Overview
Helpful code snippets will show up in this column.
curl https://app.asana.com/api/1.0/users/me \
-H "Authorization: Bearer 0/a7f89e98g007e0s07da763a"
The Asana API is a RESTful interface, providing programmatic access to much of the data in the system. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses. This makes it easy to communicate from a wide variety of environments: command-line utilities, gadgets, and even the browser URL bar itself.
The API accepts JSON or form-encoded content in requests and returns JSON content in all of its responses, including errors. Only the UTF-8 character encoding is supported for both requests and responses.
Notes on Pagination
Pagination is an important concept when working with queries for multiple objects. Requests with large result sets may timeout or be truncated; therefore, pagination is strongly encouraged to ensure both you and your users have the best experience when using the Asana API.
Happy coding!
Object Hierarchy
Asana is a work tracking and collaboration tool. This guide is designed to give developers a brief overview of how Asana is structured. It’s not meant to be exhaustive and may be too basic for experienced Asana users. The intention is to describe the fundamental elements of Asana to help you scope apps and avoid common points of confusion.
How work is organized
Tasks
Tasks are the basic unit of action in Asana. Tasks have many fields including a single assignee, name, notes, followers (i.e. collaborators), likes, and comments (among others). Tasks inherit custom fields from their parent project(s). Custom fields values are set for each individual task.
In addition to standard Create / Read / Update / Delete operations, there are a few things to watch out for when working with tasks:
- Tasks can be orphaned and belong to no projects, they can belong to one project, or they can be multi-homed across two or more projects. The
memberships
field is a collection of the projects with which the task is associated. - Tasks can be multi-homed as subtasks. For example, task A can be in project B and the same task A can also be a subtask of task C.
Projects
A project is a collection of tasks that can be viewed as a list, board, timeline, and calendar. Projects can only exist in a single organization or workplace and only belong to a single team. Projects can be public in the team or private to project members. Among the many fields associated with projects, they can have global (shared across the organization) or local (project-specific) custom fields. A project’s custom fields will be displayed on each task within the project.
Portfolios
Portfolios are collections of projects (or other portfolios). Custom fields can be added to portfolios in addition to standard fields that are displayed on every portfolio. These fields provide a high-level overview of the status of each project within the portfolio.
Sections
A section is a group of tasks within a project. Sections let you divide tasks into categories, workflow stages, priorities, and more.
Subtasks
A subtask is exactly the same as tasks in a project except that one (and only one) of its parents is a task (although subtasks can also simultaneously be organized into projects). To check if a task has a subtask, include the num_subtasks
field when fetching the parent task.
Things to note when working with subtasks:
- Subtasks do not inherit the projects of their parent tasks.
- There can be up to 5 levels of subtasks below a task. We do not recommend making sub-subtasks.
- There is no way to fetch all subtasks of all tasks in a project in a single request.
How users are organized
Workspaces
A workspace is the highest-level organizational unit in Asana. All projects, tasks, and teams have an associated workspace.
Organizations
An organization is a special kind of workspace that represents a company. Organizations connect all the employees at a company using Asana in a single space based on the company’s shared email domain. In an organization, you can group your projects into teams.
Teams
Teams are a subset of users in an organization who collaborate on projects together. Every project in an organization is associated with one team. Team messages are not currently available in the API.
Users
A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks. Asana accounts are free and tied to individuals; Asana accounts grant access to one or more shared Workspaces and Organizations to collaborate with other Asana users.
Guest Users
Users can invite clients, contractors, customers, or anyone else who does not have an email address at an approved Organization email domain. These users join as Organization Guests. Guests have limited access in an Organization -- they can only see what’s explicitly shared with them.
Note: it can be advantageous to use guests to create bot accounts. Due to the access restrictions, bots created from a guest account Personal Access Token can be given fine-grained access to only the data that it needs to use.
Authentication
Asana supports a few methods of authenticating with the API. Simple cases are usually handled with a Personal Access Token, while multi-user apps utilize OAuth.
"Authorization: Bearer ACCESS_TOKEN"
- OAuth 2.0 We require that applications designed to access the Asana API on behalf of multiple users implement OAuth 2.0.
- Personal Access Token Personal Access Tokens are designed for accessing the API from the command line or from personal applications.
OAuth
Most of the time, OAuth is the preferred method of authentication for developers, users, and Asana as a platform. If you're new to OAuth, take a moment to learn about it here. It's not as scary as you might think!
In addition to learning about how to use OAuth on the Asana platform here, feel free to take a look at the official OAuth spec!
At its core, OAuth is a mechanism for applications to access the Asana API on behalf of a user without the application having access to the username and password. Instead, apps get a token which they can use with their own application credentials to make API calls.
What is OAuth?
If you're using a library to handle this or already understand OAuth and have registered an OAuth application, you may want to skip ahead to the quick reference.
If you have not already, you will need to register an application. Take note of the client ID, an application's username, and the client secret, an application's password (protect it like one)!
A user will arrive at your application and click a button that says "Connect with Asana."
This takes the customer to the User Authorization Endpoint, which displays a page asking the user if they would like to grant access to your third-party application.
If the customer clicks "Allow", they are redirected back to the application, bringing along a special code as a query parameter. (We are assuming the Authorization Code Grant flow, which is the most common.)
The application can now use the Token Exchange Endpoint to exchange the code, together with the Client Secret, for a Bearer Token (which lasts an hour) and a Refresh Token (which can be used to fetch new Bearer Tokens when the current one expires).
The application can make requests of the API using this Bearer Token for the next hour.
Once the Bearer Token expires, the application can again use the Token Exchange Endpoint to exchange the Refresh Token for a new Bearer Token. (This can be repeated for as long as the user has authorized the application.)
We definitely recommend using a library to take care of the details of OAuth, but hopefully this helps demystify the process somewhat.
Register an Application
You must first register your application with Asana to receive a client ID and client secret. Fortunately, this process is fast and easy: visit your Account Settings dialog, click the Apps tab, and "Add New Application".
You must supply your new application with:
- App Name - A name for your application. A user will see this name when your application requests permission to access their account as well as when they review the list of apps they have authorized.
- App URL - The URL where users can access your application or, in the case of native applications, this can be a link to setup or support instructions. Note that this URL must start with "http" or "https".
- Redirect URL - As described in the OAuth specification, this is where the user will be redirected upon successful
or failed authentications. Native or command line applications should use the special redirect URL
urn:ietf:wg:oauth:2.0:oob
. For security reasons, non-native applications must supply a "https" URL (more on this below). - Icon - Optionally, you can upload an icon to enhance the recognizability of the application when users are authenticating.
Note that all of these attributes can be changed later, so don't worry too much right away.
Once you have created an app, the details view will include a Client ID, needed to uniquely identify your app to the Asana API, as well as a Client Secret.
Note Your Client Secret is a secret, it should never be shared with anyone or checked into source code that others could gain access to.
Quick Reference
- Applications can be created from the "Apps" tab of your account settings, where you will find your Client ID and Client Secret.
- The endpoint for user authorization is
https://app.asana.com/-/oauth_authorize
- The endpoint for token exchange is
https://app.asana.com/-/oauth_token
- The endpoint for revoking a token is
https://app.asana.com/-/oauth_revoke
- Asana supports the Authorization Code Grant flow.
- Once an access token has been obtained your application can make calls on behalf of the user
User Authorization Endpoint
Request
Send a user to oauth_authorize
<a href="https://app.asana.com/-/oauth_authorize
?client_id=753482910
&redirect_uri=https://my.app.com
&response_type=code
&state=thisIsARandomString
&code_challenge_method=S256
&code_challenge=671608a33392cee13585063953a86d396dffd15222d83ef958f43a2804ac7fb2
&scope=default">Authenticate with Asana</a>
Your app redirects the user to https://app.asana.com/-/oauth_authorize
, passing parameters along as a standard query string:
Parameter | Description | |
client_id | required The Client ID uniquely identifies the application making the request. | |
redirect_uri | required The URI to redirect to on success or error. This must match the Redirect URL specified in the application settings. | |
response_type | required Must be either code or id_token , or the space-delimited combination code id_token . | |
state | required Encodes state of the app, which will be returned verbatim in the response and can be used to match the response up to a given request. | |
code_challenge_method | PKCE The hash method used to generate the challenge. Typically S256 . | |
code_challenge | PKCE The code challenge used for PKCE. | |
scope | optional A space-delimited set of one or more scopes to get the user's permission to access. Defaults to the default OAuth scope if no scopes are specified. |
Response
If either the client_id
or redirect_uri
do not match, the user will simply see a plain-text error. Otherwise,
all errors will be sent back to the redirect_uri
specified.
The user then sees a screen giving them the opportunity to accept or reject the request for authorization. In either
case, the user will be redirected back to the redirect_uri
.
User is redirected to the redirect_uri
https://my.app.com?code=325797325&state=thisIsARandomString
Parameter | Description | |
code | If response_type=code in the request, this is the code your app can exchange for a token | |
state | The state parameter that was sent with the authorizing request |
Preventing CSRF Attacks
The state
parameter is necessary to prevent CSRF attacks. As such, you must check that the state
is the same in this response as it was in the request. If the state
parameter is not used, or not tied to the user's session, then attackers can initiate an OAuth flow themselves before tricking a user's browser into completing it. That is, users can unknowingly bind their accounts to an attacker account.
Requirements
The state
parameter must contain an unguessable value tied to the user's session, which can be the hash of something tied to their session when the OAuth flow is first initiated (e.g., their session cookie). This value is then passed back and forth between the client application and the OAuth service as a form of CSRF token for the client application.
Additional Resources
- OAuth 2.0 Security Best Current Practice
- Prevent Attacks and Redirect Users with OAuth 2.0 State Parameters
OAuth Scopes
The Asana API supports a small set of OAuth scopes you can request using the
scope
parameter during the user authorization step of your authentication
flow. Multiple scopes can be requested at once as a space-delimited list of
scopes. An exhaustive list of the supported scopes is provided here:
Scope | Access provided | |
default | Provides access to all endpoints documented in our API reference. If no scopes are requested, this scope is assumed by default. | |
openid | Provides access to OpenID Connect ID tokens and the OpenID Connect user info endpoint. | |
Provides access to the user's email through the OpenID Connect user info endpoint. | ||
profile | Provides access to the user's name and profile photo through the OpenID Connect user info endpoint. |
Token Exchange Endpoint
Request
When your app receives a code from the authorization endpoint, it can now be exchanged for a proper token.
If you have a client_secret
, this request should be sent from your secure server.
The browser should never see your client_secret
.
App sends request to oauth_token
{
"grant_type": "authorization_code",
"client_id": "753482910",
"client_secret": "6572195638271537892521",
"redirect_uri": "https://my.app.com",
"code": "325797325",
"code_verifier": "fdsuiafhjbkewbfnmdxzvbuicxlhkvnemwavx"
}
Your app should make a POST
request to https://app.asana.com/-/oauth_token
,
passing the parameters as part of a standard form-encoded post body.
Parameter | Description | |
grant_type | required One of authorization_code or refresh_token . See below for more details. | |
client_id | required The Client ID uniquely identifies the application making the request. | |
client_secret | required The Client Secret belonging to the app, found in the details pane of the developer console. | |
redirect_uri | required Must match the redirect_uri specified in the original request. | |
code | required This is the code you are exchanging for an authorization token. | |
refresh_token | sometimes required If grant_type=refresh_token this is the refresh token you are using to be granted a new access token. | |
code_verifier | PKCE This is the string previously used to generate the code_challenge. |
The token exchange endpoint is used to exchange a code or refresh token for an access token.
Response
In the response, you will receive a JSON payload with the following parameters:
{
"access_token": "f6ds7fdsa69ags7ag9sd5a",
"expires_in": 3600,
"token_type": "bearer",
"refresh_token": "hjkl325hjkl4325hj4kl32fjds",
"data": {
"id": "4673218951",
"name": "Greg Sanchez",
"email": "gsanchez@example.com"
}
}
Parameter | Description | |
access_token | The token to use in future requests against the API | |
expires_in | The number of seconds the token is valid, typically 3600 (one hour) | |
token_type | The type of token, in our case, bearer | |
refresh_token | If exchanging a code, a long-lived token that can be used to get new access tokens when old ones expire. | |
data | A JSON object encoding a few key fields about the logged-in user, currently id , name , and email . |
Authorization Code Grant
To implement the Authorization Code Grant flow (the most typical flow for most applications), there are three steps:
Send the user to the authorization endpoint so that they can approve access of your app to their Asana account
Receive a redirect back from the authorization endpoint with a code embedded in the parameters
Exchange the code via the token exchange endpoint for a
**refresh_token**
and, for convenience, an initialaccess_token
.When the short-lived
access_token
expires, the**refresh_token**
can be used with the token exchange endpoint, without user intervention, to get a freshaccess_token
.
The token that you have at the end can be used to make calls to the Asana API on the user's behalf.
Proof Key for Code Exchange (PKCE) OAuth Extension
User Authorization Endpoint
{
...
"code_challenge": "671608a33392cee13585063953a86d396dffd15222d83ef958f43a2804ac7fb2",
"code_challenge_method": "S256"
}
Token Exchange Endpoint
{
...
"code_verifier": "fdsuiafhjbkewbfnmdxzvbuicxlhkvnemwavx"
}
PKCE proves the app that started the authorization flow is the same app that finishes the flow. You can read more about it here.
Here's what you need to know:
Whenever a user wants to OAuth with Asana, your app server should generate a random string called the
code_verifier
. This string should be saved to the user (as everycode_verifier
should be unique per user). This should stay on the app server and only be sent to the Token Exchange Endpoint.Your app server will hash the
code_verifier
with SHA256 to get a string called thecode_challenge
. Your server will give the browser only thecode_challenge
&code_challenge_method
. Thecode_challenge_method
should be the string "S256" to tell Asana we hashed with SHA256. More specifically, code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))).The browser includes
code_challenge
&code_challenge_method
when redirecting to the User Authorization Endpoint.The app server should include the
code_verifier
in it's request to the Token Exchange Endpoint.
Asana confirms that hashing the code_verifier
with the code_challenge_method
results in the code_challenge
. This
proves to Asana the app that hit the User Authorization Endpoint is the same app that hit the Token Exchange
Endpoint.
Secure Redirect Endpoint
As the redirect from the authorization endpoint in either grant procedure contains a code that is secret between Asana's
authorization servers and your application, this response should not occur in plaintext over an unencrypted http
connection.
Because of this, we enforce the use of https
redirect endpoints for application registrations.
For non-production or personal use, you may wish to check out stunnel, which can act as a proxy to receive an encrypted connection, decrypt it, and forward it on to your application. For development work, you may wish to create a self-signed SSL/TLS certificate for use with your web server; for production work we recommend purchasing a certificate from a certificate authority. A short summary of the steps for each of these processes can be read here.
Your application will need to be configured to accept SSL/TLS connections for your redirect endpoint when users become authenticated, but for many apps, this will simply require a configuration update of your application server. Instructions for Apache and Nginx can be found on their respective websites, and most popular application servers will contain documentation on how to proceed.
Token Deauthorization Endpoint
Request
An authorization token can be deauthorized or invalidated by making a request to Asana's API.
Your app should make a POST
request to https://app.asana.com/-/oauth_revoke
,
passing the parameters as part of a standard form-encoded post body.
Parameter | Description | |
client_id | required The Client ID uniquely identifies the application making the request. | |
client_secret | required The Client Secret belonging to the app, found in the details pane of the developer console. | |
token | required The Refresh Token that should be deauthorized. Bearer Tokens will be rejected. |
The body should include a valid Refresh Token, which will cause the Refresh Token and any Associated Bearer Tokens to be deauthorized. Bearer Tokens are not accepted in the request body since a new Bearer Token can always be obtained by reusing an authorized Refresh Token.
Response
A successful response with a 200 status code indicates that the token was deauthorized or not found. An unsuccessful response with a 400 status code will be returned if the request was malformed due to missing any required fields or specifying an invalid token (such as a bearer access token).
Personal Access Token
Personal Access Tokens (PATs) are a useful mechanism for accessing the API in scenarios where OAuth would be considered overkill, such as access from the command line and personal scripts or applications. A user can create many, but not unlimited, personal access tokens. When creating a token you must give it a description to help you remember what you created the token for.
Personal Access Tokens should be used similarly to OAuth access tokens when accessing the API, passing them in the Authorization header.
Example cURL request authenticating with a PAT
curl https://app.asana.com/api/1.0/users/me \
-H "Authorization: Bearer ACCESS_TOKEN"
You can generate a Personal Access Token from the Asana developer console. See the Authentication Quick Start for detailed instructions on getting started with PATs.
You should regularly review the list of personal access tokens you have created and deauthorize those that you no longer need.
Remember to keep your tokens secret; treat them just like passwords! They act on your behalf when interacting with the API. Don't hardcode them into your programs. Instead, opt to use them as environment variables.
OpenID Connect
Asana also supports the OpenID Connect protocol for authenticating Asana users with your
applications. This means that, in addition to the normal code
and token
response types for the OAuth flow, you can
also use the id_token
response type.
For this response type, you are not granted an access token for the API, but
rather given a signed Json Web Token containing the user's ID along with some metadata. If you want
to allow users to log into your services using their Asana account, the OpenID Connect protocol is an ideal way to
authenticate an Asana user. To obtain an ID token, you must request the openid
scope during the authentication flow.
It is also possible to obtain an ID token alongside an authorization code in the authorization code grant
flow by using the (space-delimited) code id_token
response type. If you do, the redirect parameters will include
the ID token in addition to everything you would normally receive.
To access additional information about the user in a standardized format, we also expose a
user info endpoint that can provide the user's name,
email address, and profile photo. This data is available by making a GET
request to
https://app.asana.com/api/1.0/openid_connect/userinfo
with an OAuth access token that has the openid
scope.
Depending on the scopes tied to that token, you will receive different pieces of data. Refer to our
list of OAuth scopes to determine which additional scopes you need to get the data you want.
Metadata about our OpenID Connect implementation is also made available through OpenID Connect's
discovery protocol. Making an unauthenticated GET
request to https://app.asana.com/api/1.0/.well-known/openid-configuration
will provide all the details of our
implementation necessary for you to use OpenID Connect with Asana's API.
Errors
Missing authorization header
GET https://app.asana.com/api/1.0/users/me HTTP/1.1
HTTP/1.1 401 Not Authorized
{
"errors": [
{
"message": "Not Authorized"
}
]
}
Sadly, sometimes requests to the API are not successful. Failures can occur for a wide range of reasons. In all cases, the API should return an HTTP Status Code that indicates the nature of the failure (below), with a response body in JSON format containing additional information.
In the event of a server error the response body will contain an error phrase. These phrases are automatically generated using the node-asana-phrase library and can be used by Asana support to quickly look up the incident that caused the server error.
Bad request parameters
GET https://app.asana.com/api/1.0/tasks HTTP/1.1
Authorization: Bearer <personal_access_token>
HTTP/1.1 400 Bad Request
{
"errors": [
{
"message": "workspace: Missing input"
}
]
}
Asana had a problem
GET https://app.asana.com/api/1.0/users/me HTTP/1.1
Authorization: Bearer <personal_access_token>
HTTP/1.1 500 Server Error
{
"errors": [
{
"message": "Server Error",
"phrase": "6 sad squid snuggle softly"
}
]
}
Code | Meaning | Description | |
200 | Success | If data was requested, it will be available in the data field at the top level of the response body. | |
201 | Created (for object creation) | Its information is available in the data field at the top level of the response body. The API URL where the object can be retrieved is also returned in the Location header of the response. | |
400 | Bad Request | This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again. | |
401 | Unauthorized | A valid authentication token was not provided with the request, so the API could not associate a user with the request. This error also occurs if an app makes a request to a workspace that has disabled that particular app. | |
402 | Payment Required | The request was valid, but the queried object or object mutation specified in the request is only available to premium organizations and workspaces. | |
403 | Forbidden | The authentication and request syntax was valid but the server is refusing to complete the request. This can happen if you try to read or write to objects or properties that the user does not have access to. | |
404 | Not Found | Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist. | |
429 | Too Many Requests | You have exceeded one of the enforced rate limits in the API. See the documentation on rate limiting for more information. | |
451 | Unavailable For Legal Reasons | This request was blocked for legal reasons, commonly caused by embargoed IP addresses. | |
500 | Internal Server Error | There was a problem on Asana's end. |
In the event of an error, the response body will contain an errors field at the top level. This contains an array of at least one error object, described below:
Example | Description | |
message | project: Missing input Message providing more detail about the error that occurred, if available. | |
phrase | 6 sad squid snuggle softly 500 errors only. A unique error phrase which can be used when contacting developer support to help identify the exact occurrence of the problem in Asana's logs. |
Rate Limits
To protect the stability of the API and keep it available to all users, Asana enforces multiple kinds of rate limiting. Requests that hit any of our rate limits will receive a 429 Too Many Requests
response, which contains the standard Retry-After
header indicating how many seconds the client should wait before retrying the request.
Limits are allocated per authorization token. Different tokens will have independent limits.
The client libraries respect the rate-limited responses and will wait the appropriate amount of time before automatically retrying the request, up to a configurable maximum number of retries.
Standard Rate Limits
Request
GET https://app.asana.com/api/1.0/users/me HTTP/1.1
Authorization: Bearer <personal_access_token>
Response
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 30
{
"errors": [
{
"message": "You've made too many requests and hit a rate limit. Please retry after the given amount of time."
}
]
}
Our standard rate limiter imposes a quota on how many requests can be made in a given window of time. Our limits are based on minute-long windows, and differ depending on whether the domain is premium or not. We may change these quotas or add new quotas (such as maximum requests per hour) in the future.
Domain type | Maximum requests per minute | |
Free | 150 | |
Premium | 1500 |
In addition, calls to the search API are limited to 60 requests per minute. The duplication endpoints are limited to 5 concurrent jobs.
Although the quota is defined per minute, it is evaluated more frequently than once per minute, so you may not need to wait for a full minute before retrying your request. For requests rejected by this limiter, the Retry-After
header has the result of this calculation.
Requests rejected by this limiter still count against the quotas so that ignoring the Retry-After
header will result in fewer and fewer requests being accepted during the subsequent tine windows.
Concurrent Request Limits
In addition to limiting the total number of requests in a given time window, we also limit the number of requests being handled at any given instant. We may change these limits or add new limits in the future.
Request type | Maximum concurrent requests | |
Reads GET | 50 | |
Writes POST, PUT, PATCH, DELETE | 15 |
For example, if you have 50 read requests in-flight and attempt to make another read request, the API will return a 429 Too Many Requests
error. The read and write limits are independent of each other, so the number of read requests you make at one time will have no impact on the number of write requests you can make.
Responses for requests rejected by this concurrent request limiter will contain a Retry-After
header specifying a duration long enough (in seconds) such that the other in-flight requests are guaranteed to have either completed or timed out.
Cost Limits
Objects in Asana are connected to each other in a graph. Some examples of links in this graph are:
- a task object is linked to a user object as the assignee
- a user is linked to the projects it's following
- a tag is linked to all its tasks
- a task is linked to all its subtasks
- a task is linked to all its custom field values
Depending on the kind of requests you make to our API, our servers have to traverse different parts of the graph. The sizes of these parts directly influence how expensive it is for our servers to build the API responses. For example, fetching just the name and gid
of a task requires very few resources and no traversal of the graph, but fetching all tasks in a project and all their attributes (assignee, followers, custom fields, likes) can require following several thousand links in the graph.
Because there can be a wide range in the cost of any given API request in terms of the computational resources and database load, the standard rate limits are not always enough to maintain stability of the API. In the past, when we’ve received bursts of expensive requests, our typical course of action has been to block the offending authorization token and reject all future requests, resulting in confusion for both the user and the app developer. Instead, to protect against the extreme cases where API requests require inordinate traversal of the graph, we impose an additional limit based on the computational cost.
The cost we associate with a request isn't equivalent to the number of links in the subset of the graph involved, but it is roughly proportional. The cost of a request is calculated after the response has been fully built and we know how much data we needed to fetch from our databases to build it. This cost is then deducted from a quota, and the response is returned. Because the cost of a request is not known until we’ve built the response, we allow this deduction to result in a net negative quota. The request that causes the quota to become negative will receive the expected response and not be rejected.
When a request is received, if the remaining quota is not positive, the new request is rejected with a 429 Too Many Requests
. As with the standard rate limits, this quota is defined per-minute but is updated on a more frequent interval. The Retry-After
header will specify how long you must wait for the quota to become positive again.
The vast majority of developers will be unaffected by the cost limit, and the quota is set sufficiently high that it only affects users making requests that would compromise the stability of the API. Rather than unconditionally blocking their token from the API, this cost limiter will permit them to continue operation at a slower but safe and stable rate.
Common issues & pathological cases to avoid
- Deeply nested subtasks (i.e. working sub-subtasks, sub-sub-subtasks, etc.)
- Projects with too many tasks (i.e projects with over 1,000 tasks)
- Too many unreadable tags in a workspace
- Domains with too many projects for typeahead to work well
- Undeleted webhooks
Rich Text
Note: we are actively adding new rich texts formats to various objects in Asana. This may break existing apps. New apps should be built using parsers and display logic that is forward compatible with the forthcoming rich text formats. More details and ongoing updates can be found in this post in the developer forum.
Example Rich Text
<body>All these new tasks are <em>really</em> getting disorganized, so <a data-asana-gid="4168112"/> just made the new <a data-asana-gid="5732985"/> project to help keep them organized. <strong>Everyone</strong> should start using the <a data-asana-gid="6489418" data-asana-project="5732985"/> when adding new tasks there.</body>
The web product offers a number of rich formatting features when writing task notes, comments, project descriptions, and project status updates. These features include bold, italic, underlined, and monospaced text, as well as bulleted and numbered lists. Additionally, users can "@-mention" other users, tasks, projects, and many other objects within Asana to create links.
The rich text field name for an object is equivalent to its plain text field name prefixed with html_
. The following object types in Asana support rich text:
Object | Plain text field | Rich text field | |
Tasks | notes | html_notes | |
Projects | notes | html_notes | |
Stories | text | html_text | |
Project status updates | text | html_text | |
Project briefs | text | html_text | |
Teams | description | html_description |
Reading rich text
Python
from lxml import etree
html_text = "<body>...</body>"
root = etree.HTML(html_text)
user_ids = root.xpath('//a[@data-asana-type="user"]/@data-asana-gid')
for user_id in user_ids:
print(user_id)
Java
import com.jcabi.xml.XML;
import com.jcabi.xml.XMLDocument;
import java.util.List;
XML root = new XMLDocument("<body>...</body>");
List<String> userIds = root.xpath("//a[@data-asana-type=\"user\"]/@data-asana-gid");
for (String userId : userIds) {
System.out.println(userId);
}
JavaScript
var htmlText = '<body>...</body>'
var parser = new DOMParser()
var doc = parser.parseFromString(htmlText, "text/html")
var iterator = doc.evaluate(
'//a[@data-asana-type="user"]/@data-asana-gid', doc, null, XPathResult.ORDERED_NODE_ITERATOR_TYPE)
var node = iterator.iterateNext()
while (node) {
console.log(node.nodeValue);
node = iterator.iterateNext();
}
Rich text in the API is formatted as an HTML fragment, which is wrapped in a root <body>
tag. Rich text is guaranteed
to be valid XML; there will always be a root element, all tags will be closed, balanced, and case-sensitive, and all
attribute values will be quoted. The following is a list of all the tags that are currently returned by the API:
Tag | Meaning in Asana | |
<body> | None | |
<strong> | Bold text | |
<em> | Italic text | |
<u> | Underlined text | |
<s> | Strikethrough text | |
<code> | Monospaced text | |
<ol> | Ordered list | |
<ul> | Unordered list | |
<li> | List item | |
<a> | Link |
In addition, the following tags are supported in the rich text of Project Briefs:
Tag | Meaning in Asana | |
<h1> , <h2> | Header | |
<hr> | Horizontal rule | |
<table> , <tr> , <td> | Table | |
<img> | Inline image | |
<object type="application/vnd.asana.external_media"> | External media embed (iframe) | |
<object type="application/vnd.asana.project_milestones"> | List of milestones | |
<object type="application/vnd.asana.project_goals"> | List of goals |
Note: Please note that the Project Brief API and enhanced rich text features are in preview, and are expected to change. The above lists can expand as new features are introduced to the Asana web product. Treat rich text as you would treat arbitrary HTML, and ensure that your code doesn't break when it encounters a tag not on this list.
Links
While links are easy to understand when users view the rendered in the Asana web product, an <a>
tag and its href
alone are insufficient to programmatically understand what the target of the link is. This is confused further by the fact that the formats of these links are frequently ambiguous. For example, an @-mention to a user generates a link to their "My Tasks", which looks identical to a link to a normal project.
Because of this, the API will return additional attributes in <a>
tags to convey meaningful information about the target. The following is a complete list of attributes we may return inside an <a>
tag, in addition to the usual href
:
Meaning | ||
data-asana-accessible | Boolean, representing whether or not the linked object is accessible to the current user. If the resource is inaccessible, no other data-asana-* attributes will be included in the tag. | |
data-asana-dynamic | Boolean, represents if contents of the a tag is the canonical name of the object in Asana. If you want to set custom text that links to an Asana object, set data-asana-dynamic="false" when creating the tag. | |
data-asana-type | The type of the referenced object. One of user , task , project , tag , conversation , project_status , team , or search . | |
data-asana-gid | The GID of the referenced object. If the referenced object is a user, this is the user's GID. | |
data-asana-project | If the type of the referenced object is a task, and the link references that task in a particular project, this is the GID of that project. | |
data-asana-tag | If the type of the referenced object is a task, and the link references that task in a particular tag, this is the GID of that tag. |
Here are some examples of how this behavior manifests:
- Suppose a user with a name of "Tim" and a user GID of
"53421"
is @-mentioned. This will create a link to their "My Tasks" which is a project with a GID of"56789"
- The raw link generated in Asana will be
https://app.asana.com/0/56789/list
. - The
<a>
tag returned in the API will be<a href="https://app.asana.com/0/56789/list" data-asana-accessible="true" data-asana-dynamic="true" data-asana-type="user" data-asana-gid="54321">@Tim</a>
.
- The raw link generated in Asana will be
- Suppose a link to a task with name "Buy milk" and GID
"1234"
being viewed in a project with GID"5678"
is copied from the address bar and pasted into a comment.- The raw link generated in Asana will be
https://app.asana.com/0/5678/1234
. - The
<a>
tag returned in the API will be<a href="https://app.asana.com/0/5678/1234" data-asana-accessible="true" data-asana-dynamic="true" data-asana-type="task" data-asana-gid="1234" data-asana-project="5678">Buy milk</a>
- The raw link generated in Asana will be
- Suppose another user @-mentions a project with GID
"5678"
that is private and not visible to you in the web product.- The raw link generated in Asana will be
https://app.asana.com/0/5678/list
. - The
<a>
tag returned in the API will be<a href="https://app.asana.com/0/5678/list" data-asana-accessible="false" data-asana-dynamic="true">Private Link</a>
- The raw link generated in Asana will be
Here's an example of what a complete rich comment might look like in the API:
<body>All these new tasks are <em>really</em> getting disorganized, so <a href="https://app.asana.com/0/4168466/list" data-asana-accessible="true" data-asana-dynamic="true" data-asana-type="user" data-asana-gid="4168112">@Tim Bizzaro</a> just made the new <a href="https://app.asana.com/0/5732985/list" data-asana-accessible="true" data-asana-dynamic="true" data-asana-type="project" data-asana-gid="5732985">Work Requests</a> project to help keep them organized. <strong>Everyone</strong> should start using the <a href="https://app.asana.com/0/5732985/6489418" data-asana-accessible="true" data-asana-dynamic="true" data-asana-type="task" data-asana-gid="6489418" data-asana-project="5732985">Request template</a> when adding new tasks there.</body>
Inline images
Reading an inline image
<img
data-asana-gid="1234"
src="..."
data-src-width="..."
data-src-height="..."
data-thumbnail-url="..."
data-thumbnail-width="..."
data-thumbnail-height="..."
[data-asana-deleted="true"]
data-asana-type="attachment"
alt="title of the image"
style="...">
Rich text can contain inline images. The image is stored as an attachment.
If the attachment has been deleted, the HTML will contain data-asana-deleted="true"
, and some of the other attributes, such as the URLs, will not be present.
The image URLs expire after a few minutes.
External media embeds (iframes)
Reading an external media embed
<object
type="application/vnd.asana.external_media"
data-asana-type="attachment"
data-asana-gid="1234"
data="{embeddable-url}"
>
<a href="{linkable-url}">{linkable-url}</a>
</object>
You can embed Figma, Loom, YouTube, etc. within rich text. The effect is similar to an HTML iframe. There is a fixed, predefined list of external media sources that are supported: Adobe XD, Canva, Figma, InVision, Loom, LucidChart, Miro, Vimeo, Whimsical, and Wistia.
Milestones and goals
Reading milestones
<object
type="application/vnd.asana.project_milestones"
data-asana-gid="<gid-of-project>"
data-asana-type="project">[...]</object>
Reading goals
<object
type="application/vnd.asana.project_goals"
data-asana-gid="<gid-of-project>"
data-asana-type="project">[...]</object>
Rich text can contain:
- A list of all milestones in the specified project
- A list of all goals that are supported by the specified project
When reading, the inner HTML of the <object>
tag will contain a list of the first five milestones/goals, followed by "..." if there are more than five in total. When writing, the inner HTML
is ignored and can be empty.
Reading defensively
Custom handling external media
<object>
const richText = '<body><object style="display:block" type="application/vnd.asana.external_media" data="https://www.youtube.com/embed/VqnMA3K6-e0"><a href="https://www.youtube.com/embed/VqnMA3K6-e0">https://www.youtube.com/embed/VqnMA3K6-e0</a></object></body>'
const parser = new DOMParser();
const richTextDocument = parser.parseFromString(richText, "text/html");
const objects = richTextDocument.querySelectorAll("object");
for (let i = 0; i < objects.length; i++) {
replacement = null;
switch(objects[i].type) {
case "application/vnd.asana.external_media":
replacement = richTextDocument.createElement('iframe');
replacement.width = 420;
replacement.height = 315;
replacement.src = objects[i].data;
break;
default:
replacement = richTextDocument.createElement('div');
replacement.innerHtml = objects[i].innerHTML;
}
if (replacement) {
objects[i].parentElement.replaceChild(replacement, objects[i]);
}
}
richTextDocument.body.childNodes.forEach (child => {
document.body.append(child);
});
We are actively adding new rich text formats to various objects in Asana. An existing app will break if not built defensively. Apps should use parsers and display logic that is forward compatible with unknown future rich text formats.
To do this, Asana provides two mechanisms to parse and display tags that the app doesn't explicitly support:
- Defaults that render in a WebView
- Guidelines for how to handle new tags
You can read more about rich text changes in this forum post.
Render rich text in a WebView
You can expect the rich text HTML to render reasonably in a WebView if you apply the following CSS style to the
wrapping DOM node: overflow-wrap: break-word; white-space: pre-wrap;
. This won't look exactly like it does in Asana,
but it will ensure users read it in the same way.
How to handle new tags (no WebView)
An <object>
with an unhandled type
Render the <object>
tag as a block and render the contained HTML with the same behavior as if it were not inside an
<object>
. We will never send an <object>
tag nested inside another <object>
tag.
An <img>
Fall back to either the alt text or the src
link if the image can’t be displayed. Wrap the text with newlines like \n<alt text>\n
since <img>
tags are blocks.
Empty elements except <img>
and <hr>
Empty tags are described here. It is ok to omit them. Render as a new line if the tag is a block.
Other semantic non-terminal tags
Ignore the tag and render whatever is inside. Follow the HTML convention for whether it is a block or not.
Writing rich text
When writing rich text to the API, you must provide similarly structured, valid XML. The text must be wrapped in a <body>
tag, all tags must be closed, balanced, and match the case of supported tags, and attributes must be quoted. Invalid XML, as well as unsupported tags, will be rejected with a 400 Bad Request
error. Only <a>
tags support attributes, and any attributes on other tags will be similarly rejected.
Links
For <a>
tags specifically, to make it easier to create @-mentions through the API, we only require that you provide the GID of the object you wish to reference. If you have access to that object, the API will automatically generate the appropriate href
and other attributes for you. For example, to create a link to a task with GID "123"
, you can send the tag <a data-asana-gid="123"/>
which will then be expanded to <a href="https://app.asana.com/0/0/123/f" data-asana-accessible="true" data-asana-dynamic="true" data-asana-type="task" data-asana-gid="123">Task Name</a>
. You can also generate a link to a task in a specific project or tag by including a data-asana-project
or data-asana-tag
attribute in the <a>
tag. All other attributes, as well as the contents of the tag, are ignored.
To keep the contents of your tag and make a custom vanity link, include the property data-asana-dynamic="false"
when setting the contents of the tag. You would send <a data-asana-gid="123" data-asana-dynamic="false">This is some custom text!</a>
and receive <a data-asana-accessible="true" data-asana-dynamic="false" data-asana-type="task" data-asana-gid="123">This is some custom text!</a>
If you do not have access to the referenced object when you try to create a link, the API will not generate an href
for you, but will instead look for an href
you provide. This allows you to write back <a>
tags unmodified even if you do not have access to the resource. If you do not have access to the referenced object and no href
is provided, your request will be rejected with a 400 Bad Request
error. Similarly, if you provide neither a GID nor a valid href
, the request will be rejected with the same error.
Inline images
Writing an inline image (after uploading the attachment)
<img data-asana-gid="1234">
When writing an inline image, you don't need most of the attributes; all you need is the data-asana-gid
. To write HTML that includes a new inline image:
- Upload the image as an attachment with a call to
POST /attachments
. - Make a second API call to write the rich text, using the returned GID as the
data-asana-gid
field of the<img>
tag.
External media embeds
Writing an external media embed
<object
type="application/vnd.asana.external_media"
data-asana-gid="1234"
></object>
To write rich text that contains a new external media embed:
- Create URL attachment with a call to
POST /attachments
, with{ ..., "resource_subtype": "external", "url": "<your_url>" }
. Important: Use the URL that would appear in the browser address bar (e.g.https://youtube.com/watch?v=...
), NOT the embeddable URL (e.g.https://youtube.com/embed/...
). - Make a second API call to write the rich text, using the returned GID as the
data-asana-gid
field of the<object>
tag. You don't need the inner HTML and you only need a couple of the<object>
tag attributes: All that is needed is<object type="application/vnd.asana.external_media" data-asana-gid="..."></object>
Writing defensively
When processing rich text and sending it back
It’s ok to ignore tags or attributes on tags that are unknown for rendering/processing. It’s very important to send
everything back (attributes and inner content) to avoid data loss. <object>
is an exception where it’s ok to not send
any inner content back (all inner content in <object>
will be ignored).
If you plan to write an editor
If the tag and attributes are known, but it contains unknown attributes, it must be treated as unknown.
If a tag is unknown, first determine if the tag is block or inline and render it as a block or inline atomic and non-copiable (and non-cut&paste-able) editor node (all inner content is non-editable). This is because we don’t know if the unknown node has constraints on inner content or where it can appear. The node must also keep track of all attributes and inner content to be serialized back.
Pagination
Paginating requests for object sets that may be large is highly recommended. For requests that will return large result sets the API may truncate the result or timeout attempting to gather the data. Pagination ensures a more reliable experience by limiting requests to a smaller number of objects at a time, ultimately getting you the results faster; should there be more results, the API will return an offset that will allow you to access the next page.
Strongly prefer paginated requests
For all new features in the Asana API, we're making pagination required by specifying a value for the limit parameter. Though they may return more results, our current unpaginated requests are still ultimately subject to a timeout limit, which means requests that work successfully one day may fail later due to factors such as server load and network latency.
Pagination limits provide a mechanism to specify a page size that we should always be able to serve regardless of these factors. To prevent current integrations from breaking, pagination is not enabled by default on "grandfathered" endpoints; instead, you can request paginated results by providing the optional limit parameter in your query. We will be working to deprecate requests to these endpoints in the future.
Request
curl "https://app.asana.com/api/1.0/tasks?project=1337&limit=5&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9" \
-H "Authorization: Bearer <personal_access_token>"
Response
{
"data": [
{
"id": 1000,
"name": "Task 1",
...
},
...
],
"next_page": {
"offset": "yJ0eXAiOiJKV1QiLCJhbGciOiJIRzI1NiJ9",
"path": "/tasks?project=1337&limit=5&offset=yJ0eXAiOiJKV1QiLCJhbGciOiJIRzI1NiJ9",
"uri": "https://app.asana.com/api/1.0/tasks?project=1337&limit=5&offset=yJ0eXAiOiJKV1QiLCJhbGciOiJIRzI1NiJ9"
}
}
Note that all of Asana's official client libraries support pagination by default.
When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Do note that an offset token will expire after some time, as data may have changed.
When making paginated requests you are able to page through all objects for a particular query up to 100 objects at a time. Alternatively your query will be truncated at about 1000 objects. In addition, when issuing non-paginated requests to organizations with a large number of objects queries may time out before returning. For these reasons, we recommend that you paginate all requests to the API.
Parameter | Description | |
Limit | 20 The number of objects to return per page. The value must be between 1 and 100. | |
Offset | eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9 An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not passed in, the API will return the first page of results. Note: You can only pass in an offset that was returned to you via a previously paginated request. |
This method returns paginated results for tasks from a project.
Input/Output Options
GET url params
?opt_pretty
?opt_fields=followers,assignee
PUT or POST body options
options: {
pretty: true,
fields: ["followers", "assignee"]
}
In addition to providing fields and their values in a request, you may also specify options to control how your request
is interpreted and how the response is generated. For GET requests, options are specified as URL parameters prefixed
with opt_
. For POST or PUT requests, options are specified in the body. If the body uses the application/x-www-form-urlencoded
content type, then options are prefixed with opt_
just like for GET requests. If the body uses the application/json
content type, then options are specified inside the top-level options
object
(a sibling of the data
object).
?opt_fields=name,notes&opt_pretty response
HTTP/1.1 200
{
"data": {
"name": "Make a list",
"notes": "Check it twice!",
"gid": 1224
}
}
These options can be used in combination in a single request, though some of them may conflict in their impact on the response.
Option | Description | |
pretty | Provides the response in "pretty" output. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging. | |
fields | Some requests return compact representations of objects, to conserve resources and complete the request more efficiently. Other times requests return more information than you may need. This option allows you to list the exact set of fields that the API should be sure to return for the objects. The field names should be provided as paths, described below. The gid of included objects will always be returned, regardless of the field options. |
opt_fields nesting
"data": { < this
"gid": 1001,
"name": "Feed the cat", < this.name
"workspace": { < this.workspace
"gid": 14916,
"name": "Shared Projects", < this.workspace.name
},
"followers": [{ < this.followers
"gid": 1234,
"email": "tbizarro@…", < this.followers.email
}, {
"gid": 5678,
"email": "gsanchez@…", < this.followers.email
}]
}
Some output options allow you to reference fields of objects to include in the response.
The way to specify a field is by path. A path is made up of a sequence of terms separated by the dot (.
)
operator. It takes the form this.a.b
… where this refers to an object returned at the top level of the response,
a the name of a field on a root object, b a field on a child object referred to by a, and so on.
For example, when retrieving a task or tasks, the path this.followers.email
refers to the email field of all users
mentioned in the followers
field of the task or tasks returned. See the annotated output below:
There are also some advanced operators you can use for shorter syntax in selecting fields:
(
.. |
.. )
The group operator can be used in place of any whole term in a path, and will match any of a group of terms.
this.(followers|assignee).email
will match the email
field of the assignee
object or any of the followers
.
Custom External Data
Custom external data allows a client application to add app-specific metadata to Tasks
in the API. The custom data includes a string gid
that can be used to retrieve objects and a data blob that can store
character strings.
The blob may store unicode-safe serialized data such as JSON or YAML. The external gid
is capped at 1,024 characters, while data
blobs are capped at 32,768 characters. Each object supporting external data can have one gid
and one data blob stored
with it. You can also use either or both of those fields.
The external gid
field is a good choice to create a reference between a resource in Asana and another database, such as
cross-referencing an Asana task with a customer record in a CRM, or a bug in a dedicated bug tracker. Since it is just
a unicode string, this field can store numeric IDs as well as URIs, however, when using URIs extra care must be taken
when forming queries that the parameter is escaped correctly. By assigning an external gid
you can use the notation
external:custom_id
to reference your object anywhere that you may use the original object gid
.
Note: that you will need to authenticate with Oauth, as the gid
and data are app-specific, and these fields are not
visible in the UI. This also means that external data set by one Oauth app will be invisible to all other Oauth apps.
However, the data is visible to all users of the same app that can view the resource to which the data is attached,
so this should not be used for private user data.
Parameter | Description | |
gid | "contractor_name" The external gid . Max size is 1024 characters. Can be a URI. | |
data | "{ \"time_estimate\": 3600, \"time_spent\": 1482 }" The external data blob. Max size is 32,786 characters. |
App Server
Sample Server Code (don't use in production)
An app server cannot be handled via curl.
An App Server is required for working with Webhooks and App Components. When we say "App Server", we are referring to the server Asana directly sends requests to. This is different from the service it may be connecting to in the end (like Slack or Jira).
For some features, Asana needs to send requests to an App. In order for an App to use these features, they will need to implement an App Server. App Servers are simply servers that an app controls. The server needs to be accessible via http requests, return successful response codes, and sometimes return valid json bodies to requests from Asana. Some requests will be sent from an Asana user's browser, while other requests will be sent from Asana's servers.
App Servers define their own paths. Apps will need to declare the endpoints for Asana. For Webhooks, this happens when you create a new webhook. For App Components, some are declared on App Creation while others are dynamically declared in responses to requests from Asana.
You should test/debug your App Server with a tool like Postman or Insomnia.
In short:
- App Servers need to accept
http
requests and be accessible viaurl
. - Request payloads will be
json
and App Servers should respond withjson
(if a response is needed). - Successful requests should respond with either a
200
or204
status code. Some App Components have additional error handling for codes like400
. - If an app server is down or throws a
500
, we will likely retry the request.
Error Handling and Retry
If we attempt to send a request to an App Server and we receive an error status code, or the request times out, we will retry delivery with exponential backoff.
The tolerance threshold for retries vary between Webhooks and App Components. Refer to the documentation for each for a deeper understanding.
News and Changelog
To keep up to date on changes to the API, subscribe to Platform News in our developers forum.
To subscribe to updates:
- Go to Platform News
- Hit
login
in the top right and login with your Asana account. - Go back to Platform News and change the bell icon in the top right to "Watching First Post" or "Tracking".
Here are the most recent updates:
- Returning "team" data for workspaces 2022-05-05 21:17:58.379
- A new API for Project Templates 2022-03-08 02:05:32.789
- Latest on webhook improvements 2022-02-22 18:42:58.362
- Delayed Webhooks over the weekend: 29th January 2022 2022-01-29 05:11:42.057
- Project Brief API now available as a preview 2022-01-26 17:36:58.638
Audit Log Events
Asana’s Audit Log API allows you to monitor and act upon critical events in your organization's Asana instance.
Only Service Accounts in Enterprise Domains can access Audit Log API endpoints. Authentication with a Service Account's Personal Access Token is required.
To get started with the Audit Log API, visit the API Reference.
Supported AuditLogEvents
The following tables list our currently supported AuditLogEvent event_type
s, organized by event_category
. Audit log events are retained for 90 days from the date of capture. If an event that you're looking to monitor isn't listed below, please send us your feedback.
Logins
All login events operate on the User resource type.
Event Type | Description | |
user_login_succeeded | A user successfully logged in to their Asana account. | |
user_login_failed | A user failed to log in to their Asana account. | |
user_logged_out | A user logged out of their Asana account. |
User Updates
All user events operate on the User resource type.
Event Type | Description | |
user_invited | A new user was invited to or auto-joined the workspace. | |
user_deprovisioned | A user was removed from the workspace. | |
user_reprovisioned | A deprovisioned user was added back to the workspace. | |
user_forgot_password_started | A user requested a forgot password link. | |
user_password_reset | A user's password was reset. | |
user_password_changed | A user changed their password. | |
user_two_factor_auth_enabled | A user’s two factor authentication was enabled. | |
user_two_factor_auth_disabled | A user’s two factor authentication was disabled. |
Admin Settings
All admin settings events operate on the Workspace resource type except for workspace_announcement_created
and workspace_announcement_removed
that operate on the Workspace Announcement resource type.
Event Type | Description | |
workspace_google_sso_settings_changed | The workspace's Google SSO settings were changed. | |
workspace_saml_settings_changed | The workspace's SAML settings were changed. | |
workspace_saml_url_changed | The workspace's SAML url was changed. | |
workspace_password_requirements_changed | The workspace's password strength requirements were changed. | |
workspace_force_password_reset | All users in the workspace were forced to reset their password. | |
workspace_guest_invite_permissions_changed | The workspace’s guest invite permissions were changed. | |
workspace_file_attachment_options_changed | File attachment options were enabled or disabled for the workspace. | |
workspace_default_team_privacy_settings_changed | The workspace's default team privacy settings were changed. | |
workspace_wide_reporting_enabled | Workspace wide reporting was enabled. | |
workspace_wide_reporting_disabled | Workspace wide reporting was disabled. | |
workspace_associated_email_domain_added | An email domain was added to the workspace. | |
workspace_associated_email_domain_removed | An email domain was removed from the workspace. | |
workspace_require_two_factor_auth_enabled | Two factor authentication was set as required for the workspace. | |
workspace_require_two_factor_auth_disabled | Two factor authentication was set as not required for the workspace. | |
workspace_view_links_enabled | Read-only link sharing was enabled for the workspace. | |
workspace_view_links_disabled | Read-only link sharing was disabled for the workspace. | |
workspace_default_session_duration_changed | The workspace's default session duration was changed. | |
workspace_announcement_created | An announcement was created and published in the workspace. | |
workspace_announcement_removed | An announcement was removed from the workspace. | |
workspace_form_link_authentication_required_enabled | For this workspace, form link authentication was set as required, so all viewers need to authenticate with Asana in order to open forms links. | |
workspace_form_link_authentication_required_disabled | For this workspace, form link authentication was set as not required, however authentication may still be required for individual links. Some viewers may not need to authenticate with Asana in order to open forms links. | |
workspace_personal_access_token_enabled | The workspace's global personal access token setting was enabled. | |
workspace_personal_access_token_disabled | The workspace's global personal access token setting was disabled. | |
workspace_app_admin_approval_setting_changed | The workspace's specific app approval setting was changed. | |
workspace_require_app_approvals_of_type_changed | The workspace's global app approval setting was changed. | |
workspace_form_is_embeddable_forms_enabled | Embeddable forms is enabled in admin | |
workspace_form_is_embeddable_forms_disabled | Embeddable forms is disabled in admin |
Roles
All role events operate on the User resource type.
Event Type | Description | |
user_workspace_admin_role_changed | A user’s workspace admin role was changed. | |
user_division_admin_role_changed | A user’s division admin role was changed. |
Content Export
Event Type | Resource Type | Description | |
workspace_export_started | Workspace | An organization export was started. | |
search_report_export_started | Search | A search report CSV export was started. | |
workspace_teams_export_started | Workspace | A team CSV export for the workspace was started. | |
division_teams_export_started | Division | A team CSV export for the division was started. | |
workspace_members_export_started | Workspace | A member CSV export was started for the workspace. | |
project_csv_export_started | Project | A project CSV export was started. | |
attachment_downloaded | Attachment | An attachment was downloaded. |
Access Control
Event Type | Resource Type | Description | |
project_share_link_enabled | Project | A link allowing workspace members and auto-join users to join a project was enabled. | |
project_share_link_disabled | Project | A link allowing workspace members and auto-join users to join a project was disabled. | |
project_view_link_enabled | Project | A read-only link for a project was enabled. | |
project_view_link_disabled | Project | A read-only link for a project was disabled. | |
team_privacy_settings_changed | Team | A team’s privacy settings were changed. | |
team_member_added | Team | A user was added to a team. | |
team_member_removed | Team | A user was removed from a team. | |
project_member_added | Project | A user was added to a project. | |
project_member_removed | Project | A user was removed from a project. | |
project_privacy_settings_changed | Project | A project’s privacy settings were changed. |
Apps
Event Type | Resource Type | Description | |
team_harvest_integration_enabled | Team | The Harvest time tracking integration was enabled for a team. | |
team_harvest_integration_disabled | Team | The Harvest time tracking integration was disabled for a team. | |
user_app_authorized | User | An app was authorized by a user in the workspace. | |
user_app_revoked | User | An app was deauthorized by a user in the workspace. | |
user_personal_access_token_authorized | User | A new personal access token was authorized by the user in the workspace. | |
user_personal_access_token_revoked | User | A personal access token was deauthorized by the user in the workspace. | |
service_account_created | User | A service account was created or reprovisioned. | |
service_account_deleted | User | A service account was deleted. | |
service_account_name_changed | User | A service account’s name was changed. |
Creation
Event Type | Resource Type | Description | |
team_created | Team | A new team was created. | |
attachment_uploaded | Attachment | An attachment was uploaded. |
Deletion
Event Type | Resource Type | Description | |
task_deleted | Task | A task was deleted. | |
task_permanently_deleted | Task | A task was permanently deleted. | |
task_undeleted | Task | A task was undeleted. | |
project_deleted | Project | A project was deleted. | |
project_undeleted | Project | A project was undeleted. | |
portfolio_deleted | Portfolio | A portfolio was deleted. | |
portfolio_undeleted | Portfolio | A portfolio was undeleted. | |
goal_deleted | Goal | A goal was deleted. | |
goal_undeleted | Goal | A goal was undeleted. | |
custom_field_deleted | Custom Field | A custom field was deleted. | |
custom_field_undeleted | Custom Field | A custom field was undeleted. | |
message_deleted | Message | A message was deleted. | |
message_permanently_deleted | Message | A message was permanently deleted. | |
message_undeleted | Message | A message was undeleted. | |
team_deleted | Team | A team was deleted. | |
team_undeleted | Team | A team was undeleted. | |
attachment_deleted | Attachment | An attachment was deleted. | |
attachment_undeleted | Attachment | An attachment was undeleted. | |
comment_deleted | Story | A comment was deleted. | |
comment_undeleted | Story | A comment was undeleted. | |
status_update_deleted | Status Update | A status update was deleted. | |
status_update_permanently_deleted | Status Update | A status update was permanently deleted. | |
status_update_undeleted | Status Update | A status update was undeleted. | |
task_template_deleted | Task Template | A task template was deleted. | |
task_template_undeleted | Task Template | A task template was undeleted. | |
project_template_deleted | Project Template | A project template was deleted. | |
project_template_undeleted | Project Template | A project template was undeleted. |
SCIM
Asana supports SCIM 2.0 operations at https://app.asana.com/api/1.0/scim
. Okta provides greats docs for
understanding SCIM.
Only Service Accounts in Enterprise Domains can access SCIM endpoints.
Service Provider Configuration Endpoints
HTTP Method | API Endpoint | Asana Behavior | |
GET | /ServiceProviderConfig | Read-only meta information. | |
GET | /ResourceTypes | Read-only meta information. | |
GET | /Schemas | Read-only meta information. |
User Endpoints
Examples
Request: GET https://app.asana.com/api/1.0/scim/Users?filter=userName eq "johnsmith@example.com"
Response: 200 OK
{
"Resources": [
{
"id": "1",
"name": {
"familyName": "John",
"givenName": "Smith",
"formatted": "John Smith"
},
"userName": "johnsmith@example.com",
"emails": [
{
"value": "johnsmith@example.com",
"primary": true,
"type": "work"
}
],
"active": true,
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"title": "Software Engineer",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "R&D"
}
}
],
"totalResults": 1,
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
}
Request: POST https://app.asana.com/api/1.0/scim/Users
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"userName": "johnsmith@example.com",
"name": {
"formatted": "John Smith"
},
"emails": [
{
"primary": true,
"value": "johnsmith@example.com"
}
],
"active": true,
"title": "Software Engineer",
"preferredLanguage": "en",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "R&D"
}
}
Response: 201 Created
{
"id": "1",
"name": {
"familyName": "John",
"givenName": "Smith",
"formatted": "John Smith"
},
"userName": "johnsmith@example.com",
"emails": [
{
"value": "johnsmith@example.com",
"primary": true,
"type": "work"
}
],
"active": true,
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"title": "Software Engineer",
"preferredLanguage": "en",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "R&D"
}
}
Request: PATCH https://app.asana.com/api/1.0/scim/Users/1
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "replace",
"value": {
"title": "Senior Software Engineer"
}
}
]
}
Response: 200 OK
{
"id": "1",
"name": {
"familyName": "John",
"givenName": "Smith",
"formatted": "John Smith"
},
"userName": "johnsmith@example.com",
"emails": [
{
"primary": true,
"value": "johnsmith@example.com",
"type": "work"
}
],
"active": true,
"preferredLanguage": "en",
"title": "Senior Software Engineer",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "R&D"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
]
}
HTTP Method | API Endpoint | Asana Behavior | |
GET | /Users | Return full list of Users in the domain. Does not return Asana guest Users. The accepted query parameters are: 1. filter for userName . | |
GET | /Users/:id | Return specific User in the domain. Does not return Asana guest Users. | |
POST | /Users | Create a new User if the User does not exist. | |
PUT | /Users/:id | Update / remove attributes for a User. Deprovision User (zombify) in Asana if active=false . | |
PATCH | /Users/:id | Add / update attributes for a user. Deprovision User (zombify) in Asana if active=false . | |
DELETE | /Users/:id | Deprovision User (zombify) in Asana. |
Accepted attributes:
Attribute | Type | Info | |
userName | string | Unique identifier for the User, typically used by the User to directly authenticate to the service provider. Each User MUST include a non - empty userName value, and it must be an email address. REQUIRED. | |
name | complex | The User's name. | |
name.givenName | string | Unsupported for PATCH request, use name.formatted . | |
name.familyName | string | Unsupported for PATCH request, use name.formatted . | |
name.formatted | string | The full name of the User. | |
emails | multi-valued complex | Email addresses for the User. | |
emails.value | string | Email address for the User. | |
email.primary | string | Whether this email address is the preferred email address for this User. true may only appear once for this attribute. | |
active | boolean | Indicates whether the User's account is active in Asana. | |
title | string | The User's title, such as "Vice President". | |
preferredLanguage | string | The User's preferred language. Used for selecting the localized User interface. | |
"urn:ietf:params:scim: schemas:extension:enterprise: 2.0:User" | complex | The Enterprise User Schema Extension attribute. | |
"urn:ietf:params:scim: schemas:extension:enterprise: 2.0:User.department" | string | The department the User belongs to. |
Group Endpoints
Examples
Request: GET https://app.asanac.om/api/1.0/scim/Groups?filter=displayName eq "Marketing"
Response: 200 OK
{
"Resources": [
{
"id": "1",
"displayName": "Marketing",
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"meta": {
"resourceType": "Group"
}
}
],
"totalResults": 1,
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
}
Request: POST https://app.asana.com/api/1.0/scim/Groups
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "Marketing",
"members": [
{"value": "1"},
{"value": "2"}
]
}
Response: 201 Created
{
"id": 1,
"displayName": "Marketing",
"members": [
{"value": "1"},
{"value": "2"}
],
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"meta": {
"resourceType": "Group"
}
}
Request: PATCH https://app.asana.com/api/1.0/scim/Groups/1
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "add",
"path": "members",
"value": [
{
"value": "3"
}
]
}
]
}
Response: 204 No Content
SCIM Groups are equivalent to Asana Teams.
HTTP Method | API Endpoint | Asana Behavior | |
GET | /Groups | Return full list of Teams in the domain, including private Teams. The accepted query parameters are: 1. filter for displayName . | |
GET | /Groups/:id | Return a specific Team in the domain. | |
POST | /Groups | Create a new Team. | |
PUT | /Groups/:id | Replace the Team's attributes. | |
PATCH | /Groups/:id | Update the Team's attributes. |
Accepted attributes:
Attribute | Type | Info | |
displayName | string | Unique identifier for the Team. REQUIRED. | |
members | multi-valued complex | The members of the Team. | |
members.value | string | The Team member's User ID. |
Deprecations
Communicating about breaking changes
Whenever possible, the Asana API aims to preserve backwards compatibility for its users. Apps you write on top of the API now should, in ideal situations, continue to work indefinitely. However, there are a few rare cases where breaking changes are required. For example:
- When we identify a stability threat, we may need to partially limit or entirely deprecate the culprit feature in the API.
- When making a change in a backwards compatible way results in a cluttered, brittle, and confusing interface to Asana.
- When not making a breaking change poses a security vulnerability, such as when we migrated from SSLv3 to TLS 1.0.
If a breaking change is required, the API team will provide a number of resources to help our developers get through the change:
- We will communicate early, and through a variety of channels. We recommend that you join the developers community forum to learn about changes to the API.
- We will provide a clear description of the change, how it affects your requests, and a migration plan to follow to transition through the deprecation.
- We will designate a deprecation period during which you will be able to choose between both old and new behavior from the API, allowing you to test out the change without having to put your entire app at risk.
Response header notifications
While the previously mentioned communication channels are the best place to learn about upcoming changes, the API itself will also alert you of upcoming changes. Shortly after we post communication, the API will begin sending Asana-Change
headers in the responses. These headers will have two or three pieces of information:
- The unique name of the change
- A URL to our blog post describing the change
- Optionally, a flag indicating that your specific request would be affected.
This header may be present multiple times in the response if there are multiple ongoing changes. Here's an example of one of these headers:
Asana-Change: name=security_headers;info=https://asa.na/api-sh;affected=true
Asana-Change: name=other_change;info=https://asa.na/api-oc
Note: If your request is not affected, we will not claim affected=false
. This is in case, during the deprecation, we detect that the change has a larger scope than initially thought. A request going from "you may be affected" to "you definitely are affected" is an acceptable update, but a request going from "you definitely are not affected" to "you definitely are affected" is not an acceptable update.
Request header options
During the deprecation period, you can test out how the API will behave by sending additional headers in your requests. Sending an Asana-Enable
header including comma-separated names of features will turn those features on for that request. Sending an Asana-Disable
header will do the opposite and turn those features off for that request.
If no header is specified, the default behavior will be determined by how far into the deprecation period we are:
- Before the start of the deprecation period (the "start date") the feature will be disabled, and it will not be possible to enable it.
- After the start date, the feature will be disabled by default, but you can begin choosing whether to enable or disable it.
- In roughly the middle of the deprecation period (the "activation date") the default behavior will switch and the feature will be enabled by default. You can continue to disable it with the appropriate header.
- At the end of the deprecation period (the "end date") the feature will be enabled and you will no longer be able to manually disable it.
The start, activation, and end dates will clearly be documented in our communications. These days may be pushed into the future if we discover that developers need more time to migrate their apps, but they are guaranteed to never occur sooner than documented.
These dates are arranged such that, if a developer happens to miss our communication and their app breaks when the default behavior changes on the activation date, they can begin sending the Asana-Disable
header to restore the old behavior and use the remaining half of the deprecation period to make their app compatible.
Here's an example of how these headers would look:
Asana-Enable: security_headers,another_change
Asana-Disable: a_third_change
Aside from reserving the right to push the date of changes to a future date, the precise time during the activation date isn't specified. However, since the default will only affect your integration if you do not pass either the Asana-Enable
or Asana-Disable
headers for a particular deprecation you can ensure predictable behavior of our API for your app during the entire period, including throughout the activation date.
The way we recommend you implement these changes in your integration is this:
- Whenever you detect a new Asana-Change header, log these requests and be sure to take note that a change is coming. Recall that the
info
key in the header will contain a link with the details. - Identify the nature of the upcoming deprecation and decide if your integration is sensitive to the change, paying particular attention to the cases where we return
affected=true
. - If changes are necessary in your integration, test the new behavior manually by making requests with
Asana-Enable
set to the name of the deprecation. This should provide a clear example of the new behavior as it is implemented in our API. - Implement the changes in your integration in such a way that it can handle the new behavior and be sure to pass the
Asana-Enable
header when you make requests. This will ensure that you will always get the new behavior regardless of when the default behavior changes.
At this point, your integration has been migrated to the new behavior. At any point after the end date the Asana-Enable
header will be ignored by the Asana API and you can feel free to remove it. (We strongly recommend keeping it all the way through the end date in case of unforseen circumstances that cause us to temporarily reset the default behavior from the new implementation to the deprecated behavior.)
Client library support
The latest version of our official client libraries for Python, Java, PHP, and JavaScript all support sending custom headers and are able to use our deprecations framework. Consult the individual libraries for how to send headers with each request.
Developer Sandbox
An Asana developer sandbox consists of a temporary Asana domain with limited users. It is essentially a standard Asana account where you can test premium features during development.
Developer Sandboxes are intended for:
- Developers building or maintaining a 3rd-party integration with Asana (submit your completed integration to get listed on our apps page)
- Existing premium Asana customers that require a separate environment to perform risk-free testing on the API
To request a developer sandbox, please fill out this form.
API Explorer
The Asana API Explorer is a tool to easily make API requests in your browser and quickly test various routes, fields, and parameters.
The explorer is not meant to be an exhaustive tool with every endpoint in the API (try Postman if you want a tool with complete coverage). Instead, the explorer is designed to be a simple tool to help developers quickly access the API and see examples of requests and responses fetching real Asana data.
Follow these steps to get started:
Go to the API Explorer site: https://developers.asana.com/explorer
Click the large button that says “Click to authorize API Explorer”. This will use your Asana credentials to provide cookie authentication for the requests you make in the explorer. Because the explorer is using your Asana account, it only allows read requests (i.e.
GET
only) to protect against unintentionally changing your Asana data.Choose the resource you wish to query from the drop-down.
In the next drop-down, choose your desired route for that resource.
Under "Include Fields," You have the option to select only the fields you would like to include in the response (more about I/O options).
The default response limit is 10. You can increase it up to 100.
Add the required “Attribute parameters”. Note that task and project gids are in URLs when viewing those resources in the Asana web product (e.g. when viewing a task in a project: https
://app.asana.com/0/'project-gid'/'task-gid'). In subsequent requests, you may have a pagination token (see the pagination docs for more on this) to paste into the “Offset” field.
You have the option to include additional parameters in your request.
Click “Submit” to send your request to the API. You will receive a JSON pretty-formatted response.
Submit your App
Have you built a web application that you want to share with the Asana community? Submit this form to get your app listed in the Asana apps directory.
Recommendations and resources for app developers:
We strongly recommend that you use OAuth 2.0 for your app. Apps that don’t use Auth 2.0 will likely not be approved for listing in our directory.
Be aware of the OWASP Top 10 Web App Security Risks when developing your app.
If you are new to app security, we recommend reading The Web Application Hacker's Handbook.
Use end-to-end encryption. Use a trusted site to test your TLS security (such as: https://www.ssllabs.com/ssltest/).
Join the Asana developer community. This is the best resource to get technical questions answered as well as get notified about new API features, deprecations, and other breaking changes.
Once your app is listed, you can answer Asana user questions in the integrations section of the Asana community.
Updating your existing app listing
If you wish to update your existing listing, send an email to api-support at asana.com with the specific changes.
We expect existing apps to maintain the same level of user experience that they had when accepted to the apps directory.
Custom Apps
What to consider when building a custom app.
Unlike 3rd-party apps and integrations used by many companies, custom apps are designed to only be used within a single domain. For example, an Asana customer may want to use the API to create a bot, integrate Asana with a homegrown tool, or generate custom reports. If you want to get inspired about what’s possible with custom apps, here are some common use cases.
Authentication
Most custom apps use Personal Access Tokens (PATs) for authentication. In general, PATs are best for projects that don’t require multiple users to log in. For example, it’s advisable to use PATs to auth scripts, bots, or anything else that doesn’t require taking action on behalf of multiple Asana users. While less common, if your custom app requires users to sign in to use it, then you should consider using OAuth.
API Explorer
If you're unfamiliar with our API, it may be helpful to start by playing around with our API explorer. It’s a quick and easy way to test endpoints and see how various parameters affect responses. You will also find guides and code examples in our docs and client libraries that are helpful when getting started.
Client Libraries
You should consider using one of our API client libraries for your custom app. They simplify some of the more technically challenging aspects of development such as authentication and pagination. There are code examples for each library to help you get started. The client libraries also help developers navigate API deprecations, which will help you avoid unexpected breaking changes and reduce the overall time required for maintenance.
Note that client library functions are not documented. You need to check the lib/resources/gen
folder of each library to see the built-in functions.
API support
If you get stuck or need help developing your custom app (or just want to meet other Asana developers), join our active developer community. On the forum, you can find answers to many technical questions. If your question has not yet been answered, post it and you should get a reply within a day or so. In addition to community support, internal Asana engineers also help troubleshoot issues on the forum. If you have found an API bug, you can either post it to the community or email the issue to api-support at Asana dot com.
Deployment
Once you’ve created a custom app, you will likely want to host it somewhere. While you could run your script from the command line, doing so is tedious and time consuming.
The most basic, automated option is to use launchd to programmatically execute your app on your machine (launchd is like cron but better). Here’s a tutorial to get you started with launchd.
A more robust option would be to deploy your custom app to a hosted server. Here’s a guide exploring some of the popular hosting providers. Hosting your app makes it more resilient and allows you to add more sophisticated features (e.g. use webhooks).
Remember to securely store your PAT and any other sensitive data (never expose a PAT in a public repository).
Maintenance
Make certain that the email address associated with your custom app is being actively monitored. We only email developers for critical issues such as API bans and upcoming deprecations that our logs show will break your app. If you’re using a PAT to authenticate, you should confirm that the email address associated with the Asana account that generated the PAT is being actively monitored by one or more people.
We also recommend all developers join the Asana developer community. This is where we will communicate new API features as well as announce upcoming breaking changes. To ensure you don’t miss these announcements, we encourage you to turn on notifications for the Platform News section of the community.
If your app is having issues, here are some steps to help you troubleshoot the issue:
- Carefully read any error messages (here are the docs for Asana error codes).
- Check the status of the Asana API to confirm it’s up and available.
- Check for any issues with the server that is hosting your app.
- Check the Asana dev community to see if others are having the same issue.
- If you can't find an answer on the community, post your issue and someone will likely help. Please include all of the required information to reproduce the issue (e.g. verbose CURL request with full response). Never post a PAT to the forum (or share it anywhere else).
How to use the API
Request
https://app.asana.com/api/1.0/users/me
If you're familiar with building against APIs, you can jump to our examples.
If you’re new to developing on APIs, this is a great place to start. You’ll learn in this guide how to make the simplest Asana API request -- getting your user information.
To get started
- Be logged into Asana.
- Go to this URL: https://app.asana.com/api/1.0/users/me
me
is a User Identifier that refers to the logged in user. A User Identifier can be either me
, an email_address, or the gid of the user.
Response
{
"data": {
"gid": "12e345a67b8910c11",
"email": "jonsnow@example.com",
"name": "Jon Snow",
"photo": {
"image_21x21": "https://s3.amazonaws.com/profile_photos/121110987654321.hJGlskahcKA5hdslf4FS_21x21.png",
"image_27x27": "https://s3.amazonaws.com/profile_photos/121110987654321.hJGlskahcKA5hdslf4FS_27x27.png",
"image_36x36": "https://s3.amazonaws.com/profile_photos/121110987654321.hJGlskahcKA5hdslf4FS_36x36.png",
"image_60x60": "https://s3.amazonaws.com/profile_photos/121110987654321.hJGlskahcKA5hdslf4FS_60x60.png",
"image_128x128": "https://s3.amazonaws.com/profile_photos/121110987654321.hJGlskahcKA5hdslf4FS_128x128.png"
},
"resource_type": "user"
}
}
And Congratulations! You’ve just made your first Asana API request.
Let’s unpack what just happened. The base URL for all requests to the Asana API is https://app.asana.com/api/1.0
. We want information about users, so we go down a level to the https://app.asana.com/api/1.0/users
resource. Within the set of all users in Asana, We’re specifically looking to get information about our own account, so we get more specific by adding /me
to get https://app.asana.com/api/1.0/users/me
. The /me
part would ordinarily be an identifier (a long number) or email address of the user, but we've created this shorthand for getting the current user of Asana's API, whomever that may be. Put it together and you have the above path to get your user information from Asana.
Since every API request you make will start with the same base URL ('https://app.asana.com/api/1.0'), we'll just talk about what comes next in the URL -- which is often referred to as a 'resource' or 'path'. For instance, when we say /users/me
it's actually shorthand for the entire URL which would be https://app.asana.com/api/1.0/users/me
.
After requesting information from the API, you will receive a response in JSON format, which can be read and understood by both humans and computers. It's structured in a particular way so programs can rely on a consistent format for the data.
Our API is documented for what resources are available and what sort of return data to expect. For example, here are the docs for the /users
endpoint which we just called. This is where you can discover what's possible with our API.
Now, let’s make the same call to /users/me
more like software would. Before we do so, we’ll need to get access outside of your web browser to the API.
Authentication Quick Start
Similarly to entering your username/password into a website or logging into Asana with Google, when you access your Asana data via the API you need to authenticate. In the above example, you were already logged into Asana in your browser so you were able to authenticate to the API with credentials stored by your browser.
If you want to write a script that interacts with the Asana API, the easiest method is to get a Personal Access Token (PAT), which you can think of as your unique password for accessing the API.
App or PAT?
If your app needs to perform actions on behalf of users, you should use OAuth.
Getting a Personal Access Token (PAT)
Example PAT
0/68a9e79b868c6789e79a124c30b0
- Open the Developer App Management page by using this permalink or following these steps:
From within Asana, click your profile photo from the top bar and select "My Profile Settings"
Click the "Apps" tab
Click "Manage Developer Apps"
Click "+ Create New Personal Access Token"
Type a description of what you’ll use the Personal Access Token for.
Click "Create"
Copy your token. You will only see this one time, but you can always create another PAT later.
Note: treat your PAT like you would a password. Do not share it or display it online.
Using Terminal
curl Request
curl https://app.asana.com/api/1.0/users/me \
-H "Authorization: Bearer 0/123456789abcdef"
We’ll use cURL, a command line program to make HTTP requests. MacOS and many Linux distributions have cURL pre-installed, and it’s available for download on Windows and many other operating systems. If you’re curious, you can learn more about cURL in its own documentation.
Let’s do this:
Response
{
data: {
gid: "<your gid>",
email: "<your email>"
name: "<your name>",
...
}
}
Copy/paste the cURL request on the right (make sure to enter your personal access token instead of the placeholder after the word "Bearer", or else you'll get a "Not Authorized" message):
Press Enter
Nice work! You just wrote a cURL command.
In our API documentation, we will often write examples as cURL commands since it's a middle-of-the-road approach to accessing our API: more flexible than using a browser, but user-friendly enough to be quick and easy to do.
You’re ready to start coding!
Asana has client libraries in several popular coding languages. Using these libraries has several advantages (like managing authorization and retrying errors) that make them a good place to go from here. Let’s take a look at making the same /users/me
request in Python, JavaScript, and Ruby (feel free to skip ahead to your favorite of the three languages).
Using Postman
You can quickly get started on Asana's API with the API Explorer. However, if you want a more robust experience hitting the API, we recommend using Postman. You can get started with the 'Run in Postman' button!
Once you have the collection, you should create an environment.
You'll want to set:
authentication_token
to a Personal Access Token (PAT). If you don't have one yet, visit our Authentication Quick Start.workspace
to your workspace's gid. You can find this value via a logged-in browser by going to https://app.asana.com/api/1.0/users/me/workspaces, or you can hit that endpoint using your PAT.- Any other gids you want to easily access.
- For example, you can set
task
to the gid of a task that you regularly test with,project
to the gid of a private sandbox project, anduser
to the string 'me'.
- For example, you can set
No need to edit your environment for requests on different objects, simply navigate to the endpoint you want to use, and change the {{object}}
to any gid you want.
Importing this collection gives you a snapshot of the API at this time. To stay up to date with API changes, you'll have to re-import the collection by hitting the 'Run in Postman' button, and choosing to override your existing collection. This means if you want to save custom requests, you should do so in a different collection.
Common Usecases
Collaboration across teams and tools works best when everyone stays in sync and processes flow easily and without friction. This is why we have Asana's API: it's a platform to ensure all of your information is up to date and that your teams stay efficient and in the loop.
Asana’s API provides a means for software and scripts to read information from inside Asana, input information from outside Asana, and automatically react when things change. This can include:
- Consistently doing repetitive or tedious tasks.
- Chaining a process together by responding to changes.
- Creating reports on the state of tasks and projects.
- Staying in sync with other software such as Slack or Salesforce used in your organization.
- Pulling information from other locations like email or Evernote into Asana.
- Adding new features on top of Asana.
- Customizing Asana for your team’s processes and workflows.
The role of Asana's platform is to allow Asana to meet your team where you are and how you work. Asana is built to be flexible and powerful, to be intuitive enough for all teams to adopt and maintain clarity on who is doing what by when. Asana’s platform enables you to specialize this flexibility to maximize efficiency. Here are some ideas for what you can build:
Doing repetitive work
Integrations and bots are great for making sure that repetitive tasks are always taken care of. Running a script with Asana's API can quickly take care of work like moving cards between board columns, setting assignees or due dates based on the state of the task, or asking that all custom fields are set before work can begin on a task. This can save time and overhead when trying to keep your projects clear and correct.
Reacting to changes
Workflows with Asana often have a "when this task changes, do something" feel. An example is moving tasks between projects based on subtasks: if one team completes a subtask, move the parent task to the next team's project. Integrations can be built to respond in near-real time to changes in Asana to move work forward to the next step.
Generating reports
Fetching the state of the tasks in a project or for your teammates can unlock the ability to create simple - or complex - metrics around how you are progressing. How many open tasks are there in the project? Who has the most tasks assigned? How often does the due date of each task get shifted back? Our platform enables pulling of data from Asana to make customized metrics to track your work.
Keeping in sync
Teams frequently use a multitude of software tools to accomplish work, from email to asset management to file storage. These specialized tools are often used with colleagues who don't track their work with Asana; and even if they do, keeping all of your tools in sync makes the transitions between tools straightforward to minimize work about work.
Some of our integration partners, like Tray.io, Unito, and Zapier, offer syncing solutions out of the box with common workplace tools, or you could build your own solution in cases where you need more flexibility, such as when connecting to customized or internally-built software.
Capturing work
Asana is built for teamwork and knowing who is doing what by when. Having an easy way to capture information in Asana makes it less likely that work will slip through the cracks. For example, when communicating with people who work in other companies who aren't members of your Asana organization, an integration like we built for Gmail lets you create follow-up tasks with just a few clicks.
Getting information into Asana in a quick and easy way is important for ensuring that you don’t drop the ball. Asana’s platform is a great way to pull information from many channels into Asana with minimum hassle.
Extending Asana
Asana is built to be a tool that works well for all teams, so we build features into our core product that aren't overly opinionated about how you get work done. At the same time, there is opportunity for teams to use Asana in a specialized way or with specific additional features. When there are features that you'd like Asana to have, our platform is a resource to make them happen. As a matter of fact, some of our more successful integrations like Instagantt exist purely to provide additional features to Asana.
Customizing workflows
Integrations or scripts work great to maintain a custom workflow, saving a team member from having to continually pay attention to the state of tasks in Asana.
Whether it's ensuring that custom fields are filled out, tasks are completed, tasks live in the correct board-view column, or automatically assigning tasks at certain stages in your process, integrations can react to changes in Asana to ensure that everyone is up to date. When processes mature around how you get work done, it's a great time to use Asana's platform to make sure everything stays consistent and clear.
Check out some examples of integrations we've built on Asana in the next section.
Examples
Python Hello World
import asana
# replace with your personal access token.
personal_access_token = '0/123456789....'
# Construct an Asana client
client = asana.Client.access_token(personal_access_token)
# Set things up to send the name of this script to us to show that you succeeded! This is optional.
client.options['client_name'] = "hello_world_python"
# Get your user info
me = client.users.me()
# Print out your information
print("Hello world! " + "My name is " + me['name'] + "!")
To get started, run pip install asana
or follow the detailed installation instructions on the GitHub page for the Python client library.
Once it’s installed, open your favorite text editor and we’ll code a GET request to /users/me
in Python.
Save this file as something descriptive like "hello_world.py"
To run this script in your console, pass it as an argument to the python interpreter, i.e. python hello_world.py
from the same directory as the file. You should see the message we wrote above with your user information.
As an aside, for clarity python-asana
will also work with Python 3.x (with small changes to the above example to make it compatible.)
All of the built-in functions can be found in the /gen folder of the client library.
You can see a variant of this script, and other useful Asana API scripts, in our open-source GitHub examples repository
Node Hello World
var asana = require('asana');
// replace with your personal access token.
var personalAccessToken = '0/123456789....';
// Construct an Asana client
var client = asana.Client.create().useAccessToken(personalAccessToken);
// Get your user info
client.users.me()
.then(function(me) {
// Print out your information
console.log('Hello world! ' + 'My name is ' + me.name + '!');
});
To get started, npm install asana
or follow the detailed installation instructions on the GitHub page for the Node client library.
Once it’s installed, open your favorite text editor and we’ll code a GET request to /users/me
- the same request as above, but in JavaScript.
Save this file as something descriptive like "hello_world.js"
To run this script in your console, pass it as an argument to the node interpreter, i.e. node hello_world.js
from the same directory as the file. You should see the message we wrote above with your user information.
All of the built-in functions can be found in the /gen folder of the client library.
You can see a variant of this script, and other useful Asana API scripts, in our open-source GitHub examples repository
Ruby Hello World
require 'asana'
# replace with your personal access token.
personal_access_token = '0/123456789....'
client = Asana::Client.new do |c|
c.authentication :access_token, personal_access_token
end
me = client.users.me
puts "Hello world! " + "My name is " + me.name + "!"
To get started, `gem install asana` or follow the detailed installation instructions on the [GitHub page for the Ruby client library](https://github.com/Asana/ruby-asana/).
Once it’s installed, open your favorite text editor and we’ll code a GET request to /users/me
- the same request as above, but in Ruby.
Save this file as something descriptive like "hello_world.rb"
To run this script in your console, pass it as an argument to the ruby interpreter, i.e. ruby hello_world.rb
from the same directory as the file. You should see the message we wrote above with your user information.
All of the built-in methods can be found in the /resources folder of the client library.
You can see a variant of this script, and other useful Asana API scripts, in our open-source GitHub examples repository
Workflow automation script
Asana's API enables customization and automation of your organization’s workflow through scripts built to specialize your use of Asana. Using Asana to track your work and leveraging Asana’s API to automate your processes is a powerful combination which can make your team much more efficient. Here's one example of how we do it at Asana.
Tracking timely responses to support questions
Asana’s developer relations team manages technical support for our API through a number of channels: support tickets, questions about our API and integrations forwarded on from our colleagues, the Asana Community's Developer category, Stack Overflow, pull requests and bug reports from open-source GitHub projects like our client libraries, and more. Staying on top of all of these channels can be daunting, but we want our users to reach us however works best for them. At the same time, we want to isolate the noisiness of incoming requests for our colleagues at Asana who are involved with only one channel.
Additionally, the management of the question and answer process, triaging the incoming requests, troubleshooting with our engineers, and measuring our response performance are all internal processes. Even if we have a workflow in place to support our developer relations team, we want the experience for other teams to be easy and lightweight. We want to ensure our coworkers do the right things by default without hindering the consistency of our work and our ability to track progress.
Our solution: automation and reporting through our API to provide consistent management of the whole process.
To do this, we wrote an integration with the following goals in mind:
- Maintain clarity amongst our teams by tracking work in Asana.
- Have only one place we have to look to stay in the loop.
- Ensure that no questions get missed, i.e. a reminder bot.
- Let our API users know that they've been heard in a timely fashion.
- Track our performance in remaining responsive.
- Automate some of the bookkeeping required to maintain a consistent workflow.
- Separate the specifics of how we track our performance from our colleagues’ workflows.
The script we built does the following for us:
- Integrate with external sources to put incoming questions into Asana, one project per channel.
- Add question tasks from each incoming project into a single combined project.
- Acknowledge a question has been received and begin tracking response times.
- Upon first response, complete a task to signal relevant followers that we've reached out.
Maintain focus
We use webhooks to get notified in near-real time when new tasks are created in any of several Asana projects, one per incoming channel. Some of these projects are automatically synced with outside sources, others are available for our coworkers to create tasks in. Keeping tasks in their source channel helps keep us organized for where to go to respond. These projects are what our colleagues follow in order to remain focused on their own channels.
Our script responds to these webhook notifications from each project by adding these tasks into a single "Developer Questions" project. Our developer relations team can then see all outstanding questions about our API in a single place. This is a key part of hitting our service level agreement (SLA) goals: not having to cycle through many projects and channels to see how we're progressing.
Ensure timely responses
Once a question gets added to our Developer Questions project, our integration creates a subtask on it. This signals to our colleagues that we have received the question and will begin to triage and investigate. The subtask is completed when we first respond to our users to inform them that we're investigating. Completion of the question task itself signals that we've achieved a resolution for the person who reached out to us.
Track progress
Our script can generate a simple report to see which questions are still open, how long they’ve been open, and how much time we have left to answer before we miss our service level agreement limits. A simple webpage that the integration creates enables a high level view of what's still in progress and how timely we've been in the past.
Keep the process moving, automatically
Our integration also helps automate some of the routine steps to ensure questions get answered. After a task gets triaged for priority, our integration sets an appropriate due date. It can also set an assignee and followers based on current workload and by matching certain keywords in the task description. If the task approaches its due date and it has not received a response, the script comments on the task to alert us that the question is about to reach our SLA limit. This helps us keep the right people in the loop with minimal overhead and maximum clarity of what needs to be done by when.
By managing this routine and specialized workflow with automation through Asana’s API, our team is more efficient, more effective, and less likely to make a mistake. We know how responsive we've been and can see how we're doing at any time. We're better able to minimize the number of questions which slip through the cracks. The result is better support for outside developers and increased focus on core work, not work about work.
Over time, we've continuously tweaked how our integration behaves to evolve our process, empowering us to adjust and iterate our approach. This is one of the key opportunities that Asana's API provides: ownership and control over how work gets done. Incremental improvements provide the chance to try out new workflows and settle on one that works well for everyone, leading to a more consistent and customized experience of using Asana.
To get started, check out our examples page. For support or to generate ideas of how your team can work more effectively with Asana, head to the Asana Community to chat with Asana team members and users!
Triage bot
Let’s start coding!
Follow along below in the right pane to see the terminal commands and code for this tutorial. We will use a very basic file structure for the purposes of this guide. Start by making a project directory, moving into it, and running
npm init
.
$ mkdir triage-bot
$ cd triage-bot
$ npm init
Install the Node Asana client library and create config and app files:
$ npm install asana
$ touch config.js app.js
Add gids (global ids) for the workspace, design request project, and designers that will be assigned requests (note that all gids in Asana should be strings). You can get a project’s gid from its URL in the Asana web product (e.g. the structure of links for a task is www.asana.com/0/{project_gid}/{task_gid}). Similarly, you can get user’s gid from the URL of their task list (i.e. click on their name in Asana). To get your workspace gid(s), go to https://app.asana.com/api/1.0/users/me/workspaces.
let config = {
workspaceId: "15793206719",
designRequestProjectId: "180350018127066",
//gids of designers who are fulfilling design requests
designers: ["180015866142449", "180015866142454", "180015886142844"]
};
module.exports = config;
Next, let’s get started on our app.js file. Include the Asana node client library and the config file:
let asana = require('asana');
let config = require('./config');
Get your access token and use it to create an Asana client. At the time of writing this guide, the Asana API is going through two deprecations (moving to string gids and changing how sections function). You can learn about our deprecations framework in our docs. To prevent my app from breaking when the deprecations are finalized, I'm passing headers to enable the new API behavior for string gids and sections. We will also set a delay to determine how quickly our parallel requests are sent.
// Get personal access token (PAT) from environment variables.
const accessToken = process.env.triage_bot_pat;
const deprecationHeaders = {"defaultHeaders": {"asana-enable": "new_sections,string_ids"}};
// Create Asana client using PAT and deprecation headers.
const client = asana.Client.create(deprecationHeaders).useAccessToken(accessToken);
// Request delay in ms
const delay = 200;
Use the search API to fetch unassigned tasks from the design requests project. Note that the search API doesn’t return paginated results so you need to pass the max limit which is 100. If there are often more than 100 unassigned tasks, you can add a function to keep running the script until there are no more unassigned tasks.
function getUnassignedTasks() {
let workspaceId = config.workspaceId;
let params = {
"projects.any" : config.designRequestProjectId,
"assignee.any" : "null",
"resource_subtype": "default_task",
"fields": "gid",
"limit": 100
};
client.tasks.searchInWorkspace(workspaceId, params).then(tasks => {
randomAssigner(tasks.data);
});
}
We’ll need a few helper functions. One to shuffle an array and another to assign tasks.
function shuffleArray(array) {
for (let i = array.length - 1; i > 0; i--) {
let j = Math.floor(Math.random() * (i + 1));
let temp = array[i];
array[i] = array[j];
array[j] = temp;
}
return array;
}
function assignTask(taskStringId, assigneeStringId) {
client.tasks.update(taskStringId, {assignee: assigneeStringId})
}
Our final function will take the array of unassigned tasks and round-robin assign them to the group of shuffled designers from the config file. We will use an interval to loop so we can control the speed of the requests. You can change the delay with the const you declared earlier. This is a balance between speed and staying within our concurrent request limit. In node, a normal loop would send all requests at once, which doesn’t work in larger projects.
function randomAssigner(unassignedTasks) {
let shuffledDesigners = shuffleArray(config.designers);
let numDesigners = shuffledDesigners.length;
// Let's use an interval to loop, so we control how quickly requests are sent
let index = 0;
let interval = setInterval(function() {
assignTask(unassignedTasks[index].gid, shuffledDesigners[index % numDesigners]);
index++;
// When our index reaches the end, we're done
if (index >= unassignedTasks.length) {
clearInterval(interval);
console.log("You've assigned " + unassignedTasks.length + " new design requests");
}
}, delay);
}
Then we just need to call our getUnassignedTasks function to kick-off the script:
getUnassignedTask();
Now run your script, sit back, and watch the bot do your work.
$ node app.js
Why build a bot?
When processes get complex in Asana there can begin to be work about work. This could be happening to you (or someone you love) if you find yourself spending time doing repetitive work such as triaging tasks, reminding people to do something, or adding/removing followers as you move a task through a workflow.
What we’re going to build
In this guide, we will build a simple triage bot that will assign tasks. This is a common Asana use case with support inboxes or request projects.
If you want to skip ahead and see the code for the triage bot, it’s on GitHub in the JavaScript folder of our devrel-examples repo.
For this guide, let’s suppose a design team has a requests project where people from the marketing team fill out an Asana form to request graphics from the design team. The form creates a task in the design requests project that needs to be assigned to a designer.
Our triage bot will gather all unassigned tasks in the design request project and then randomly distribute the requests across a group of designers.
For the purposes of this guide, we will keep it this simple, however, you could add more complex logic to your bot. For instance, you could check custom field values on the request task to see what type of request it is (e.g. video, graphic, logo, etc.) and then assign it to the designer that has those skills. You could go even further and check the designers workload to see who currently has the least amount of work already assigned to them (this could be determined by a point value for tasks assigned to them in the project). You could then have the bot ping the design request task as it approaches the due date to ensure that the designer will have it completed on deadline.
Helpful links
Before we get started, here are some helpful links for building on the Asana API:
- Asana API reference docs
- Asana longform documentation
- Asana developer community -- if you get blocked or have a question about the API, there are devs in our community that are eager to help. We also post API updates and news to the community forum.
- The code for this bot on GitHub
Create your bot user in Asana
Create a new Asana account for your bot (instructions for inviting users). You want to create a distinct Asana account for your bot because any action it takes in Asana will be attributed to this user. Give your bot a name and photo that will be recognizable to users in Asana that encounter it. Note that if your bot is a guest member in Asana that it will need to be added to every project you need it to work in. Bots based on guest Asana accounts will also not have access to some API features such as defining new custom fields or modifying their settings.
Authenticating your bot
We will authenticate our bot using a Personal Access Token (PAT). Log in to the Asana account that will be used for the bot and navigate to the developer console. You can get to your dev console by either using this URL https://app.asana.com/-/developer_console or from within Asana by clicking your photo icon in the upper right of Asana -> My Profile Settings -> Apps -> Manage Developer Apps.
Next, click “+ New access token” and follow the instructions to get your token. Treat this token like a username and password. Don’t share it with anyone and never publish it to a public repository. I like to save my PAT as an environment variable (here are instructions on how to do this on Mac). For this guide, I’ve saved a PAT as an env variable called triage_bot_pat
.
Create an Asana sandbox
Before we start coding, create a project in Asana to use as a sandbox. While not required, I like to set the project to private while developing. To get some users in the project, add your main Asana user as well as your bot account. You could also invite a personal email as a guest user.
Choose an Asana client library
The Asana API has SDKs in several popular languages. For most developers, we recommend using one of our client libraries because they help with some of the complexities of using an API such as authentication, pagination, and deprecations.
For this guide, we will use the Asana Node client library, however, you can follow along in any language of your choice.
Each library has an examples folder in addition to the readme, which can be helpful for getting started. The methods for each resource can be found in the “gen” folder of each client library (e.g. node-asana/lib/resources/gen/).
Now head over to the top of the right pane to start coding your bot ----->
Congratulations! Now go above and beyond
You’ve created an Asana triage bot. Let’s explore a few ideas on how to make it even better.
Deploy your app
While you can run your bot from the command line, that seems like a lot of work to run a bot that’s supposed to eliminate work about work.
One option is to use launchd to automatically execute your script (launchd is like cron but better). Here’s a tutorial to get you started with launchd.
The next step would be to deploy to a hosted server. Here’s a guide exploring some of the popular hosting providers. Hosting your app makes it more resilient and allows you to create more sophisticated apps (e.g. use webhooks).
Use Asana as your config file
To take your bot’s accessibility to the next level, put your configuration in an Asana task(s) and then have your script read that task(s) for instructions. This allows you (or anyone else) to make config changes without touching any code. For example, if a designer is on vacation, you can easily remove them from the group that gets assigned requests. Similarly, if a designer joins or leaves the team, this change could be easily configured in a task instead of having to change the bot’s code.
To see this approach in the wild, checkout Ohmega, an automation framework we created. Here’s the configuration service that reads a tree of tasks for its configuration.
Use webhooks for real-time triaging
If you need your bot to react to changes in real time, then you’ll need to use webhooks. We built a python webhook inspector to help developers get started using Asana webhooks.
Other bot examples
Reminder bot
Even the most conscientious and best-intentioned teammate can get overloaded and occasionally forget a task. For project managers, team leads, or coordinators, it can be draining to check-in on everyone to make sure that everything is going according to schedule. How can you stay on track and minimize the work-about-work?
Instead of continually reminding teammates to stay focused, use Asana’s API to create a bot for automatic reminders (a bot is a script that performs a task automatically). In this case, a "ping bot" takes action when due dates are approaching (or for any other specified trigger). This can act as a more intelligent version of the reminders that Asana already sends when due dates approach. For example, this persistent friend could comment with reminders further in advance, ask assignees or followers to take some action like setting a custom field, re-assign the work, and/or push out due dates. With a bot taking care of the schedule and reminders, people can spend their time on the work that needs human attention, like ideation and feedback.
Recruiting bot
At Asana, we use a bot to help automate the process for evaluating engineering candidates. The bot helps ensure that applicant coding tests are graded in a timely manner by the right engineer.
When candidates have submitted their coding test, the bot uses the Asana API to assign the test to a grader based on specific criteria tracked in Asana, such as their preferred programming languages and number of previous evaluations. Graders are given x days to grade tests (the bot takes into account when graders are out of office). If tests have not been graded by the due date, graders are pinged by the bot with a comment on the task to either grade the test or re-assign it to someone else. After y days, the bot automatically re-assigns the test to the next grader to keep the process moving.
Bugs bot
Our engineering teams handle triaging bug reports by creating a task in a "Bugs" project. A bot then adds the project manager of the relevant team in Asana as a follower, moves the task into a "needs triage" section, and requests assistance. The project manager can then evaluate the bug and triage it.
Since the evaluation of the severity of the bug is important for understanding how urgent the fix is, Bugs Bot will remain persistent, commenting every few days until the task has been moved out of the triage section and into a section of the relevant priority. This process ensures that we're aware of the impact of bugs and helps us avoid severe bugs slipping through the cracks.
Official Client Libraries
Asana is committed to making the developer experience as smooth as possible. Part of this effort is providing high-quality libraries you can use to access the API. The available libraries are listed below, and more are in development. If you don't see what you need, check the open-source community for your platform, and let us know that you'd like to find one here!
JavaScript (Node)
npm install asana
For use in the Node server-side JavaScript runtime.
Installation: Install with npm
JavaScript (Browser)
<script src="asana-min.js"></script>
This is built our Node library, so you get the exact same interface.
Installation: Visit the releases page to download the latest full or minified JS bundle, then include the script in your web page.
Python
pip install asana
Installation: Install with pip
Ruby
gem install asana
Installation: Install with gem
Java
<dependency>
<groupId>com.asana</groupId>
<artifactId>asana</artifactId>
<version>0.10.1</version>
</dependency>
Installation: If you use Maven for dependency management simply include the following in your pom.xml.
PHP
"require": {
"asana/asana": "^0.10.0"
}
Installation: If you use Composer to manage dependencies you can include the "asana/asana" package as a dependency.
Overview of App Components
BETA
Now recruiting: Participate in Asana Research and earn a $300 gift card of your choice!
An important step in maintaining flow at work is having all the information you need in one place. Asana is for teams to track projects, to provide clarity on who is doing what by when, and to automate repetitive processes. With App Components, it's now easier than ever to see key work information from other tools on the surface of tasks, as well as automate cross-tool processes.
Apps can use App Components to display customized widgets, forms, and rules within Asana's user interface. Under the hood, requests are made from Asana directly to your App Server. Your App Server controls the information within these customized widgets, as well what happens when a user takes actions within these components.
Using App Components, you can build customizable in-product experiences for apps within Asana by leveraging capabilities such as:
For a visual tour on getting started with App Components, feel free to review the following video. Then, when you're ready, visit our Getting Started guide to begin building right away.
App Components are currently in open beta. For the latest updates and announcements, subscribe to our developer forum.
Widget
BETA - For access, please see Overview of App Components
Request to the App Server
https://app-server.com/widget?workspace=12345&task=23456&user=34567&locale=en&attachment=45678&asset=56789&expires_at=2011-10-05T14%3A48%3A00.000Z&resource_url=https%3A%2F%2Fcompany.atlassian.net%2Fissue%2F1254
Response from the App Server
{
"template": "summary_with_details_v0",
"data": {
"title": "MSB-3 As a user, I see a flexible widget",
"subtitle": "Jira Cloud Story · Open in Jira Cloud",
"subicon_url": "https://jira.com/icons/subicon.png",
"footer": {
"footer_type": "updated",
"last_updated_at": "2012-02-22T02:06:58.147Z"
},
"comment_count": 12,
"fields": [
{
"name": "Status",
"type": "pill",
"text": "In Progress",
"color": "blue"
},
{
"name": "Priority",
"type": "value_with_icon",
"icon_url": "https://jira.com/icons/priority_highest.png",
"text": "Highest"
},
{
"name": "Assignee",
"type": "value_with_icon",
"icon_url": "https://jira.com/avatars/rhian.png",
"text": "Rhian Sheehan"
}
]
}
}
A Widget is a card that is used to show data about an external resource. Currently, Widgets
appear inside of tasks. While the contents of a Widget may change, the overall format stays
consistent across apps. Apps can control what layout they prefer by supplying their preferred
template
. You can see the available templates in the Enumerated Values
section of response schema.
The App Server controls the content of this Widget. When an Asana user's browser navigates to a Widget, Asana sends a request to the registered App Server. As long as the response from the server is valid (like the example on the right), the Widget will display.
How does Asana determine when a Widget should be shown? When a task is opened in
Asana, it checks each attachment on the task. If an attachment has a URL
that fits with an App's registered match url
(ex: https:\/\/.*.atlassian.net\/.*
)
then it shows a Widget. A GET request is sent to the App's Widget metadata URL
, including
URL parameters like task
, user
, and workspace
.
Widget Configurations
Property | Description | |
Widget metadata URL | A URL that Asana uses to make requests for the data needed to load a Widget, which displays information about a third party resource. | |
Match URL pattern | A regex which allows Asana to compute whether a URL attachment is supported by an activated app on the project in order to render a Widget. |
Related References:
Modal Form
BETA - For access, please see Overview of App Components
Request to the App Server
https://app-server.com/form?workspace=12345&task=23456&user=34567&locale=en&expires_at=2011-10-05T14%3A48%3A00.000Z
Response from the App Server
{
"title": "Create New Issue",
"on_submit_callback": "https://app-server.com/actions/create",
"submit_button_text": "Create Issue",
"fields": [
{
"type": "single_line_text",
"name": "summary",
"title": "Summary",
"value": "",
"placeholder": "Enter some text",
"width": "full",
"is_required": true
},
{
"type": "rich_text",
"name": "description",
"title": "Description",
"value": "",
"placeholder": "",
"is_required": true
},
{
"type": "typeahead",
"name": "jira-project",
"title": "Jira project",
"value": "",
"placeholder": "Search Jira for a project...",
"is_required": true,
"typeahead_url": "https://app-server.com/jira/project/typeahead",
},
{
"type": "checkboxes",
"name": "attachments",
"is_required": false,
"options": [
{
"id": "shouldIncludeAttachments",
"label": "Attach files from this Asana task"
}
]
}
]
}
A Modal Form allows users to fill out a dynamic app-controlled list of fields. The number of fields can range from 0-20. Once a form is submitted, the information is sent to the App Server and Asana will perform different functionality depending on what they responded with. If the App wants to cause additional changes within Asana, the App Server will need to make the changes via the API.
An advanced feature of Modal Forms is live on_change
events. While a user is filling out a form,
the App Server can receive on_change
requests. These requests include what the user has changed, and
allow the App Server to respond with an updated form. Apps can build complex branching logic depending
on changes a user makes.
To take advantage of on_change
events, set some form fields is_watched
value to true
and an on_change_callback
endpoint to hit with updates.
See the on_change
field in the response to the
form metadata request. The request sent to that
endpoint is the On change callback request.
Modal Form Configurations
Property | Description | |
Form metadata URL | A URL that Asana uses to request data from the app about fields it should display in the Modal Form. |
Related References:
Lookup
BETA - For access, please see Overview of App Components
Request to the App Server
https://app-server.com/lookup?value=Cool&workspace=12345&task=23456&user=34567&locale=en&expires_at=2011-10-05T14%3A48%3A00.000Z
Response from the App Server
{
"resource_name": "Cool Attachment",
"resource_url": "https://localhost:5000/attachments/123456789"
}
Users can send a search term to the app server. The term is often a URL or the title of an external resource. The app server then responds with a resource or an error.
Lookup Configurations
Property | Description | |
Resource attach URL | A URL that Asana will make a request to when a user submits a value to attach (i.e., when clicking "Add"). | |
Placeholder text | Optional. Placeholder action text that appears in the Lookup input field after the user clicks on the Lookup action text. | |
Resource typeahead URL | A URL that Asana will make a request to when a user types into a Lookup field. |
Related References:
Rule Action
BETA - For access, please see Overview of App Components
Request to the App Server
https://app-server.com/rule?workspace=12345&project=23456&action_type=45678&action=56789&user=34567&locale=en&expires_at=2011-10-05T14%3A48%3A00.000Z
Response from the App Server
{
"on_submit_callback": "https://app-server.com/slack/action/onsubmit",
"on_change": {
"on_change_callback": "https://app-server.com/slack/action/onchange",
},
"fields": [
{
"title": "Choose a channel",
"type": "typeahead",
"id": "typeahead_full_width",
"is_watched": true,
"is_required": true,
"typeahead_url": "https://app-server.com/slack/typeahead"
},
{
"title": "Write a message",
"type": "rich_text",
"name": "description",
"is_required": true
}
]
}
A Rule Action allows users to customize actions triggered by Asana's rule engine. They use the same functionality as
the Modal Form, as Asana requests a form definition from the App Server. The app controls the form
fields, handles on_change
events, and stores the inputs of the form. When a rule is created, Asana sends a request to
the App Server with the user-specified inputs. When the rule is triggered, Asana sends an event to the App Server.
Rule Actions are a part of Asana Rules.
Note: An App Server must be hosted in order for Rule Actions to function. For a brief list of popular hosting options, see Hosting.
To see an example app server written for Rule Actions, see our app-components-rule-action-example-app on GitHub.
Rule Action Configurations
Property | Description | |
Display name | The Rule Action name visible to end users in the rule builder (e.g., "Create a Jira issue"). | |
Run action URL | A URL that Asana will make a request to when the rule is triggered. | |
Form metadata URL | A URL that Asana will make a request to to display the configuration form. |
Related References:
- Get Rule Action typeahead results
- Run action
- Get action metadata
- On action change callback
- On action submit callback
Entry Point
BETA - For access, please see Overview of App Components
The Entry Point allows users to initiate the Lookup and Modal Form components from tasks.
To configure the Entry Point, one or both of the above capabilities must be configured first. If only one of these capabilities is configured, the Entry Point takes the form of a button. If both of these capabilities above are configured, the Entry Point is rendered as a dropdown menu.
Entry Point Configurations
Property | Description | |
Lookup action text | Clickable action text that allows users to initiate a Lookup. | |
Modal Form action text | Clickable action text that allows users to initiate a Modal Form. |
Getting Started
BETA - For access, please see Overview of App Components
This guide will show you how to begin building with App Components. To make best use of the following tutorials, be sure you've already reviewed the Overview of App Components.
Overview of Build Steps
BETA - For access, please see Overview of App Components
The overall development process for App Components involves the following:
- Create the app in the developer console.
- Configure the app in the developer console.
- Build the App Server.
- Get the app ready for publishing.
- Submit the app for review.
The tutorials in this guide will cover the first two steps of the overall build process: creating and configuring the app. By the end of this guide, you will have an app ready to interact with your App Server.
Before You Begin
BETA - For access, please see Overview of App Components
Get a Sandbox
To get started with App Components, you'll need an Asana account. This will give you a workspace to access the developer console, through which you can create and configure apps directly in Asana's user interface.
While you can sign up for an account if you don't already have one, we actually recommend using a Developer Sandbox to help you build in a separate, dedicated environment. You'll still be able to access the developer console this way, but the developer sandbox will also grant you access to the Example App, where you can explore the capabilities and features of App Components in-depth.
Consider the App's User Experience
Each app built with App Components is unique, and will leverage different capabilities of App Components. For example, the Zoom app lets users create a new meeting or attach an existing meeting to an Asana task. Under the hood, these actions are made possible by using a Modal Form to create new meetings, Lookup to search and connect existing meetings, and a Widget to display the external meeting data in a task. Meanwhile, a different app may forego such functionalities, and instead exclusively use Rule Actions to automate workflows between Asana and another tool. Overall, we encourage you to experiment with different capabilities and decide how you want your end user's experience to be.
To see visual documentation for how you can design your app, check out the App Components Toolkit. For further inspiration, feel free to navigate to the app directory.
Start Building the App Server
Because App Components allow your end users to interact with resources outside of Asana's user interface, an App Server is required for building with App Components. While it isn't necessary to have a complete App Server before moving forward, it's a good idea to at least know the URLs to any server endpoints you want to configure ahead of time (e.g., your URL to get the metadata for a Widget), though these can be configured or changed at any time.
Feel free to review the app-components-example-app on GitHub to see an example server written in Express.js. This server is also used in the Example App.
Create the App
BETA - For access, please see Overview of App Components
The first step is to create the app in your developer console. Navigate to Create new app and provide a name for your app. If your app is published, this name will appear in the Asana app for users to see, including in both the app gallery and app directory.
Configure the App
BETA - For access, please see Overview of App Components
Once your app has been created, you'll automatically be brought to the new app's settings. From here, you can make the configurations necessary to define your app.
Note: To see these settings again, navigate to your app in the developer console.
Configure Basic Info
On the Basic information tab, provide some information about your app.
These details will be accessible to the end user, and are meant to help them identify and learn more about your application.
Property | Description | |
App icon | Your app's icon, shown to users to identify your application. | |
App name | Your app's name, shown to users to identify your application. | |
Short description | A short description of the app shown in the app gallery. | |
Long description | An extended description of the functionality of the app shown in the app settings. | |
Company name | Your company name. | |
Company URL | URL of the page where users can learn more about your company. | |
App landing page URL | URL of the page where users can learn more about this app and install it. | |
Support URL | URL of the page where users can read documentation or get support. | |
Privacy policy URL | URL of the page where users can read your app's privacy policy. |
Configure Capabilities
The next set of configurations you make will differ depending on what functionality and user experience you're looking to build. Each of the capabilities below are configured separately in the App Components tab in the developer console:
Follow the links in the table below to view the configurations required to build each capability (e.g., Widget).
Capability | Description | |
Widget | Display a dynamic, custom widget card in tasks that shows data from an attached resource. | |
Modal Form | Build a custom form to allow users to create new resources. This form gets shown in a modal when a user clicks the entry point on a task. | |
Lookup | Show a text input to allow users to find and attach resources to tasks. Users can paste a URL, ID, or pick from an optional typeahead. | |
Rule Actions | Build one or more custom action for Asana’s Rules engine to help users automate their work. Users can create rules that run your action when triggered. | |
Entry Point | Configure the button in tasks that initiates the Lookup and Modal Form. To configure this, one or both of these capabilities must be configured first. |
Configure the Installation Flow
When a user connects an app with App Components to Asana for the first time, they will go through an installation flow. There are a number of configurations that can be made here, including:
Property | Description | |
Headline | Text that appears as a title on the overview of features (i.e., "value props"). | |
Subhead | Text that appears as a subtitle on the overview of features. | |
Feature image | The image representing a feature. For the best user experience, we recommend providing three Feature image s. | |
Caption text | Text below the image of a feature. | |
Image alt text | Alt text for image of feature. | |
Authentication URL | A URL which informs Asana where to make requests for authenticating and authorizing users. This is called during installation or when the app returns a response indicating the user must authenticate to continue. |
To make these configurations, navigate to the Install your app tab and provide your configurations:
For an in-depth overview of the installation flow (including its customizations), see the Installing Flow.
Next Steps
BETA - For access, please see Overview of App Components
At this point, your app has been created and fully configured. For further configurations (e.g., updating a URL, replacing button text, etc.), you can head back into the developer console to make any necessary changes.
Next, you'll want to finish building the App Server. Leveraging the URLs configured earlier in this guide, this is what enables your end users to interact with resources external to Asana (i.e., via requests to endpoints exposed on the App Server).
When both your app and your App Server are complete, you can move forward with getting your app ready for publishing.
Building the App Server
BETA - For access, please see Overview of App Components
Because apps built with App Components allow end users to interact with resources external to Asana, an App Server is required in order for your app to function. Asana will make requests directly to endpoints exposed on the App Server, which controls, for example, what the user sees in a Widget or what happens when the user takes certain actions.
To see an example server written in Express.js, check out the app-components-example-app on GitHub. This server is also used in the Example App.
As a final note, we recommend creating and configuring your app before moving forward with building the App Server. After you have completed building both the app and App Server, you will be ready to begin the publishing process.
Authorization
BETA - For access, please see Overview of App Components
<!-- Example: An app might return this HTML in response to the
Authentication URL request after the Oauth flow is completed:
-->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>You have successfully connected Asana to the app</title>
</head>
<body>
Success!
<script>
window.opener.postMessage("success", "https://app.asana.com");
window.close();
</script>
</body>
</html>
Overview
The Asana platform needs confirmation from the App Components app that authentication has completed successfully.
When an app is added to a project, the user adding that app is sent to its Authentication URL
(see the Installation Flow). The app may perform OAuth with Asana, OAuth with a
different app, perform both, or perform none. For apps intended for multi-user usage, OAuth with Asana is
required to securely determine the identity of the user performing the authorization. Otherwise, as long as
the app confirms the flow was complete, Asana will successfully add the app to the project. This will allow
requests to be sent to the app's predefined endpoints.
How it works
Under the hood, we carry this out by listening for a message from the authentication popup window containing the string "success".
When we make a request to the app's Authentication URL
, the browser opens a popup or "child" window and waits for it to respond
with "success" using window.postMessage. The target window
for this postMessage
call should be the opener, accessible via
window.opener.
Note that for security purposes, the origin of the event (which is added to the event by the browser) needs to match the root of the
Authentication URL
registered to the app. That is, the authentication success message must be initiated from the same origin that receives the
authentication request. This is different from the targetOrigin
of the window.opener.postMessage
call, which must be exactly
"https://app.asana.com"
.
Additional notes
If the app wants additional data from Asana or wants to make changes within Asana, they should have the user complete an OAuth flow against Asana.
Keep in mind that this authorization provides the App Server with a single user's auth token. Multiple users of Asana will view external resources attached by a user who has authenticated and send requests to the App Server, but the server will likely only have the token for one user. You may want to suggest users to authenticate with a bot account.
Security
BETA - For access, please see Overview of App Components
When handling requests from Asana, an App Components app should:
- Add cross-origin resource sharing (CORS) headers to responses. In order to update the Asana user interface (e.g., populating a Widget with external data), requests are made from the client to your app server. As such, enabling and configuring CORS is required. Feel free to use your browser's developer tools to debug during development.
- Reject requests with missing or incorrect signatures. See Message Integrity for more details.
- Reject requests with an
expires_at
time in the past.- Note: Make sure to use the correct units for this.
expires_at
is in milliseconds. If you compare the expiration time to a timestamp in seconds, it will always look like the request expires thousands of years in the future.
- Note: Make sure to use the correct units for this.
If an app uses OAuth for authentication, the app should:
- Prevent OAuth CSRF attacks. A one-time CSRF token in the
state
parameter is required in order to implement a secure OAuth flow. Omitting thestate
parameter is a security risk. If thestate
parameter is not used, or not tied to the user's session, then attackers can initiate an OAuth flow themselves before tricking a user's browser into completing it. For more information about thestate
parameter, see OAuth.
If an app doesn't use OAuth for authentication, the Asana Security Team should manually review the authentication scheme the app uses. In particular, we will try to verify that:
- An attacker can't authenticate themselves as someone else
- An attacker can't force a victim to authenticate as another user (e.g., with a CSRF attack)
Message Integrity
BETA - For access, please see Overview of App Components
The burden of verifying the request is on the app. Without this check, attackers can send requests to the App Server pretending to be Asana.
Message integrity is provided by a SHA-256 HMAC signature on the contents of the request. For GET
requests, the "message" used
to generate the signature is the query string of the request with escaped characters, omitting the leading "?" of the query string.
For POST
requests, the "message" is the JSON blob in the data
field of the request body. For both types of requests, the secret
used to compute the signature is your app's Client Secret which can be found in the OAuth tab for the app in the
developer console.
Note that the signature is transmitted via a header in the request body, particularly the value of x-asana-request-signature
. The
app server calculates the same signature and compares that to the value in the header. The app server should reject the request if the two do not match.
The signature must be on the exact parameter string that will be passed to the app, since the signature will change if something as
trivial as spacing changes.
To see an example of how the signature is computed, you can view an open source example app server in the app-components-example-app repository.
Timeliness
BETA - For access, please see Overview of App Components
Timeliness is provided by the addition of an expiration parameter: expires_at
. If this parameter were not added, then a recorded request (e.g., a log), could be reused to continue requesting information from the app at a later time.
The burden of verifying the request has not expired is on the app. Without this check, the App Server is vulnerable to replay attacks.
Hosting
BETA - For access, please see Overview of App Components
Apps built with App Components allow end users to interact with resources external to Asana. As such an App Server is required in order for your app to function.
The following list includes providers and services commonly used for hosting an app server:
During development, you may choose to use ngrok, which creates a public URL that "tunnels" into localhost. We do not advise the use of ngrok beyond testing and debugging purposes.
Final Steps
BETA - For access, please see Overview of App Components
As you finish building the App Server, you may find it necessary to update certain configurations such as URLs, image links, etc. These configurations can be updated at any time in the developer console.
After you have finished building both your app and App Server, you are now ready to begin the publishing process!
Publishing an App
BETA - For access, please see Overview of App Components
After creating and configuring your app to function alongside your App Server, you may begin the app review process.
Apps built on App Components are manually reviewed before they are accessible within Asana. To ensure a smooth review process and user experience, here are some guidelines you can follow before submitting the app for review.
Publishing Checklist
BETA - For access, please see Overview of App Components
When configuring your app, you should:
- Add necessary images (e.g., feature images, icon, logo, etc.)
- Add links to supporting information and/or documentation (e.g., app landing page URL, support URL, etc.)
- Proofread marketing-related text (e.g., description, extended description, features)
- Make sure button text has 3-4 words or fewer and start with a verb
- Use consistent language for similar concepts where applicable
- Use sentence case by default and capitalize proper nouns
When testing your application, you should:
- Try to "break" your forms (e.g., test watched fields, limit invalid submissions, test typeahead fetches, etc.)
- Test and proof-read any custom error messages
- Test the auth flow from both the web browser and desktop app
- You can enter the installation flow manually by navigating to
https://app.asana.com/-/install_platform_ui_app?app_id=<app_client_id>
- You can enter the installation flow manually by navigating to
- Test Rule Actions with a variety of trigger combinations
Installation Flow
BETA - For access, please see Overview of App Components
When the end user connects an app with App Components to Asana for the first time, they will go through an installation flow. This involves walking the user through the app's features (i.e., "value props"), authorizing the app, and adding it to projects in Asana.
The installation flow can be configured in the developer console. Note that a list of all possible configurations can also be found in Configure the App in the Getting Started guide.
For the end user, the installation flow can be triggered through either one of two ways:
- The in-product app gallery. Users can access the app gallery by going into a project (in which they want to install an app), then navigating to Customize > Add App.
- The Asana app directory:
Note that subsequent interactions with the same application by the same user will not trigger the following installation flow. To force the installation flow in its entirety again (e.g., for QA purposes), you can visit https://app.asana.com/-/install_platform_ui_app?app_id=<app_client_id>
, replacing the value of the app_id
query parameter with the application's Client ID (accessible via the developer console).
Features
BETA - For access, please see Overview of App Components
After entering the installation flow, the first screen that users see are the app's features, or value props.
As part of the customizations, a Headline
and Subhead
can be shown at the top of the screen. Additionally, up to three Feature image
s can be displayed on the screen, each containing the image itself, accompanying Caption text
to display under each image, as well as Image alt text
text. We recommend configuring all three Feature images
for the best user experience.
Authenticating
BETA - For access, please see Overview of App Components
On the next screen, the user will be directed to the auth screen, which will ask them to connect to the external app.
When the user clicks the button to continue, Asana will make a request to the application's specified Authentication URL
in a pop-up window. From here, it is developer's discretion as to how the user proceeds with authentication. In most cases, this authentication step usually involves completing the Asana OAuth flow, as well as the third-party (i.e., external) OAuth flow.
Additionally, you may choose to present custom screens, forms, or otherwise logic to prompt the user for additional information needed to set up the application.
The authentication flow is concluded when the app confirms that authentication is complete with a "success" message using window.postMessage. For more information, feel free to review Authorization requirements when publishing an app.
Adding to a Project
BETA - For access, please see Overview of App Components
Once the user has successully granted permissions, they'll be taken to different screens depending on how they entered the installation flow:
- If the user began the installation flow from outside of a project (e.g., through the Asana app directory), the user will be shown an additional screen that prompts them to add the app to any necessary projects. This screen will not be shown otherwise.
From here, the user may choose to add the app to one or more projects, or even skip adding the app for the time being. Once the user has made their choice, the final screen will confirm the user's choices, and the installation flow will be completed.
- If the user began the installation flow from within a project, the user will see a confirmation of the app they've added, and the installation flow will be completed.
Submit for Review
BETA - For access, please see Overview of App Components
After you have completed development of your app (and you have addressed the guidelines above), you can begin the process to have your app published on Asana.
Troubleshooting
Common Issues
App Component shows "Something went wrong. Try again later."
This typically happens when we receive a response from the app server that we do not understand. To ensure that Asana is able to read the response from the app server, check that the app server is returning the required properties listed in the corresponding schema of the endpoint being called (see App Component Schemas). Additionally, for certain properties like color
and width
, check that the value the app server is returning is a valid option under the Enumerated Values dropdown of an App Component schema.
Another reason that you may be seeing this message is when your app server is not using CORS. In order to update the Asana user interface (e.g., populating a Widget with external data), requests are made from the client to your app server. As such, enabling and configuring CORS is required. See Security for more information.
App server endpoints are not being triggered
Check that the endpoint paths saved for your app in the developer console match the endpoint paths that you created for your app server. For example, your app server's endpoint to GET Form Metadata might be https://app.example.com/form/metadata
, while in your app's settings it is saved as https://app.example.com/metadata
. Since these paths are non-matching, when Asana makes a request to GET Form Metadata, it will be making requests to https://app.example.com/metadata
instead of https://app.example.com/form/metadata
.
Additionally, some app server responses may contain an on_change_callback
and an on_submit_callback
property. Check that the endpoints provided for these values are what you expected.
Unable to trigger installation process again
In the event that you would like to test your app's installation flow again, you can visit https://app.asana.com/-/install_platform_ui_app?app_id=<app_client_id>
. You can find your app_client_id
in the URL of your app in the developer console.
App Component - Rule Action: App server is not receiving a response back from Asana
The app server for Rule Action must be hosted in order for Rule Actions to function. For a brief list of popular hosting options, see Hosting.
App does not appear in the app gallery of my organization
Ensure that your app is added to your organization. This can be done in your app's setting in the developer console under Install your app > Add an organization.
For any questions on App Components, as well as an opportunity to engage with other developers in the community, feel free to visit our App Components forum
Additional Resources
Configurations
BETA - For access, please see Overview of App Components
The following tables represent a master list of all the configurations you can make to define your App Components app. Further context for these configurations can be found in the Configure the App section of the Getting Started guide. Feel free to also review the Toolkit for a visual documentation of these configurations. To make these configurations, visit the developer console.
Note: You must first create an app in order to be able to configure it. To begin, see the Getting Started guide.
Configurations for Basic Information
Property | Description | |
App icon | Your app's icon, shown to users to identify your application. | |
App name | Your app's name, shown to users to identify your application. | |
Short description | A short description of the app shown in the app gallery. | |
Long description | An extended description of the functionality of the app shown in the app settings. | |
Company name | Your company name. | |
Company URL | URL of the page where users can learn more about your company. | |
App landing page URL | URL of the page where users can learn more about this app and install it. | |
Support URL | URL of the page where users can read documentation or get support. | |
Privacy policy URL | URL of the page where users can read your app's privacy policy. |
Configurations for Widget
Property | Description | |
Widget metadata URL | A URL that Asana uses to make requests for the data needed to load a Widget, which displays information about a third party resource. | |
Match URL pattern | A regex which allows Asana to compute whether a URL attachment is supported by an activated app on the project in order to render a Widget. |
Configurations for Modal Form
Property | Description | |
Form metadata URL | A URL that Asana uses to request data from the app about fields it should display in the Modal Form. |
Configurations for Lookup
Property | Description | |
Resource attach URL | A URL that Asana will make a request to when a user submits a value to attach (i.e., when clicking "Add"). | |
Placeholder text | Optional. Placeholder action text that appears in the Lookup input field after the user clicks on the Lookup action text. | |
Resource typeahead URL | A URL that Asana will make a request to when a user types into a Lookup field. |
Configurations for Rule Action
Property | Description | |
Display name | The Rule Action name visible to end users in the rule builder (e.g., "Create a Jira issue"). | |
Run action URL | A URL that Asana will make a request to when the rule is triggered. | |
Form metadata URL | A URL that Asana will make a request to to display the configuration form. |
Configurations for Entry Point
Property | Description | |
Lookup action text | Clickable action text that allows users to initiate a Lookup. | |
Modal Form action text | Clickable action text that allows users to initiate a Modal Form. |
Configurations for the Installation Flow
Property | Description | |
Headline | Text that appears as a title on the overview of features (i.e., "value props"). | |
Subhead | Text that appears as a subtitle on the overview of features. | |
Feature image | The image representing a feature. For the best user experience, we recommend providing three Feature image s. | |
Caption text | Text below the image of a feature. | |
Image alt text | Alt text for image of feature. | |
Authentication URL | A URL which informs Asana where to make requests for authenticating and authorizing users. This is called during installation or when the app returns a response indicating the user must authenticate to continue. |
Example Apps
Modal Form & Widget
BETA - For access, please see Overview of App Components
The example app offers a quick way for developers to explore the capabilities and features of App Components. By following the steps below, you'll gain an understanding of how to install App Component apps to your developer sandbox, as well as how an example app communicates with endpoints exposed on a pre-built local server.
Note that for the App Components apps that you create, you'll be able to configure your own images, descriptions, URLs, and other content. Many of the values for these fields are marked by {curly braces} in the example app.
Before you begin, be sure you already have a developer sandbox, as this will give you access the "External Example App" in the app gallery. To start using the example app:
- Clone this repository containing an example Express server.
- Follow the instructions in the README to run the server. This server needs to remain on as you use the example app.
- Open the developer sandbox in your browser.
- In an existing project, go to Customize > Add App > External Example App to install the App Components example app.
- Important: The installation flow this takes you through is only shown once per user. To see it a second time, navigate to
https://app.asana.com/-/install_platform_ui_app?app_id=<app_client_id>
, replacing the value of theapp_id
query parameter with the application's Client ID (accessible via the developer console).
- Important: The installation flow this takes you through is only shown once per user. To see it a second time, navigate to
- Once the example app is installed, create a task in your project. In the task's {Example} custom field, go to {Add Example Resource} > {Open form} to see examples of customizable inputs. Click Submit.
- View the newly-generated Widget on your task. You can begin editing index.js to modify the contents of the widget. Note that you'll need to restart the local server and reload the page to see your changes.
That's it! At this point, feel free to keep exploring how changes in the server affects data in the task's Widget. Once you're ready to define an app, click here to create your own app with App Components.
Example Rule Actions
BETA - For access, please see Overview of App Components
To explore the capabilities of Rule Actions, see our app-components-rule-action-example-app on GitHub. Follow the instructions outlined in the repository's README.md
to get started.
Toolkit
BETA
Our App Components Toolkit provides a visual documentation of App Components. You'll see at-a-glance how the different features and capabilities surface within Asana, including how they fit together and what you can do with them. Feel free to use the toolkit to supplement the process of designing and building your apps with App Components.
Forum
BETA
For the latest news on App Components, as well as opportunity to engage with other developers in the community, feel free to visit our App Components forum.
App Component Reference
BETA - For access, please see Overview of App Components
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
This is the interface for handling requests for App Components. This reference is generated from an OpenAPI spec.
Base URLs:
- {siteUrl}
Note that {siteUrl} refers to the base URL for your App Server endpoints.
Additional resources:
Modal Forms
BETA - For access, please see Overview of App Components
GET /{form_metadata_url}
GET /{modal_form_typeahead_url}
POST /{on_change_callback}
POST /{on_submit_callback}
The Modal Form is displayed when the user starts the flow to create a resource. Asana will make a signed request to the specified form_metadata_url
in the configuration, and expect a response with the metadata needed to create the form. This process is also used for forms within Rule Actions.
Get form metadata
BETA - For access, please see Overview of App Components
Code samples
curl -X GET {siteUrl}/{form_metadata_url}?workspace=string&task=string&user=string&expires_at=string \
-H 'Accept: application/json'
200 Response
{
"metadata": {
"fields": [],
"on_change_callback": "https://www.example.com/on_change",
"on_submit_callback": "https://www.example.com/on_submit",
"submit_button_text": "Create New Issue",
"title": "Create New Issue"
},
"template": "form_metadata_v0"
}
See Input/Output Options to include more fields in your response.
GET /{form_metadata_url}
Get the metadata from the App Server to render a form.
Parameters
Name | Description | |
?workspace string required | The workspace gid this hook is coming from. | |
?task string required | The task gid this hook is coming from. | |
?user string required | The user gid this hook is coming from. | |
?expires_at string required | The time (in ISO-8601 date format) when the request should expire |
Responses
Status | Description | ||||
200 FormMetadata | Successfully retrieved the metadata for a single form. | ||||
↓ Show Common Responses ↓ |
Get Modal Form typeahead results
BETA - For access, please see Overview of App Components
Code samples
curl -X GET {siteUrl}/{modal_form_typeahead_url} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
Body parameter
{
"expires_at": "2019-04-15T01:01:46.055Z",
"query": "Messages",
"task": "67890",
"user": "54321",
"workspace": "12345"
}
200 Response
{
"header": "List of messages",
"items": [
{
"icon_url": "https://example-icon.png",
"subtitle": "OTP",
"title": "OTP Team PF",
"value": "OTP"
}
]
}
See Input/Output Options to include more fields in your response.
GET /{modal_form_typeahead_url}
If a Modal Form form field is of type typehead
, this operation gets typeahead results to render as a dropdown list.
When the user types into a Modal Form form field, Asana will send a request containing the entered string to the application's typeahead_url
. The list of TypeaheadItems in the response will then be rendered in a dropdown list.
Parameters
Name | Description | |
body object required | Request to retrieve typeahead results in a Modal Form typeahead form field. |
Responses
Status | Description | ||||
200 TypeaheadList | Successfully retrieved typeahead results. | ||||
↓ Show Common Responses ↓ |
On change callback
BETA - For access, please see Overview of App Components
Code samples
curl -X POST {siteUrl}/{on_change_callback} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"data": {"field":"value","field":"value"} }'
Body parameter
{
"changed_field": "string",
"expires_at": "string",
"task": "string",
"user": "string",
"workspace": "string"
}
200 Response
{
"metadata": {
"fields": [],
"on_change_callback": "https://www.example.com/on_change",
"on_submit_callback": "https://www.example.com/on_submit",
"submit_button_text": "Create New Issue",
"title": "Create New Issue"
},
"template": "form_metadata_v0"
}
See Input/Output Options to include more fields in your response.
POST /{on_change_callback}
The callback request made to an App Server when a watched field's value changes within a form.
Parameters
Name | Description | |
body object required | Request to notify of an on change event. |
Responses
Status | Description | ||||
200 FormMetadata | Successfully returned the new state of the form. | ||||
↓ Show Common Responses ↓ |
On submit callback
BETA - For access, please see Overview of App Components
Code samples
curl -X POST {siteUrl}/{on_submit_callback} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"data": {"field":"value","field":"value"} }'
Body parameter
{
"expires_at": "string",
"task": "string",
"user": "string",
"values": {
"property1": {
"field_name": "string",
"field_object": {}
},
"property2": {
"field_name": "string",
"field_object": {}
}
},
"workspace": "string"
}
200 Response
{
"error": "No resource matched that input",
"resource_name": "Build the Thing",
"resource_url": "https://example.atlassian.net/browse/CP-1"
}
See Input/Output Options to include more fields in your response.
POST /{on_submit_callback}
The callback request made to an App Server when a form is submitted.
Parameters
Name | Description | |
body object required | Request to notify of a form submission. |
Detailed descriptions
field_object: A form field object.
Valid object schemas: FormField-Checkbox, FormField-Date, FormField-Datetime, FormField-Dropdown, FormField-MultiLineText, FormField-RadioButton, FormField-RichText, FormField-SingleLineText, FormField-StaticText, FormField-Typeahead
Responses
Status | Description | ||||
200 AttachedResource | Successfully attached the resource created by the form. | ||||
↓ Show Common Responses ↓ |
Rule Actions
BETA - For access, please see Overview of App Components
GET /{rule_action_typeahead_url}
POST /{run_action_url}
GET /{action.metadata_url}
POST /{action.on_change_callback}
POST /{action.on_submit_callback}
When a rule containing a Rule Action is triggered, the Rules Engine will make a request to the app to inform the app to run the configured Rule Action. The resulting status code will indicate to the Rules Engine whether the action was successfully completed and, if not, specify a cause for the error.
Get Rule Action typeahead results
BETA - For access, please see Overview of App Components
Code samples
curl -X GET {siteUrl}/{rule_action_typeahead_url} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
Body parameter
{
"expires_at": "2019-04-15T01:01:46.055Z",
"query": "Messages",
"task": "67890",
"user": "54321",
"workspace": "12345"
}
200 Response
{
"header": "List of messages",
"items": [
{
"icon_url": "https://example-icon.png",
"subtitle": "OTP",
"title": "OTP Team PF",
"value": "OTP"
}
]
}
See Input/Output Options to include more fields in your response.
GET /{rule_action_typeahead_url}
In a Rule Action typeahead form field, this operation gets typeahead results to render as a dropdown list.
When the user types into a Rule Action form field, Asana will send a request containing the entered string to the application's typeahead_url
. The list of TypeaheadItems in the response will then be rendered in a dropdown list.
Parameters
Name | Description | |
body object required | Request to retrieve typeahead results in a Rule Action typeahead form field. |
Responses
Status | Description | ||||
200 TypeaheadList | Successfully retrieved typeahead results. | ||||
↓ Show Common Responses ↓ |
Run action
BETA - For access, please see Overview of App Components
Code samples
curl -X POST {siteUrl}/{run_action_url} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"data": {"field":"value","field":"value"} }'
Body parameter
{
"action": "string",
"action_type": "string",
"expires_at": "string",
"idempotency_key": "string",
"target_object": "string",
"user": "string",
"workspace": "string"
}
200 Response
{
"action_result": "ok",
"error": "That resource no longer exists",
"resources_created": [
{
"error": "No resource matched that input",
"resource_name": "Build the Thing",
"resource_url": "https://example.atlassian.net/browse/CP-1"
}
]
}
See Input/Output Options to include more fields in your response.
POST /{run_action_url}
The request made when an action is triggered.
Parameters
Name | Description | |
body object required | Request to notify of an action running. |
Responses
Status | Description | ||||
200 RanAction | Successfully attached the resource created by the form. | ||||
↓ Show Common Responses ↓ |
Get action metadata
BETA - For access, please see Overview of App Components
Code samples
curl -X GET {siteUrl}/{action.metadata_url}?action_type=string&project=string&workspace=string&user=string&expires_at=string \
-H 'Accept: application/json'
200 Response
{
"metadata": {
"fields": [],
"on_change_callback": "https://www.example.com/on_change",
"on_submit_callback": "https://www.example.com/on_submit",
"submit_button_text": "Create New Issue",
"title": "Create New Issue"
},
"template": "form_metadata_v0"
}
See Input/Output Options to include more fields in your response.
GET /{action.metadata_url}
When a user has navigated to the Custom Rule builder UI and selected a Rule Action (either through the sidebar or via a Rule Preset), Asana will make a request to the app to get the configuration form definition for the chosen Rule Action. This will initiate the flow to configure a new Rule Action or edit the configuration of an existing Rule Action. This is the endpoint and schema for updating Rule Actions; app triggers (V2) will be analogous.
Parameters
Name | Description | |
?action string | The ID of an existing Rule Action that is being edited. Should be omitted when configuring a new Rule Action. | |
?action_type string required | The ID of the configuration used to create the Rule Action. | |
?project string required | The project gid this hook is coming from. | |
?workspace string required | The workspace gid this hook is coming from. | |
?user string required | The user gid this hook is coming from. | |
?expires_at string required | The time (in ISO-8601 date format) when the request should expire |
Responses
Status | Description | ||||
200 FormMetadata | Successfully retrieved the metadata for a single action. | ||||
↓ Show Common Responses ↓ |
On action change callback
BETA - For access, please see Overview of App Components
Code samples
curl -X POST {siteUrl}/{action.on_change_callback} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"data": {"field":"value","field":"value"} }'
Body parameter
{
"action": "string",
"action_type": "string",
"changed_field": "string",
"expires_at": "string",
"project": "string",
"user": "string",
"workspace": "string"
}
200 Response
{
"metadata": {
"fields": [],
"on_change_callback": "https://www.example.com/on_change",
"on_submit_callback": "https://www.example.com/on_submit",
"submit_button_text": "Create New Issue",
"title": "Create New Issue"
},
"template": "form_metadata_v0"
}
See Input/Output Options to include more fields in your response.
POST /{action.on_change_callback}
The callback request made to an App Server when a watched field's value changes within an action form.
Parameters
Name | Description | |
body object required | Request to notify of an on change event. |
Responses
Status | Description | ||||
200 FormMetadata | Successfully returned the new state of the form. | ||||
↓ Show Common Responses ↓ |
On action submit callback
BETA - For access, please see Overview of App Components
Code samples
curl -X POST {siteUrl}/{action.on_submit_callback} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"data": {"field":"value","field":"value"} }'
Body parameter
{
"action": "string",
"action_type": "string",
"expires_at": "string",
"project": "string",
"rule_name": "string",
"task": "string",
"user": "string",
"values": {
"property1": {
"field_name": "string",
"field_object": {}
},
"property2": {
"field_name": "string",
"field_object": {}
}
},
"workspace": "string"
}
400 Response
{
"metadata": {
"fields": [],
"on_change_callback": "https://www.example.com/on_change",
"on_submit_callback": "https://www.example.com/on_submit",
"submit_button_text": "Create New Issue",
"title": "Create New Issue"
},
"template": "form_metadata_v0"
}
See Input/Output Options to include more fields in your response.
POST /{action.on_submit_callback}
The form is submitted when the user chooses to create their Rule. Asana will create the Rule Action data model object and make a signed request to the on_submit_callback specified in the form metadata returned from the fetch/update Rule Action form endpoints. Information about the created Rule Action should be included in the response if it was successfully created. This is the endpoint and schema for updating Rule Actions; app triggers (V2) will be analogous.
Parameters
Name | Description | |
body object required | Request to submit an action form. |
Detailed descriptions
field_object: A form field object.
Valid object schemas: FormField-Checkbox, FormField-Date, FormField-Datetime, FormField-Dropdown, FormField-MultiLineText, FormField-RadioButton, FormField-RichText, FormField-SingleLineText, FormField-StaticText, FormField-Typeahead
Responses
Status | Description | ||||
200 None | Successfully handled form submission. | ||||
↓ Show Common Responses ↓ |
Lookups
BETA - For access, please see Overview of App Components
POST /{resource_attach_url}
GET /{resource_typeahead_url}
If the app defined a resource attach URL, tasks without a Widget offer the Lookup functionality. This appears as a text input to the user. When the user submits the text, the app responds with either a resource attachment or with an error.
Attach resource
BETA - For access, please see Overview of App Components
Code samples
curl -X POST {siteUrl}/{resource_attach_url} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"data": {"field":"value","field":"value"} }'
Body parameter
{
"attachment": "string",
"expires_at": "string",
"query": "string",
"task": "string",
"user": "string",
"workspace": "string"
}
200 Response
{
"error": "No resource matched that input",
"resource_name": "Build the Thing",
"resource_url": "https://example.atlassian.net/browse/CP-1"
}
See Input/Output Options to include more fields in your response.
POST /{resource_attach_url}
When the user attaches a resource URL to a task, Asana will make a signed request to the specified resource_attach_url
in the app configuration. Information about the attached resource should be included in the response.
Parameters
Name | Description | |
body object required | Request to attach a resource. |
Responses
Status | Description | ||||
200 AttachedResource | Successfully attached the resource to the given object. | ||||
↓ Show Common Responses ↓ |
Get Lookup typeahead results
BETA - For access, please see Overview of App Components
Code samples
curl -X GET {siteUrl}/{resource_typeahead_url} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
Body parameter
{
"expires_at": "2019-04-15T01:01:46.055Z",
"query": "Messages",
"task": "67890",
"user": "54321",
"workspace": "12345"
}
200 Response
{
"header": "List of messages",
"items": [
{
"icon_url": "https://example-icon.png",
"subtitle": "OTP",
"title": "OTP Team PF",
"value": "OTP"
}
]
}
See Input/Output Options to include more fields in your response.
GET /{resource_typeahead_url}
Gets typeahead results to render as a dropdown list in the resource lookup input field.
When the user types into the lookup input field, Asana will send a request containing the entered string to the application's typeahead_url
. The list of TypeaheadItems in the response will then be rendered in a dropdown list. When the user selects an item from the list, Asana will send a resource attach request to the app server, then process the response and render the attached resource in the widget.
Parameters
Name | Description | |
body object required | Request to retrieve typeahead results for a resource lookup query. |
Responses
Status | Description | ||||
200 TypeaheadList | Successfully retrieved typeahead results. | ||||
↓ Show Common Responses ↓ |
Widgets
BETA - For access, please see Overview of App Components
GET /{widget_metadata_url}
The Widget is displayed when the user views a task with an attachment with a resource URL matching your capability’s match_resource_url_pattern
. When this happens, Asana will make a signed request to your widget_metadata_url
, and expect a response with information to render in the Widget.
Get widget metadata
BETA - For access, please see Overview of App Components
Code samples
curl -X GET {siteUrl}/{widget_metadata_url}?resource_url=string&workspace=string&task=string&user=string&attachment=string&expires_at=string \
-H 'Accept: application/json'
200 Response
{
"metadata": {
"error": "The resource cannot be accessed",
"fields": [],
"footer": {},
"num_comments": 2,
"subicon_url": "https://example-icon.png",
"subtitle": "Custom App Story · Open in Custom App",
"title": "Status"
},
"template": "summary_with_details_v0"
}
See Input/Output Options to include more fields in your response.
GET /{widget_metadata_url}
Get the metadata from the App Server to render a widget.
Parameters
Name | Description | |
?resource_url string required | The URL of the URL attachment on the task (i.e. Jira issue, GitHub pull request) | |
?workspace string required | The workspace gid this hook is coming from. | |
?task string required | The task gid this hook is coming from. | |
?user string required | The user gid this hook is coming from. | |
?attachment string required | The attachment ID of the URL attachment. | |
?expires_at string required | The time (in ISO-8601 date format) when the request should expire |
Responses
Status | Description | ||||
200 WidgetMetadata | Successfully retrieved the metadata for a single widget. | ||||
418 Unauthorized | Unauthorized | ||||
↓ Show Common Responses ↓ |
App Component Schemas
BETA - For access, please see Overview of App Components
The schema definitions for each object requested or returned from Asana's API. Some fields are not returned by default and you'll need to use Input/Output Options to include them.
AttachedResource
BETA - For access, please see Overview of App Components
{
"error": "No resource matched that input",
"resource_name": "Build the Thing",
"resource_url": "https://example.atlassian.net/browse/CP-1"
}
The response to a successful lookup request.
Properties
Name | Description | |
error string | The error that should be displayed to the user | |
resource_name string required | The name of the attached resource | |
resource_url string required | The URL of the attached resource |
BadRequest
BETA - For access, please see Overview of App Components
{
"data": {
"error": "Illegal or malformed request."
}
}
An error response object indicating a bad request (i.e., a status code of 400
).
Properties
Name | Description | |
data object | An object containing an error string to display to the user. |
Forbidden
BETA - For access, please see Overview of App Components
{
"data": {
"error": "Access forbidden."
}
}
An error response object indicating a forbidden request (i.e., a status code of 403
).
Properties
Name | Description | |
data object | An object containing an error string to display to the user. |
FormField-Checkbox
BETA - For access, please see Overview of App Components
{
"error": "Please review and change your input",
"id": "create-resource-field-1",
"is_required": true,
"is_watched": true,
"name": "Resource name",
"options": [
{
"id": "opt-in",
"label": "Opt in"
}
],
"type": "checkbox",
"value": [
"opt-in"
]
}
A Modal Form field that accepts checkbox input. Limit 10 options.
Properties
Name | Description | |
error string | Optional. The developer-specified error message displayed to the user if there is an error with the chosen value. | |
id string required | The ID of the field, which is used to reference the field. These should be unique across the entire form. | |
is_required boolean | Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false . | |
is_watched boolean | Optional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false . | |
name string | The text (i.e., label) to show in the title of the field. Limit 50 characters. | |
options [object] required | An array (minimum length: 1) of CheckboxOption objects. | |
type string required | The type of Modal Form field. | |
value [string] | Optional. The values for the form field, which are the IDs of the chosen CheckboxOption objects. |
Enumerated Values
Property | Value | |
type | checkbox |
FormField-Date
BETA - For access, please see Overview of App Components
{
"error": "Please review and change your input",
"id": "date-field-1",
"is_required": true,
"is_watched": true,
"name": "Date",
"placeholder": "2022-02-01",
"type": "date"
}
A Modal Form field that accepts date input.
Properties
Name | Description | |
error string | Optional. The developer-specified error message displayed to the user if there is an error with the chosen value. | |
id string required | The ID of the field, which is used to reference the field. These should be unique across the entire form. | |
is_required boolean | Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false . | |
is_watched boolean | Optional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false . | |
name string | The text (i.e., label) to show in the title of the field. Limit 50 characters. | |
placeholder string | The placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder. | |
type string required | The type of Modal Form field. |
Enumerated Values
Property | Value | |
type | date |
FormField-Datetime
BETA - For access, please see Overview of App Components
{
"error": "Please review and change your input",
"id": "datetime-field-1",
"is_required": true,
"is_watched": true,
"name": "Datetime",
"placeholder": "2022-02-01T14:48:00.000Z",
"type": "datetime"
}
A Modal Form field that accepts datetime input.
Properties
Name | Description | |
error string | Optional. The developer-specified error message displayed to the user if there is an error with the chosen value. | |
id string required | The ID of the field, which is used to reference the field. These should be unique across the entire form. | |
is_required boolean | Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false . | |
is_watched boolean | Optional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false . | |
name string | The text (i.e., label) to show in the title of the field. Limit 50 characters. | |
placeholder string | The placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder. | |
type string required | The type of Modal Form field. |
Enumerated Values
Property | Value | |
type | datetime |
FormField-Dropdown
BETA - For access, please see Overview of App Components
{
"error": "Please review and change your input",
"id": "create-resource-field-1",
"is_required": true,
"is_watched": true,
"name": "Resource name",
"options": [
{
"icon_url": "https://example.com/red.png",
"id": "red",
"label": "Red"
}
],
"type": "dropdown",
"value": "dropdown_option_1",
"width": "full"
}
A Modal Form field that accepts input via a dropdown list. Limit 50 options.
Properties
Name | Description | |
error string | Optional. The developer-specified error message displayed to the user if there is an error with the chosen value. | |
id string required | The ID of the field, which is used to reference the field. These should be unique across the entire form. | |
is_required boolean | Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false . | |
is_watched boolean | Optional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false . | |
name string | The text (i.e., label) to show in the title of the field. Limit 50 characters. | |
options [object] required | An array (minimum length: 1) of DropdownOption objects. | |
type string required | The type of Modal Form field. | |
value string | Optional. The value for the form field, which is the ID of the chosen DropdownOption object. | |
width string | Optional. The width of the form field. If not provided, the default value will be "full" . |
Enumerated Values
Property | Value | |
type | dropdown | |
width | full | |
width | half |
FormField-MultiLineText
BETA - For access, please see Overview of App Components
{
"error": "Please review and change your input",
"id": "create-resource-field-1",
"is_required": true,
"is_watched": true,
"name": "Resource name",
"placeholder": "Enter the full title of the resource here",
"type": "multi_line_text",
"value": "Annual Kick-Off Meeting"
}
A Modal Form field that accepts multi-line text input.
Properties
Name | Description | |
error string | Optional. The developer-specified error message displayed to the user if there is an error with the chosen value. | |
id string required | The ID of the field, which is used to reference the field. These should be unique across the entire form. | |
is_required boolean | Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false . | |
is_watched boolean | Optional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false . | |
name string | The text (i.e., label) to show in the title of the field. Limit 50 characters. | |
placeholder string | The placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder. | |
type string required | The type of Modal Form field. | |
value string | The value of the field. If not provided, the field will be empty and the form cannot be submitted if it is required. Limit 3000 characters. |
Enumerated Values
Property | Value | |
type | multi_line_text |
FormField-RadioButton
BETA - For access, please see Overview of App Components
{
"error": "Please review and change your input",
"id": "create-resource-field-1",
"is_required": true,
"is_watched": true,
"name": "Resource name",
"options": [
{
"id": "blue",
"label": "Blue",
"sub_label": "#0000FF"
}
],
"type": "radio_button",
"value": "radio_option_1"
}
A Modal Form field that accepts radio button input. Limit 5 options.
Properties
Name | Description | |
error string | Optional. The developer-specified error message displayed to the user if there is an error with the chosen value. | |
id string required | The ID of the field, which is used to reference the field. These should be unique across the entire form. | |
is_required boolean | Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false . | |
is_watched boolean | Optional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false . | |
name string | The text (i.e., label) to show in the title of the field. Limit 50 characters. | |
options [object] required | An array (minimum length: 1) of RadioOption objects. | |
type string required | The type of Modal Form field. | |
value string | Optional. The value for the form field, which is the ID of the chosen RadioOption object. |
Enumerated Values
Property | Value | |
type | radio_button |
FormField-RichText
BETA - For access, please see Overview of App Components
{
"error": "Please review and change your input",
"id": "create-resource-field-1",
"is_required": true,
"is_watched": true,
"name": "Resource name",
"placeholder": "Enter the full title of the resource here",
"type": "rich_text",
"value": "Annual Kick-Off Meeting"
}
A Modal Form field that accepts rich text input.
Properties
Name | Description | |
error string | Optional. The developer-specified error message displayed to the user if there is an error with the chosen value. | |
id string required | The ID of the field, which is used to reference the field. These should be unique across the entire form. | |
is_required boolean | Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false . | |
is_watched boolean | Optional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false . | |
name string | The text (i.e., label) to show in the title of the field. Limit 50 characters. | |
placeholder string | The placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder. | |
type string required | The type of Modal Form field. | |
value string | The value of the field. If not provided, the field will be empty and the form cannot be submitted if it is required. Limit 3000 characters. |
Enumerated Values
Property | Value | |
type | rich_text |
FormField-SingleLineText
BETA - For access, please see Overview of App Components
{
"error": "Please review and change your input",
"id": "create-resource-field-1",
"is_required": true,
"is_watched": true,
"name": "Resource name",
"placeholder": "Enter the full title of the resource here",
"type": "single_line_text",
"value": "Annual Kick-Off Meeting",
"width": "full"
}
A Modal Form field that accepts single-line text input.
Properties
Name | Description | |
error string | Optional. The developer-specified error message displayed to the user if there is an error with the chosen value. | |
id string required | The ID of the field, which is used to reference the field. These should be unique across the entire form. | |
is_required boolean | Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false . | |
is_watched boolean | Optional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false . | |
name string | The text (i.e., label) to show in the title of the field. Limit 50 characters. | |
placeholder string | The placeholder for the input, which is shown if the field has no value. If not provided, there will be no placeholder. | |
type string required | The type of Modal Form field. | |
value string | The value of the field. If not provided, the field will be empty and the form cannot be submitted if it is required. Limit 200 characters. | |
width string | Optional. The width of the form field. If not provided, the default value will be "full" . |
Enumerated Values
Property | Value | |
type | single_line_text | |
width | full | |
width | half |
FormField-StaticText
BETA - For access, please see Overview of App Components
{
"id": "create-resource-field-1",
"name": "Please enter the following details:",
"type": "static_text"
}
A Modal Form "field" that displays static text. Fields of this type do not collect user input.
Properties
Name | Description | |
id string required | The ID of the field, which is used to reference the field. These should be unique across the entire form. | |
name string required | The text (i.e., label) for the field. Limit 50 characters. | |
type string required | The type of Modal Form field. |
Enumerated Values
Property | Value | |
type | static_text |
FormField-Typeahead
BETA - For access, please see Overview of App Components
{
"error": "Please review and change your input",
"id": "typeahead_field_1",
"is_required": true,
"is_watched": true,
"name": "Statuses",
"type": "typeahead",
"typeahead_url": "https://www.app-server.com/app/typeahead",
"value": "typeahead_1",
"width": "full"
}
A Modal Form field that accepts typeahead input.
Properties
Name | Description | |
error string | Optional. The developer-specified error message displayed to the user if there is an error with the chosen value. | |
id string required | The ID of the field, which is used to reference the field. These should be unique across the entire form. | |
is_required boolean | Optional. Indicates whether the field is required to submit the form. If this property is not specified, the value is assumed false . | |
is_watched boolean | Optional. Indicates whether the field should be watched. Fields that are watched send requests to the on_change URL specified in the form metadata to get updated form information. If this property is not specified, the value is assumed false . | |
name string | The text (i.e., label) to show in the title of the field. Limit 50 characters. | |
type string required | The type of Modal Form field. | |
typeahead_url string required | The URL that Asana uses to request typehead results from the application server. | |
value string | Optional. The value for the form field, which is the ID of the chosen TypeaheadListItem object. | |
width string | Optional. The width of the form field. If not provided, the default value will be "full" . |
Enumerated Values
Property | Value | |
type | typeahead | |
width | full | |
width | half |
FormMetadata
BETA - For access, please see Overview of App Components
{
"metadata": {
"fields": [],
"on_change_callback": "https://www.example.com/on_change",
"on_submit_callback": "https://www.example.com/on_submit",
"submit_button_text": "Create New Issue",
"title": "Create New Issue"
},
"template": "form_metadata_v0"
}
Contains the metadata that describes how to display and manage a form.
Properties
Name | Description | |
metadata object required | The metadata (i.e., underlying definition) of a form. metadata must exist alongside a template , and its schema must be specific to the value of that template . | |
template string required | The interface name and version of a distinct form UI layout. A template is directly associated with a particular metadata schema. |
Enumerated Values
Property | Value | |
template | form_metadata_v0 |
InternalServerError
BETA - For access, please see Overview of App Components
{
"data": {
"error": "Internal server error."
}
}
An error response object indicating a request that could not be found (i.e., a status code of 500
).
Properties
Name | Description | |
data object | An object containing an error string to display to the user. |
NotFound
BETA - For access, please see Overview of App Components
{
"data": {
"error": "Not found."
}
}
An error response object indicating a request that could not be found (i.e., a status code of 404
).
Properties
Name | Description | |
data object | An object containing an error string to display to the user. |
RanAction
BETA - For access, please see Overview of App Components
{
"action_result": "ok",
"error": "That resource no longer exists",
"resources_created": [
{
"error": "No resource matched that input",
"resource_name": "Build the Thing",
"resource_url": "https://example.atlassian.net/browse/CP-1"
}
]
}
The response to an action request.
Properties
Name | Description | |
action_result string required | Specifies any additional information that the app wants to send to Asana on completion of the action. Can only be resources_created or ok . | |
error string | The error that should be displayed to the user | |
resources_created [object] | A field with the data corresponding to the action_result value. Each action_result has its own data field shape that Asana expects. resources_created expects the name and url of the resources that the action created. |
Enumerated Values
Property | Value | |
action_result | resources_created | |
action_result | ok |
TypeaheadItem
BETA - For access, please see Overview of App Components
{
"icon_url": "https://example-icon.png",
"subtitle": "OTP",
"title": "OTP Team PF",
"value": "OTP"
}
An object describing a typeahead result.
Properties
Name | Description | |
icon_url string | The URL of the icon to display next to the title | |
subtitle string | The subtitle of the typeahead item | |
title string required | The title of the typeahead item | |
value string required | The value of the typeahead item |
TypeaheadList
BETA - For access, please see Overview of App Components
{
"header": "List of messages",
"items": [
{
"icon_url": "https://example-icon.png",
"subtitle": "OTP",
"title": "OTP Team PF",
"value": "OTP"
}
]
}
The response to a successful typeahead request.
Properties
Name | Description | |
header string | Optional. Header text to display above the list of typeahead results. If no header is passed in or the value is an empty string, only the typeahead results with be rendered. | |
items [object] required | Array of TypeaheadItem objects that indicate typeahead results. |
Unauthorized
BETA - For access, please see Overview of App Components
{
"data": {
"error": "Authorization required."
}
}
An error response object indicating a unauthorized request (i.e., a status code of 401
).
Properties
Name | Description | |
data object | An object containing an error string to display to the user. |
WidgetField-DatetimeWithIcon
BETA - For access, please see Overview of App Components
{
"datetime": "2012-02-22T02:06:58.147Z",
"icon_url": "https://example-icon.png",
"name": "Status",
"type": "datetime_with_icon"
}
A Widget field that displays a timestamp and an optional icon.
Properties
Name | Description | |
datetime string | The time (in ISO-8601 date format) to display next to the icon. | |
icon_url string | Optional. The URL of the icon to display next to the time. | |
name string required | The text (i.e., label) to show in the title of the field. Limit 40 characters. | |
type string required | The type of Widget field. |
Enumerated Values
Property | Value | |
type | datetime_with_icon |
WidgetField-Pill
BETA - For access, please see Overview of App Components
{
"color": "gray",
"name": "Status",
"text": "In Progress",
"type": "pill"
}
A Widget field that displays custom text in a colored "pill" format.
Properties
Name | Description | |
color string required | The color of the pill. | |
name string required | The text (i.e., label) to show in the title of the field. Limit 40 characters. | |
text string required | The text to show in the field. Limit 40 characters. | |
type string required | The type of Widget field. |
Enumerated Values
Property | Value | |
color | none | |
color | red | |
color | orange | |
color | yellow-orange | |
color | yellow | |
color | yellow-green | |
color | green | |
color | blue-green | |
color | aqua | |
color | blue | |
color | indigo | |
color | purple | |
color | magenta | |
color | hot-pink | |
color | pink | |
color | cool-gray | |
type | pill |
WidgetField-TextWithIcon
BETA - For access, please see Overview of App Components
{
"icon_url": "https://example-icon.png",
"name": "Status",
"text": "In Progress",
"type": "text_with_icon"
}
A Widget field that displays custom text with an optional icon.
Properties
Name | Description | |
icon_url string | Optional. The URL of the icon to display next to the text. | |
name string required | The text (i.e., label) to show in the title of the field. Limit 40 characters. | |
text string required | The text to show in the field. Limit 40 characters. | |
type string required | The type of Widget field. |
Enumerated Values
Property | Value | |
type | text_with_icon |
WidgetFooter-Created
BETA - For access, please see Overview of App Components
{
"created_at": "2012-02-22T02:06:58.147Z",
"footer_type": "created"
}
A Widget footer that displays the timestamp of the resource's creation time.
Properties
Name | Description | |
created_at string required | The time (in ISO-8601 date format) to show in the footer. | |
footer_type string required | The type of Widget footer. |
Enumerated Values
Property | Value | |
footer_type | created |
WidgetFooter-CustomText
BETA - For access, please see Overview of App Components
{
"footer_type": "custom_text",
"icon_url": "https://example-icon.png",
"text": "This is a custom footer message"
}
A Widget footer that displays custom text and an optional icon.
Properties
Name | Description | |
footer_type string required | The text to show in the footer. | |
icon_url string | Optional. The icon to show in the footer next to the text. If not provided, no icon will be shown. | |
text string required | The text to show in the footer. |
Enumerated Values
Property | Value | |
footer_type | custom_text |
WidgetFooter-Updated
BETA - For access, please see Overview of App Components
{
"footer_type": "updated",
"last_updated_at": "2012-02-22T02:06:58.147Z"
}
A Widget footer that displays the timestamp of the resource's last updated time.
Properties
Name | Description | |
footer_type string required | The type of Widget footer. | |
last_updated_at string required | The time (in ISO-8601 date format) to show in the footer. |
Enumerated Values
Property | Value | |
footer_type | updated |
WidgetMetadata
BETA - For access, please see Overview of App Components
{
"metadata": {
"error": "The resource cannot be accessed",
"fields": [],
"footer": {},
"num_comments": 2,
"subicon_url": "https://example-icon.png",
"subtitle": "Custom App Story · Open in Custom App",
"title": "Status"
},
"template": "summary_with_details_v0"
}
An object containing information about the widget.
Properties
Name | Description | |
metadata object required | The metadata (i.e., underlying definition) of a widget. metadata must exist alongside a template , and its schema must be specific to the value of that template . | |
template string required | The interface name and version of a distinct widget UI layout. A template is directly associated with a particular metadata schema. |
Enumerated Values
Property | Value | |
template | summary_with_details_v0 |
API Reference
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
This is the interface for interacting with the Asana Platform. Our API reference is generated from our OpenAPI spec.
Base URLs:
Additional resources:
Attachments
GET /attachments/{attachment_gid}
DELETE /attachments/{attachment_gid}
GET /attachments
POST /attachments
An attachment object represents any file attached to a task in Asana, whether it’s an uploaded file or one associated via a third-party service such as Dropbox or Google Drive.
Get an attachment
Code samples
curl -X GET https://app.asana.com/api/1.0/attachments/{attachment_gid} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
200 Response
{
"data": {
"gid": "12345",
"resource_type": "attachment",
"name": "Screenshot.png",
"resource_subtype": "dropbox",
"created_at": "2012-02-22T02:06:58.147Z",
"download_url": "https://s3.amazonaws.com/assets/123/Screenshot.png",
"host": "dropbox",
"parent": {
"gid": "12345",
"resource_type": "task",
"name": "Bug Task",
"resource_subtype": "default_task"
},
"permanent_url": "https://s3.amazonaws.com/assets/123/Screenshot.png",
"size": 12345,
"view_url": "https://www.dropbox.com/s/123/Screenshot.png"
}
}
See Input/Output Options to include more fields in your response.
GET /attachments/{attachment_gid}
Get the full record for a single attachment.
Parameters
Name | Description | ||||
/attachment_gid string required | Globally unique identifier for the attachment. | ||||
↓ Show Common Parameters ↓ |
Responses
Status | Description | ||||
200 Attachment | Successfully retrieved the record for a single attachment. | ||||
↓ Show Common Responses ↓ |
Delete an attachment
Code samples
curl -X DELETE https://app.asana.com/api/1.0/attachments/{attachment_gid} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
200 Response
{
"data": {}
}
See Input/Output Options to include more fields in your response.
DELETE /attachments/{attachment_gid}
Deletes a specific, existing attachment.
Returns an empty data record.
Parameters
Name | Description | ||||
/attachment_gid string required | Globally unique identifier for the attachment. | ||||
↓ Show Common Parameters ↓ |
Responses
Status | Description | ||||
200 Inline | Successfully deleted the specified attachment. | ||||
↓ Show Common Responses ↓ |
Response Schema
Status Code 200
Get attachments from an object
Code samples
curl -X GET https://app.asana.com/api/1.0/attachments?parent=159874 \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
200 Response
{
"data": [
{
"gid": "12345",
"resource_type": "attachment",
"name": "Screenshot.png",
"resource_subtype": "dropbox"
}
]
}
See Input/Output Options to include more fields in your response.
GET /attachments
Returns the compact records for all attachments on the object.
Parameters
Name | Description | ||||
?parent string required | Globally unique identifier for object to fetch statuses from. Must be a GID for a task or project_brief. | ||||
↓ Show Common Parameters ↓ |
Responses
Status | Description | ||||
200 AttachmentCompact | Successfully retrieved the specified object's attachments. | ||||
↓ Show Common Responses ↓ |
Upload an attachment
Code samples
curl -X POST https://app.asana.com/api/1.0/attachments \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}' \
-d '{"data": {"field":"value","field":"value"} }'
Body parameter
file: string
name: string
parent: string
resource_subtype: external
url: string
200 Response
{
"data": {
"gid": "12345",
"resource_type": "attachment",
"name": "Screenshot.png",
"resource_subtype": "dropbox",
"created_at": "2012-02-22T02:06:58.147Z",
"download_url": "https://s3.amazonaws.com/assets/123/Screenshot.png",
"host": "dropbox",
"parent": {
"gid": "12345",
"resource_type": "task",
"name": "Bug Task",
"resource_subtype": "default_task"
},
"permanent_url": "https://s3.amazonaws.com/assets/123/Screenshot.png",
"size": 12345,
"view_url": "https://www.dropbox.com/s/123/Screenshot.png"
}
}
See Input/Output Options to include more fields in your response.
POST /attachments
Upload an attachment.
This method uploads an attachment on an object and returns the compact record for the created attachment object. This is possible by either:
- Providing the URL of the external resource being attached, or
- Downloading the file content first and then uploading it as any other attachment. Note that it is not possible to attach files from third party services such as Dropbox, Box, Vimeo & Google Drive via the API
The 100MB size limit on attachments in Asana is enforced on this endpoint.
This endpoint expects a multipart/form-data encoded request containing the full contents of the file to be uploaded.
Requests made should follow the HTTP/1.1 specification that line
terminators are of the form CRLF
or \r\n
outlined
here
in order for the server to reliably and properly handle the request.
Parameters
Name | Description | ||||
body object required | The file you want to upload. | ||||
↓ Show Common Parameters ↓ |
Detailed descriptions
body: The file you want to upload.
Note when using curl:
Be sure to add an ‘@’
before the file path, and use the --form
option instead of the -d
option.
When uploading PDFs with curl, force the content-type to be pdf by
appending the content type to the file path: --form
"file=@file.pdf;type=application/pdf"
.
Enumerated Values
Parameter | Value | |
resource_subtype | asana_file_attachments | |
resource_subtype | external |
Responses
Status | Description | ||||
200 Attachment | Successfully uploaded the attachment to the parent object. | ||||
↓ Show Common Responses ↓ |
Audit Log API
GET /workspaces/{workspace_gid}/audit_log_events
Asana's Audit Log is an immutable log of important events in your organization's Asana instance.
The Audit Log API allows you to monitor and act upon important security and compliance-related changes. Organizations might use this API endpoint to:
- Set up proactive alerting with a Security Information and Event Management (SIEM) tool like Splunk
- Conduct reactive investigations when a security incident takes place
- Visualize key domain data in aggregate to identify security trends
Note that since the API provides insight into what is happening in an Asana instance, the data is read-only. That is, there are no "write" or "update" endpoints for audit log events.
Only Service Accounts in Enterprise Domains can access Audit Log API endpoints. Authentication with a Service Account's Personal Access Token is required.
For a full list of supported events, see Supported AuditLogEvents.
Get audit log events
Code samples
curl -X GET https://app.asana.com/api/1.0/workspaces/{workspace_gid}/audit_log_events \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
200 Response
{
"data": [
{
"gid": "12345",
"actor": {
"actor_type": "user",
"email": "gregsanchez@example.com",
"gid": "1111",
"name": "Greg Sanchez"
},
"context": {
"api_authentication_method": "cookie",
"client_ip_address": "1.1.1.1",
"context_type": "web",
"oauth_app_name": "string",
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
},
"created_at": "2021-01-01T00:00:00.000Z",
"details": {},
"event_category": "deletion",
"event_type": "task_deleted",
"resource": {
"email": "string",
"gid": "1111",
"name": "Example Task",
"resource_subtype": "milestone",
"resource_type": "task"
}
}
]
}
See Input/Output Options to include more fields in your response.
GET /workspaces/{workspace_gid}/audit_log_events
Retrieve the audit log events that have been captured in your domain.
This endpoint will return a list of AuditLogEvent objects, sorted by creation time in ascending order. Note that the Audit Log API captures events from October 8th, 2021 and later. Queries for events before this date will not return results.
There are a number of query parameters (below) that can be used to filter the set of AuditLogEvent objects that are returned in the response. Any combination of query parameters is valid. When no filters are provided, all of the events that have been captured in your domain will match.
The list of events will always be paginated. The default limit is 1000 events. The next set of events can be retrieved using the offset
from the previous response. If there are no events that match the provided filters in your domain, the endpoint will return null
for the next_page
field. Querying again with the same filters may return new events if they were captured after the last request. Once a response includes a next_page
with an offset
, subsequent requests can be made with the latest offset
to poll for new events that match the provided filters.
When no offset
is provided, the response will begin with the oldest events that match the provided filters. It is important to note that AuditLogEvent objects will be permanently deleted from our systems after 90 days. If you wish to keep a permanent record of these events, we recommend using a SIEM tool to ingest and store these logs.
Parameters
Name | Description | ||||
/workspace_gid string required | Globally unique identifier for the workspace or organization. | ||||
?start_at string(date-time) | Filter to events created after this time (inclusive). | ||||
?end_at string(date-time) | Filter to events created before this time (exclusive). | ||||
?event_type string | Filter to events of this type. | ||||
?actor_type string | Filter to events with an actor of this type. | ||||
?actor_gid string | Filter to events triggered by the actor with this ID. | ||||
?resource_gid string | Filter to events with this resource ID. | ||||
↓ Show Common Parameters ↓ |
Detailed descriptions
event_type: Filter to events of this type. Refer to the Supported AuditLogEvents for a full list of values.
actor_type: Filter to events with an actor of this type.
This only needs to be included if querying for actor types without an ID. If actor_gid
is included, this should be excluded.
Enumerated Values
Parameter | Value | |
actor_type | user | |
actor_type | asana | |
actor_type | asana_support | |
actor_type | anonymous | |
actor_type | external_administrator |
Responses
Status | Description | ||||
200 AuditLogEvent | AuditLogEvents were successfully retrieved. | ||||
↓ Show Common Responses ↓ |
Batch API
POST /batch
There are many cases where you want to accomplish a variety of work in the Asana API but want to minimize the number of HTTP requests you make. For example:
- Modern browsers limit the number of requests that a single web page can make at once.
- Mobile apps will use more battery life to keep the cellular radio on when making a series of requests.
- There is an overhead cost to developing software that can make multiple requests in parallel.
- Some cloud platforms handle parallelism poorly, or disallow it entirely.
To make development easier in these use cases, Asana provides a batch API that enables developers to perform multiple “actions” by making only a single HTTP request.
Making a Batch Request
To make a batch request, send a POST
request to /batch
. Like other POST
endpoints, the body should contain a data
envelope. Inside this envelope should be a single actions
field, containing a list of “action” objects. Each action represents a standard request to an existing endpoint in the Asana API.
The maximum number of actions allowed in a single batch request is 10. Making a batch request with no actions in it will result in a 400 Bad Request
.
When the batch API receives the list of actions to execute, it will dispatch those actions to the already-implemented endpoints specified by the relative_path
and method
for each action. This happens in parallel, so all actions in the request will be processed simultaneously. There is no guarantee of the execution order for these actions, nor is there a way to use the output of one action as the input of another action (such as creating a task and then commenting on it).
The response to the batch request will contain (within the data
envelope) a list of result objects, one for each action. The results are guaranteed to be in the same order as the actions in the request, e.g., the first result in the response corresponds to the first action in the request.
The batch API will always attempt to return a 200 Success
response with individual result objects for each individual action in the request. Only in certain cases (such as missing authorization or malformed JSON in the body) will the entire request fail with another status code. Even if every individual action in the request fails, the batch API will still return a 200 Success
response, and each result object in the response will contain the errors encountered with each action.
Rate Limiting
The batch API fully respects all of our rate limiting. This means that a batch request counts against both the standard rate limiter and the concurrent request limiter as though you had made a separate HTTP request for every individual action. For example, a batch request with five actions counts as five separate requests in the standard rate limiter, and counts as five concurrent requests in the concurrent request limiter. The batch request itself incurs no cost.
If any of the actions in a batch request would exceed any of the enforced limits, the entire request will fail with a 429 Too Many Requests
error. This is to prevent the unpredictability of which actions might succeed if not all of them could succeed.
Restrictions
Not every endpoint can be accessed through the batch API. Specifically, the following actions cannot be taken and will result in a 400 Bad Request
for that action:
- Uploading attachments
- Creating, getting, or deleting organization exports
- Any SCIM operations
- Nested calls to the batch API
Submit parallel requests
Code samples
curl -X POST https://app.asana.com/api/1.0/batch \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}' \
-d '{"data": {"field":"value","field":"value"} }'
Body parameter
{
"data": {
"actions": [
{
"data": {
"assignee": "me",
"workspace": "1337"
},
"method": "get",
"options": {
"fields": [
"name",
"notes",
"completed"
],
"limit": 3
},
"relative_path": "/tasks/123"
}
]
}
}
200 Response
{
"data": [
{
"body": {
"data": {
"completed": false,
"gid": "1967",
"name": "Hello, world!",
"notes": "How are you today?"
}
},
"headers": {
"location": "/tasks/1234"
},
"status_code": 200
}
]
}
See Input/Output Options to include more fields in your response.
POST /batch
Make multiple requests in parallel to Asana's API.
Parameters
Name | Description | ||||
body object required | The requests to batch together via the Batch API. | ||||
↓ Show Common Parameters ↓ |
Enumerated Values
Parameter | Value | |
method | get | |
method | post | |
method | put | |
method | delete | |
method | patch | |
method | head |
Responses
Status | Description | ||||
200 Batch | Successfully completed the requested batch API operations. | ||||
↓ Show Common Responses ↓ |
Custom Fields
POST /custom_fields
GET /custom_fields/{custom_field_gid}
PUT /custom_fields/{custom_field_gid}
DELETE /custom_fields/{custom_field_gid}
GET /workspaces/{workspace_gid}/custom_fields
POST /custom_fields/{custom_field_gid}/enum_options
POST /custom_fields/{custom_field_gid}/enum_options/insert
PUT /enum_options/{enum_option_gid}
In the Asana application, Tasks, Projects, and Portfolios can hold user-specified Custom Fields which provide extra information; for example, a priority value or a number representing the time required to complete a Task. This lets a user define the type of information that each Item within a Project or Portfolio can contain in addition to the built-in fields that Asana provides.
Note: Custom Fields are a premium feature. Integrations which work with Custom Fields need to handle an assortment of use cases for free and premium users in context of free and premium organizations. For a detailed examination of to what data users will have access in different circumstances, read the section below on access control.
display_value
is a read-only field that will always be a string. For apps that use custom fields, this is a great way to safely display/export the value of a custom field, regardless of its type. We suggest apps use this field in order to future-proof for changes to Custom Fields.
Characteristics of Custom Fields
- There is metadata that defines the Custom Field. This metadata can be shared across an entire workspace, or be specific to a Project or Portfolio.
- Creating a Custom Field Setting on a Project or Portfolio means each direct child will have the custom field. This is conceptually akin to adding columns in a database or a spreadsheet: every Task (row) in the Project (table) can contain information for that field, including "blank" values, i.e.
null
data. For Portfolio custom fields, every Project (row) in the Portfolio (table) will contain information for the custom field. - Custom Field Settings only go one child deep. Meaning a custom field setting on a portfolio will give each project the custom field, but not each task within those projects.
- Tasks have Custom Field values assigned to them.
Types of Custom Fields
Integrations using Custom Fields need to be aware of the four basic types that a Custom Field can adopt. These types are:
text
- an arbitrary, relatively short string of textnumber
- a number with a defined level of precisionenum
- a selection of a single option from a defined list of options (i.e., mutually exclusive selections)multi_enum
- a selection of one or more options from a defined list of options (i.e., mutually inclusive selections)
Example use-case
Consider an organization that has defined a Custom Field for "Priority". This field is of enum
type and can have user-defined values of Low
, Medium
, or High
. This is the field metadata, and it is visible within, and shared across, the entire organization.
A Project is then created in the organization, called "Bugs", and the "Priority" Custom Field is associated with that Project. This will allow all Tasks within the "Bugs" Project to have an associated "Priority".
A new Task is created within "Bugs". This Task, then, has a field named "Priority" which can take on the Custom Field value of one of [null]
, Low
, Medium
, and High
.
Custom Fields in the API
These Custom Fields are accessible via the API through a number of endpoints at the top level (e.g. /custom_fields
and /custom_field_settings
) and through calls on Workspaces, Portfolios, Projects, and Tasks resources. The API also provides a way to fetch both the metadata and data which define each particular Custom Field, so that a client application may render proper UI to display or edit the values.
Text fields are currently limited to 1024 characters. On Tasks, their Custom Field value will have a text_value
property to represent this field.
Number fields can have an arbitrary precision
associated with them; for example, a precision of 2
would round its value to the second (hundredths) place, i.e. 1.2345 would round to 1.23. On Tasks, the Custom Field value will have a number_value
property to represent this field.
Enum fields
Enum fields represent a selection from a list of options. On the metadata, they will contain all of the options in an array. Each option has 4 properties:
gid
- the gid of this enum option. Note that this is the gid of the individual option - the Custom Field itself has a separategid
.name
- the name of the option (e.g., "Choice #1")enabled
- whether this field is enabled. Disabled fields are not available to choose from when disabled, and are visually hidden in the Asana application, but they remain in the metadata for Custom Field values which were set to the option before the option was disabled.color
- a color associated with this choice.
On the Task's Custom Field value, the enum will have an enum_value
property which will be the same as one of the choices from the list defined in the Custom Field metadata.
Querying an organization for its Custom Fields
For Custom Fields shared across the workspace or organization, the Workspace can be queried for its list of defined Custom Fields. Like other collection queries, the fields will be returned as a compact record; slightly different from most other compact records is the fact that the compact record for Custom Fields includes type
as well as gid
and name
.
Accessing Custom Field definitions
The Custom Fields reference describes how the metadata which defines a Custom Field is accessed. A GET request with a gid
can be issued on the /custom_fields
endpoint to fetch the full definition of a single Custom Field given its gid
from (for instance) listing all Custom Fields on a Workspace, or getting the gid
from a Custom Field Settings object or a Task.
Associating Custom Fields with a Project or Portfolio
A mapping between a Custom Field and a Project or Portfolio is handled with a Custom Field Settings object. This object contains a reference for each of the Custom Field and the Project or Porfolio, as well as additional information about the status of that particular Custom Field. For instance, is_important
, which defines whether or not the custom field will appear in the list/grid on the Asana application.
Accessing Custom Field values on Tasks or Projects
The Tasks reference has information on how Custom Fields look on Tasks. Custom Fields will return as an array on the property custom_fields
, and each entry will contain, side-by-side, the compact representation of the Custom Field metadata and a {typename}_value
property that stores the value set for the Custom Field.
Of particular note is that the top-level gid
of each entry in the custom_fields
array is the gid
of the Custom Field metadata, as it is the compact representation of this metadata. This can be used to refer to the full metadata by making a request to the /custom_fields/{custom_fields_id}
endpoint as described above.
Custom Fields can be set just as in the Asana-defined fields on a task via POST or PUT requests. You can see an example on the update a task endpoint.
Custom Fields on projects follow this same pattern.
Warning: Program defensively with regards to Custom Field definitions
Asana application users have the ability to change the definitions of Custom Field metadata. This means that as you write scripts or applications to work with them, it's possible for the definitions to change at any time, which may cause an application using them to break or malfunction if it makes assumptions about the metadata for a particular Custom Field. When using Custom Fields, it is a good idea to program defensively, meaning you your application should double-check that the Custom Field metadata is what it expects.
Storing the state of the Custom Field metadata for too long if you dynamically create a model for it can cause your model to become unsynchronized with the model stored in Asana. If you encounter (for example) an enum
value on a Task that does not match any option in your metadata model, your metadata model has become out of date with the Custom Field metadata.
Note: We are currently studying proposals for future implementations to more elegantly handle the modification of Custom Field metadata for application integrations.
Enabled and Disabled Values
When information that is contained in a Custom Field value loses a logical association with its metadata definition, the value becomes disabled. This can happen in a couple of simple ways, for example, if you remove the Custom Field metadata from a Project, or move a Task with a Custom Field to a different Project which does not have the Custom Field metadata associated with it. The value remains on the Task, and the Custom Field metadata can still be found and examined, but as the context in which the Custom Field makes sense is gone, the Custom Field cannot change its value; it can only be cleared.
Note: Tasks that are associated with multiple Projects do not become disabled, so long as at least one of the Projects is still associated with the Custom Field metadata. In other words, Tasks with multiple Projects will retain logically associated to the set of Custom Field metadata represented by all of their Projects.
Moving the Task back under a Project with that Custom Field applied to it or applying the Custom Field metadata to the current Project will return the Custom Field value to an enabled state. In this scenario, the Custom Field will be re-enabled and editable again.
In the Asana application, disabled fields are grayed out and not allowed to change, other than to be discarded. In the API, we return a property enabled: false
to inform the external application that the value has been disabled.
Note that the API enforces the same operations on disabled Custom Field values as hold in the Asana application: they may not have their values changed, since the lack of context for the values of a custom field in general doesn't provide enough information to know what new values should be. Setting the Custom Field value to null
will clear and remove the Custom Field value from the Task.
Custom Field access control
Custom Fields are a complex feature of the Asana platform, and their access in the Asana application and in the API vary based on the status of the user and project. When building your application, it's best to be defensive and not assume the given user will have read or write access to a custom field, and fail gracefully when this occurs.
Create a custom field
Code samples
curl -X POST https://app.asana.com/api/1.0/custom_fields \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}' \
-d '{"data": {"field":"value","field":"value"} }'
Body parameter
{
"data": {
"currency_code": "EUR",
"custom_label": "gold pieces",
"custom_label_position": "suffix",
"description": "Development team priority",
"enabled": true,
"enum_options": [
{
"color": "blue",
"enabled": true,
"name": "Low"
}
],
"enum_value": {
"color": "blue",
"enabled": true,
"name": "Low"
},
"format": "custom",
"has_notifications_enabled": true,
"multi_enum_values": [
{
"color": "blue",
"enabled": true,
"name": "Low"
}
],
"name": "Status",
"number_value": 5.2,
"precision": 2,
"resource_subtype": "text",
"text_value": "Some Value",
"workspace": "1331"
}
}
201 Response
{
"data": {
"gid": "12345",
"resource_type": "custom_field",
"created_by": {
"gid": "12345",
"resource_type": "user",
"name": "Greg Sanchez"
},
"currency_code": "EUR",
"custom_label": "gold pieces",
"custom_label_position": "suffix",
"description": "Development team priority",
"display_value": "blue",
"enabled": true,
"enum_options": [
{
"gid": "12345",
"resource_type": "enum_option",
"color": "blue",
"enabled": true,
"name": "Low"
}
],
"enum_value": {
"gid": "12345",
"resource_type": "enum_option",
"color": "blue",
"enabled": true,
"name": "Low"
},
"format": "custom",
"has_notifications_enabled": true,
"is_global_to_workspace": true,
"multi_enum_values": [
{
"gid": "12345",
"resource_type": "enum_option",
"color": "blue",
"enabled": true,
"name": "Low"
}
],
"name": "Status",
"number_value": 5.2,
"precision": 2,
"resource_subtype": "text",
"text_value": "Some Value",
"type": "text"
}
}
See Input/Output Options to include more fields in your response.
POST /custom_fields
Creates a new custom field in a workspace. Every custom field is required to be created in a specific workspace, and this workspace cannot be changed once set.
A custom field’s name must be unique within a workspace and not conflict
with names of existing task properties such as Due Date
or Assignee
.
A custom field’s type must be one of text
, enum
, multi_enum
or number
.
Returns the full record of the newly created custom field.
Parameters
Name | Description | ||||
body object | The custom field object to create. | ||||
↓ Show Common Parameters ↓ |
Detailed descriptions
precision: Only relevant for custom fields of type ‘Number’. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive. For percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%. The identifier format will always have a precision of 0.
Enumerated Values
Parameter | Value | |
custom_label_position | prefix | |
custom_label_position | suffix | |
format | currency | |
format | identifier | |
format | percentage | |
format | custom | |
format | none | |
resource_subtype | text | |
resource_subtype | enum | |
resource_subtype | multi_enum | |
resource_subtype | number |
Responses
Status | Description | ||||
201 CustomField | Custom field successfully created. | ||||
↓ Show Common Responses ↓ |
Get a custom field
Code samples
curl -X GET https://app.asana.com/api/1.0/custom_fields/{custom_field_gid} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
200 Response
{
"data": {
"gid": "12345",
"resource_type": "custom_field",
"created_by": {
"gid": "12345",
"resource_type": "user",
"name": "Greg Sanchez"
},
"currency_code": "EUR",
"custom_label": "gold pieces",
"custom_label_position": "suffix",
"description": "Development team priority",
"display_value": "blue",
"enabled": true,
"enum_options": [
{
"gid": "12345",
"resource_type": "enum_option",
"color": "blue",
"enabled": true,
"name": "Low"
}
],
"enum_value": {
"gid": "12345",
"resource_type": "enum_option",
"color": "blue",
"enabled": true,
"name": "Low"
},
"format": "custom",
"has_notifications_enabled": true,
"is_global_to_workspace": true,
"multi_enum_values": [
{
"gid": "12345",
"resource_type": "enum_option",
"color": "blue",
"enabled": true,
"name": "Low"
}
],
"name": "Status",
"number_value": 5.2,
"precision": 2,
"resource_subtype": "text",
"text_value": "Some Value",
"type": "text"
}
}
See Input/Output Options to include more fields in your response.
GET /custom_fields/{custom_field_gid}
Get the complete definition of a custom field’s metadata.
Since custom fields can be defined for one of a number of types, and these types have different data and behaviors, there are fields that are relevant to a particular type. For instance, as noted above, enum_options is only relevant for the enum type and defines the set of choices that the enum could represent. The examples below show some of these type-specific custom field definitions.
Parameters
Name | Description | ||||
/custom_field_gid string required | Globally unique identifier for the custom field. | ||||
↓ Show Common Parameters ↓ |
Responses
Status | Description | ||||
200 CustomField | Successfully retrieved the complete definition of a custom field’s metadata. | ||||
↓ Show Common Responses ↓ |
Update a custom field
Code samples
curl -X PUT https://app.asana.com/api/1.0/custom_fields/{custom_field_gid} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}' \
-d '{"data": {"field":"value","field":"value"} }'
Body parameter
{
"data": {
"currency_code": "EUR",
"custom_label": "gold pieces",
"custom_label_position": "suffix",
"description": "Development team priority",
"enabled": true,
"enum_options": [
{
"color": "blue",
"enabled": true,
"name": "Low"
}
],
"enum_value": {
"color": "blue",
"enabled": true,
"name": "Low"
},
"format": "custom",
"has_notifications_enabled": true,
"multi_enum_values": [
{
"color": "blue",
"enabled": true,
"name": "Low"
}
],
"name": "Status",
"number_value": 5.2,
"precision": 2,
"resource_subtype": "text",
"text_value": "Some Value",
"workspace": "1331"
}
}
200 Response
{
"data": {
"gid": "12345",
"resource_type": "custom_field",
"created_by": {
"gid": "12345",
"resource_type": "user",
"name": "Greg Sanchez"
},
"currency_code": "EUR",
"custom_label": "gold pieces",
"custom_label_position": "suffix",
"description": "Development team priority",
"display_value": "blue",
"enabled": true,
"enum_options": [
{
"gid": "12345",
"resource_type": "enum_option",
"color": "blue",
"enabled": true,
"name": "Low"
}
],
"enum_value": {
"gid": "12345",
"resource_type": "enum_option",
"color": "blue",
"enabled": true,
"name": "Low"
},
"format": "custom",
"has_notifications_enabled": true,
"is_global_to_workspace": true,
"multi_enum_values": [
{
"gid": "12345",
"resource_type": "enum_option",
"color": "blue",
"enabled": true,
"name": "Low"
}
],
"name": "Status",
"number_value": 5.2,
"precision": 2,
"resource_subtype": "text",
"text_value": "Some Value",
"type": "text"
}
}
See Input/Output Options to include more fields in your response.
PUT /custom_fields/{custom_field_gid}
A specific, existing custom field can be updated by making a PUT request on the URL for that custom field. Only the fields provided in the data
block will be updated; any unspecified fields will remain unchanged
When using this method, it is best to specify only those fields you wish to change, or else you may overwrite changes made by another user since you last retrieved the custom field.
A custom field’s type
cannot be updated.
An enum custom field’s enum_options
cannot be updated with this endpoint. Instead see “Work With Enum Options” for information on how to update enum_options
.
Locked custom fields can only be updated by the user who locked the field.
Returns the complete updated custom field record.
Parameters
Name | Description | ||||
/custom_field_gid string required | Globally unique identifier for the custom field. | ||||
body object | The custom field object with all updated properties. | ||||
↓ Show Common Parameters ↓ |
Detailed descriptions
precision: Only relevant for custom fields of type ‘Number’. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive. For percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%. The identifier format will always have a precision of 0.
Enumerated Values
Parameter | Value | |
custom_label_position | prefix | |
custom_label_position | suffix | |
format | currency | |
format | identifier | |
format | percentage | |
format | custom | |
format | none | |
resource_subtype | text | |
resource_subtype | enum | |
resource_subtype | multi_enum | |
resource_subtype | number |
Responses
Status | Description | ||||
200 CustomField | The custom field was successfully updated. | ||||
↓ Show Common Responses ↓ |
Delete a custom field
Code samples
curl -X DELETE https://app.asana.com/api/1.0/custom_fields/{custom_field_gid} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
200 Response
{
"data": {}
}
See Input/Output Options to include more fields in your response.
DELETE /custom_fields/{custom_field_gid}
A specific, existing custom field can be deleted by making a DELETE request on the URL for that custom field. Locked custom fields can only be deleted by the user who locked the field. Returns an empty data record.
Parameters
Name | Description | ||||
/custom_field_gid string required | Globally unique identifier for the custom field. | ||||
↓ Show Common Parameters ↓ |
Responses
Status | Description | ||||
200 Inline | The custom field was successfully deleted. | ||||
↓ Show Common Responses ↓ |
Response Schema
Status Code 200
Get a workspace's custom fields
Code samples
curl -X GET https://app.asana.com/api/1.0/workspaces/{workspace_gid}/custom_fields \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
200 Response
{
"data": [
{
"gid": "12345",
"resource_type": "custom_field",
"created_by": {
"gid": "12345",
"resource_type": "user",
"name": "Greg Sanchez"
},
"currency_code": "EUR",
"custom_label": "gold pieces",
"custom_label_position": "suffix",
"description": "Development team priority",
"display_value": "blue",
"enabled": true,
"enum_options": [
{
"gid": "12345",
"resource_type": "enum_option",
"color": "blue",
"enabled": true,
"name": "Low"
}
],
"enum_value": {
"gid": "12345",
"resource_type": "enum_option",
"color": "blue",
"enabled": true,
"name": "Low"
},
"format": "custom",
"has_notifications_enabled": true,
"is_global_to_workspace": true,
"multi_enum_values": [
{
"gid": "12345",
"resource_type": "enum_option",
"color": "blue",
"enabled": true,
"name": "Low"
}
],
"name": "Status",
"number_value": 5.2,
"precision": 2,
"resource_subtype": "text",
"text_value": "Some Value",
"type": "text"
}
]
}
See Input/Output Options to include more fields in your response.
GET /workspaces/{workspace_gid}/custom_fields
Returns a list of the compact representation of all of the custom fields in a workspace.
Parameters
Name | Description | ||||
/workspace_gid string required | Globally unique identifier for the workspace or organization. | ||||
↓ Show Common Parameters ↓ |
Responses
Status | Description | ||||
200 CustomField | Successfully retrieved all custom fields for the given workspace. | ||||
↓ Show Common Responses ↓ |
Create an enum option
Code samples
curl -X POST https://app.asana.com/api/1.0/custom_fields/{custom_field_gid}/enum_options \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}' \
-d '{"data": {"field":"value","field":"value"} }'
Body parameter
{
"data": {
"color": "blue",
"enabled": true,
"insert_after": "12345",
"insert_before": "12345",
"name": "Low"
}
}
201 Response
{
"data": {
"gid": "12345",
"resource_type": "enum_option",
"color": "blue",
"enabled": true,
"name": "Low"
}
}
See Input/Output Options to include more fields in your response.
POST /custom_fields/{custom_field_gid}/enum_options
Creates an enum option and adds it to this custom field’s list of enum options. A custom field can have at most 100 enum options (including disabled options). By default new enum options are inserted at the end of a custom field’s list. Locked custom fields can only have enum options added by the user who locked the field. Returns the full record of the newly created enum option.
Parameters
Name | Description | ||||
/custom_field_gid string required | Globally unique identifier for the custom field. | ||||
body object | The enum option object to create. | ||||
↓ Show Common Parameters ↓ |
Responses
Status | Description | ||||
201 EnumOption | Custom field enum option successfully created. | ||||
↓ Show Common Responses ↓ |
Reorder a custom field's enum
Code samples
curl -X POST https://app.asana.com/api/1.0/custom_fields/{custom_field_gid}/enum_options/insert \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}' \
-d '{"data": {"field":"value","field":"value"} }'
Body parameter
{
"data": {
"after_enum_option": "12345",
"before_enum_option":