/sections/{section_gid}
A specific, existing section can be updated by making a PUT request on
the URL for that project. Only the fields provided in the data block
will be updated; any unspecified fields will remain unchanged. (note that
at this time, the only field that can be updated is the name field.)
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 task.
Returns the complete updated section record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| section_gid | path | optional | string | The globally unique identifier for the section. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
The section to create.
application/json
SectionsUpdateSectionRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ name | string | required |
| └ insert_after | string | optional |
| └ insert_before | string | optional |
Successfully updated the specified section.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
PUT /sections/{section_gid}
/sections/{section_gid}/addTask
Add a task to a specific, existing section. This will remove the task from other sections of the project.
The task will be inserted at the top of a section unless an insert_before or insert_after parameter is declared.
This does not work for separators (tasks with the resource_subtype of section).
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| section_gid | path | optional | string | The globally unique identifier for the section. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
The task and optionally the insert location.
application/json
SectionsAddTaskToSectionRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ task | string | required |
| └ insert_after | string | optional |
| └ insert_before | string | optional |
Successfully added the task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /sections/{section_gid}/addTask
/status_updates
Returns the compact status update records for all updates on the object.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| parent | query | required | string | Globally unique identifier for object to fetch statuses from. Must be a GID for a project, portfolio, or goal. |
| created_since | query | optional | string | Only return statuses that have been created since the given time. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the specified object’s status updates.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /status_updates
/status_updates
Creates a new status update on an object.
Returns the full record of the newly created status update.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
The status update to create.
application/json
StatusUpdatesCreateNewStatusUpdateRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ title | string | optional |
| └ resource_subtype | string | optional |
| └ text | string | required |
| └ html_text | string | optional |
| └ status_type | string | required |
| └ parent | string | required |
Successfully created a new status update.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /status_updates
/status_updates/{status_update_gid}
Deletes a specific, existing status update.
Returns an empty data record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| status_update_gid | path | optional | string | The status update to get. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
Successfully deleted the specified status.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
DELETE /status_updates/{status_update_gid}
/status_updates/{status_update_gid}
Returns the complete record for a single status update.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| status_update_gid | path | optional | string | The status update to get. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the specified object’s status updates.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /status_updates/{status_update_gid}
/stories/{story_gid}
Deletes a story. A user can only delete stories they have created.
Returns an empty data record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| story_gid | path | optional | string | Globally unique identifier for the story. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
Successfully deleted the specified story.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
DELETE /stories/{story_gid}
/stories/{story_gid}
Returns the full record for a single story.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| story_gid | path | optional | string | Globally unique identifier for the story. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the specified story.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /stories/{story_gid}
/stories/{story_gid}
Updates the story and returns the full record for the updated story. Only comment stories can have their text updated, and only comment stories and attachment stories can be pinned. Only one of text and html_text can be specified.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| story_gid | path | optional | string | Globally unique identifier for the story. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
The comment story to update.
application/json
StoriesUpdateFullRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ text | string | optional |
| └ html_text | string | optional |
| └ is_pinned | boolean | optional |
| └ created_at | string | optional |
| └ sticker_name | string | optional |
| └ resource_subtype | string | optional |
Successfully retrieved the specified story.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
PUT /stories/{story_gid}
/tasks/{task_gid}/stories
Returns the compact records for all stories on the task.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the specified task’s stories.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /tasks/{task_gid}/stories
/tasks/{task_gid}/stories
Adds a story to a task. This endpoint currently only allows for comment
stories to be created. The comment will be authored by the currently
authenticated user, and timestamped when the server receives the request.
Returns the full record for the new story added to the task.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
The story to create.
application/json
StoriesCreateCommentRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ text | string | optional |
| └ html_text | string | optional |
| └ is_pinned | boolean | optional |
| └ created_at | string | optional |
| └ sticker_name | string | optional |
| └ resource_subtype | string | optional |
Successfully created a new story.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks/{task_gid}/stories
/tags
Returns the compact tag records for some filtered set of tags. Use one or more of the parameters provided to filter the tags returned.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| workspace | query | optional | string | The workspace to filter tags on. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the specified set of tags.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /tags
/tags
Creates a new tag in a workspace or organization.
Every tag is required to be created in a specific workspace or
organization, and this cannot be changed once set. Note that you can use
the workspace parameter regardless of whether or not it is an
organization.
Returns the full record of the newly created tag.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
The tag to create.
application/json
TagsCreateNewTagRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ color | string | optional |
| └ notes | string | optional |
| └ followers | array | optional |
| └ workspace | string | optional |
Successfully created the newly specified tag.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tags
/tags/{tag_gid}
A specific, existing tag can be deleted by making a DELETE request on
the URL for that tag.
Returns an empty data record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| tag_gid | path | optional | string | Globally unique identifier for the tag. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
Successfully deleted the specified tag.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
DELETE /tags/{tag_gid}
/tags/{tag_gid}
Returns the complete tag record for a single tag.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| tag_gid | path | optional | string | Globally unique identifier for the tag. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the specified tag.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /tags/{tag_gid}
/tags/{tag_gid}
Updates the properties of a tag. 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 tag.
Returns the complete updated tag record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| tag_gid | path | optional | string | Globally unique identifier for the tag. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully updated the specified tag.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
PUT /tags/{tag_gid}
/tasks/{task_gid}/tags
Get a compact representation of all of the tags the task has.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the tags for the given task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /tasks/{task_gid}/tags
/workspaces/{workspace_gid}/tags
Returns the compact tag records for some filtered set of tags. Use one or more of the parameters provided to filter the tags returned.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| workspace_gid | path | optional | string | Globally unique identifier for the workspace or organization. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the specified set of tags.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /workspaces/{workspace_gid}/tags
/workspaces/{workspace_gid}/tags
Creates a new tag in a workspace or organization.
Every tag is required to be created in a specific workspace or
organization, and this cannot be changed once set. Note that you can use
the workspace parameter regardless of whether or not it is an
organization.
Returns the full record of the newly created tag.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| workspace_gid | path | optional | string | Globally unique identifier for the workspace or organization. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
The tag to create.
application/json
TagsCreateTagInWorkspaceRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ color | string | optional |
| └ notes | string | optional |
| └ followers | array | optional |
Successfully created the newly specified tag.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /workspaces/{workspace_gid}/tags
/task_templates
Returns the compact task template records for some filtered set of task templates. You must specify a project
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| project | query | optional | string | The project to filter task templates on. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved requested task templates
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /task_templates
/task_templates/{task_template_gid}
A specific, existing task template can be deleted by making a DELETE request on the URL for that task template. Returns an empty data record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_template_gid | path | optional | string | Globally unique identifier for the task template. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
Successfully deleted the specified task template.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
The request was valid, but the queried object or object mutation specified in the request is above your current premium level.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
DELETE /task_templates/{task_template_gid}
/task_templates/{task_template_gid}
Returns the complete task template record for a single task template.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_template_gid | path | optional | string | Globally unique identifier for the task template. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved requested task template
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /task_templates/{task_template_gid}
/task_templates/{task_template_gid}/instantiateTask
Creates and returns a job that will asynchronously handle the task instantiation.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_template_gid | path | optional | string | Globally unique identifier for the task template. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Describes the inputs used for instantiating a task - the task’s name.
application/json
TaskTemplatesInstantiateTaskJobRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ name | string | optional |
Successfully created the job to handle task instantiation.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /task_templates/{task_template_gid}/instantiateTask
/projects/{project_gid}/tasks
Returns the compact task records for all tasks within the given project, ordered by their priority within the project. Tasks can exist in more than one project at a time.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| completed_since | query | optional | string | Only return tasks that are either incomplete or that have been completed since this time. Accepts a date-time string or the keyword now. |
| project_gid | path | optional | string | Globally unique identifier for the project. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the requested project’s tasks.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /projects/{project_gid}/tasks
/sections/{section_gid}/tasks
Board view only: Returns the compact section records for all tasks within the given section.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| section_gid | path | optional | string | The globally unique identifier for the section. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| completed_since | query | optional | string | Only return tasks that are either incomplete or that have been completed since this time. Accepts a date-time string or the keyword now. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the section’s tasks.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /sections/{section_gid}/tasks
/tags/{tag_gid}/tasks
Returns the compact task records for all tasks with the given tag. Tasks can have more than one tag at a time.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| tag_gid | path | optional | string | Globally unique identifier for the tag. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the tasks associated with the specified tag.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /tags/{tag_gid}/tasks
/tasks
Returns the compact task records for some filtered set of tasks. Use one or more of the parameters provided to filter the tasks returned. You must specify a project or tag if you do not specify assignee and workspace.
For more complex task retrieval, use workspaces/{workspace_gid}/tasks/search.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| assignee | query | optional | string | The assignee to filter tasks on. If searching for unassigned tasks, assignee.any = null can be specified. |
| project | query | optional | string | The project to filter tasks on. |
| section | query | optional | string | The section to filter tasks on. |
| workspace | query | optional | string | The workspace to filter tasks on. |
| completed_since | query | optional | string | Only return tasks that are either incomplete or that have been completed since this time. |
| modified_since | query | optional | string | Only return tasks that have been modified since the given time. Note: A task is considered “modified” if any of its properties |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved requested tasks.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /tasks
/tasks
Creating a new task is as easy as POSTing to the /tasks endpoint with a
data block containing the fields you’d like to set on the task. Any
unspecified fields will take on default values.
Every task is required to be created in a specific workspace, and this
workspace cannot be changed once set. The workspace need not be set
explicitly if you specify projects or a parent task instead.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
The task to create.
application/json
TasksCreateNewTaskRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ created_by | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ resource_subtype | string | optional |
| └ liked | boolean | optional |
| └ likes | array | optional |
| └ gid | string | optional |
| └ user | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ notes | string | optional |
| └ due_at | string | optional |
| └ due_on | string | optional |
| └ hearts | array | optional |
| └ gid | string | optional |
| └ user | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ hearted | boolean | optional |
| └ external | object | optional |
| └ gid | string | optional |
| └ data | string | optional |
| └ start_at | string | optional |
| └ start_on | string | optional |
| └ completed | boolean | optional |
| └ num_likes | integer | optional |
| └ created_at | string | optional |
| └ dependents | array | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ html_notes | string | optional |
| └ …19 more | object | optional |
Successfully created a new task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks
/tasks/{task_gid}
A specific, existing task can be deleted by making a DELETE request on
the URL for that task. Deleted tasks go into the “trash” of the user
making the delete request. Tasks can be recovered from the trash within a
period of 30 days; afterward they are completely removed from the system.
Returns an empty data record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
Successfully deleted the specified task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
DELETE /tasks/{task_gid}
/tasks/{task_gid}
Returns the complete task record for a single task.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the specified task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /tasks/{task_gid}
/tasks/{task_gid}
A specific, existing task can be updated by making a PUT request on the
URL for that task. 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 task.
Returns the complete updated task record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
The task to update.
application/json
TasksUpdateTaskRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ created_by | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ resource_subtype | string | optional |
| └ liked | boolean | optional |
| └ likes | array | optional |
| └ gid | string | optional |
| └ user | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ notes | string | optional |
| └ due_at | string | optional |
| └ due_on | string | optional |
| └ hearts | array | optional |
| └ gid | string | optional |
| └ user | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ hearted | boolean | optional |
| └ external | object | optional |
| └ gid | string | optional |
| └ data | string | optional |
| └ start_at | string | optional |
| └ start_on | string | optional |
| └ completed | boolean | optional |
| └ num_likes | integer | optional |
| └ created_at | string | optional |
| └ dependents | array | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ html_notes | string | optional |
| └ …19 more | object | optional |
Successfully updated the specified task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
PUT /tasks/{task_gid}
/tasks/{task_gid}/addDependencies
Marks a set of tasks as dependencies of this task, if they are not already dependencies. A task can have at most 30 dependents and dependencies combined.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
The list of tasks to set as dependencies.
application/json
TasksSetDependenciesForTaskRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ dependencies | array | optional |
Successfully set the specified dependencies on the task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
The request was valid, but the queried object or object mutation specified in the request is above your current premium level.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks/{task_gid}/addDependencies
/tasks/{task_gid}/addDependents
Marks a set of tasks as dependents of this task, if they are not already dependents. A task can have at most 30 dependents and dependencies combined.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
The list of tasks to add as dependents.
application/json
TasksSetTaskDependentsRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ dependents | array | optional |
Successfully set the specified dependents on the given task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
The request was valid, but the queried object or object mutation specified in the request is above your current premium level.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks/{task_gid}/addDependents
/tasks/{task_gid}/addFollowers
Adds followers to a task. Returns an empty data block.
Each task can be associated with zero or more followers in the system.
Requests to add/remove followers, if successful, will return the complete updated task record, described above.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
The followers to add to the task.
application/json
TasksAddFollowersToTaskRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ followers | array | required |
Successfully added the specified followers to the task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks/{task_gid}/addFollowers
/tasks/{task_gid}/addProject
Adds the task to the specified project, in the optional location
specified. If no location arguments are given, the task will be added to
the end of the project.
addProject can also be used to reorder a task within a project or
section that already contains it.
At most one of insert_before, insert_after, or section should be
specified. Inserting into a section in an non-order-dependent way can be
done by specifying section, otherwise, to insert within a section in a
particular place, specify insert_before or insert_after and a task
within the section to anchor the position of this task.
A task can have at most 20 projects multi-homed to it.
Returns an empty data block.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
The project to add the task to.
application/json
TasksAddProjectToTaskRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ project | string | required |
| └ section | string | optional |
| └ insert_after | string | optional |
| └ insert_before | string | optional |
Successfully added the specified project to the task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks/{task_gid}/addProject
/tasks/{task_gid}/addTag
Adds a tag to a task. Returns an empty data block.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
The tag to add to the task.
application/json
TasksAddTagToTaskRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ tag | string | required |
Successfully added the specified tag to the task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks/{task_gid}/addTag
/tasks/{task_gid}/dependencies
Returns the compact representations of all of the dependencies of a task.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the specified task’s dependencies.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
The request was valid, but the queried object or object mutation specified in the request is above your current premium level.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /tasks/{task_gid}/dependencies
/tasks/{task_gid}/dependents
Returns the compact representations of all of the dependents of a task.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the specified dependents of the task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
The request was valid, but the queried object or object mutation specified in the request is above your current premium level.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /tasks/{task_gid}/dependents
/tasks/{task_gid}/duplicate
Creates and returns a job that will asynchronously handle the duplication.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Describes the duplicate’s name and the fields that will be duplicated.
application/json
TasksDuplicateTaskJobRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ name | string | optional |
| └ include | string | optional |
Successfully created the job to handle duplication.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks/{task_gid}/duplicate
/tasks/{task_gid}/removeDependencies
Unlinks a set of dependencies from this task.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
The list of tasks to unlink as dependencies.
application/json
TasksUnlinkDependenciesFromTaskRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ dependencies | array | optional |
Successfully unlinked the dependencies from the specified task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
The request was valid, but the queried object or object mutation specified in the request is above your current premium level.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks/{task_gid}/removeDependencies
/tasks/{task_gid}/removeDependents
Unlinks a set of dependents from this task.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
The list of tasks to remove as dependents.
application/json
TasksUnlinkDependentsRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ dependents | array | optional |
Successfully unlinked the specified tasks as dependents.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
The request was valid, but the queried object or object mutation specified in the request is above your current premium level.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks/{task_gid}/removeDependents
/tasks/{task_gid}/removeFollowers
Removes each of the specified followers from the task if they are following. Returns the complete, updated record for the affected task.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
The followers to remove from the task.
application/json
TasksRemoveFollowersFromTaskRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ followers | array | required |
Successfully removed the specified followers from the task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks/{task_gid}/removeFollowers
/tasks/{task_gid}/removeProject
Removes the task from the specified project. The task will still exist in
the system, but it will not be in the project anymore.
Returns an empty data block.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
The project to remove the task from.
application/json
TasksRemoveProjectFromTaskRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ project | string | required |
Successfully removed the specified project from the task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks/{task_gid}/removeProject
/tasks/{task_gid}/removeTag
Removes a tag from a task. Returns an empty data block.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
The tag to remove from the task.
application/json
TasksRemoveTagFromTaskRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ tag | string | required |
Successfully removed the specified tag from the task.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks/{task_gid}/removeTag
/tasks/{task_gid}/setParent
parent, or no parent task at all. Returns an empty data block. When using insert_before and insert_after, at most one of those two options can be specified, and they must already be subtasks of the parent.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
The new parent of the subtask.
application/json
TasksSetParentTaskRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ parent | string | required |
| └ insert_after | string | optional |
| └ insert_before | string | optional |
Successfully changed the parent of the specified subtask.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks/{task_gid}/setParent
/tasks/{task_gid}/subtasks
Returns a compact representation of all of the subtasks of a task.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the specified task’s subtasks.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /tasks/{task_gid}/subtasks
/tasks/{task_gid}/subtasks
Creates a new subtask and adds it to the parent task. Returns the full record for the newly created subtask.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| task_gid | path | optional | string | The task to operate on. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
The new subtask to create.
application/json
TasksCreateSubtaskRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ created_by | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ resource_subtype | string | optional |
| └ liked | boolean | optional |
| └ likes | array | optional |
| └ gid | string | optional |
| └ user | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ notes | string | optional |
| └ due_at | string | optional |
| └ due_on | string | optional |
| └ hearts | array | optional |
| └ gid | string | optional |
| └ user | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ hearted | boolean | optional |
| └ external | object | optional |
| └ gid | string | optional |
| └ data | string | optional |
| └ start_at | string | optional |
| └ start_on | string | optional |
| └ completed | boolean | optional |
| └ num_likes | integer | optional |
| └ created_at | string | optional |
| └ dependents | array | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ html_notes | string | optional |
| └ …19 more | object | optional |
Successfully created the specified subtask.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
POST /tasks/{task_gid}/subtasks
/user_task_lists/{user_task_list_gid}/tasks
Returns the compact list of tasks in a user’s My Tasks list.
Note: Access control is enforced for this endpoint as with all Asana API endpoints, meaning a user’s private tasks will be filtered out if the API-authenticated user does not have access to them.
Note: Both complete and incomplete tasks are returned by default unless they are filtered out (for example, setting completed_since=now will return only incomplete tasks, which is the default view for “My Tasks” in Asana.)
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| completed_since | query | optional | string | Only return tasks that are either incomplete or that have been completed since this time. Accepts a date-time string or the keyword now. |
| user_task_list_gid | path | optional | string | Globally unique identifier for the user task list. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the user task list’s tasks.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /user_task_lists/{user_task_list_gid}/tasks
/workspaces/{workspace_gid}/tasks/custom_id/{custom_id}
Returns a task given a custom ID shortcode.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| workspace_gid | path | optional | string | Globally unique identifier for the workspace or organization. |
| custom_id | path | optional | string | Generated custom ID for a task. |
Successfully retrieved task for given custom ID.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /workspaces/{workspace_gid}/tasks/custom_id/{custom_id}
/workspaces/{workspace_gid}/tasks/search
To mirror the functionality of the Asana web app’s advanced search feature, the Asana API has a task search endpoint that allows you to build complex filters to find and retrieve the exact data you need.
Like the Asana web product’s advance search feature, this search endpoint will only be available to premium Asana users. A user is premium if any of the following is true:
Even if a user is only a member of a premium team inside a non-premium workspace, search will allow them to find data anywhere in the workspace, not just inside the premium team. Making a search request using credentials of a non-premium user will result in a 402 Payment Required error.
Search results are not stable; repeating the same query multiple times may return the data in a different order, even if the data do not change. Because of this, the traditional pagination available elsewhere in the Asana API is not available here. However, you can paginate manually by sorting the search results by their creation time and then modifying each subsequent query to exclude data you have already seen. Page sizes are limited to a maximum of 100 items, and can be specified by the limit query parameter.
Changes in Asana (regardless of whether they’re made though the web product or the API) are forwarded to our search infrastructure to be indexed. This process can take between 10 and 60 seconds to complete under normal operation, and longer during some production incidents. Making a change to a task that would alter its presence in a particular search query will not be reflected immediately. This is also true of the advanced search feature in the web product.
You may receive a 429 Too Many Requests response if you hit any of our rate limits.
| Parameter name | Custom field type | Accepted type |
|—|—|—|
| custom_fields.{gid}.is_set | All | Boolean |
| custom_fields.{gid}.value | Text | String |
| custom_fields.{gid}.value | Number | Number |
| custom_fields.{gid}.value | Enum | Enum option ID |
| custom_fields.{gid}.starts_with | Text only | String |
| custom_fields.{gid}.ends_with | Text only | String |
| custom_fields.{gid}.contains | Text only | String |
| custom_fields.{gid}.less_than | Number only | Number |
| custom_fields.{gid}.greater_than | Number only | Number |
For example, if the gid of the custom field is 12345, these query parameter to find tasks where it is set would be custom_fields.12345.is_set=true. To match an exact value for an enum custom field, use the gid of the desired enum option and not the name of the enum option: custom_fields.12345.value=67890.
Not Supported: searching for multiple exact matches of a custom field, searching for multi-enum custom field
Note: If you specify projects.any and sections.any, you will receive tasks for the project and tasks for the section. If you’re looking for only tasks in a section, omit the projects.any from the request.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| workspace_gid | path | optional | string | Globally unique identifier for the workspace or organization. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| text | query | optional | string | Performs full-text search on both task name and description |
| resource_subtype | query | optional | string | Filters results by the task’s resource_subtype |
| assignee.any | query | optional | string | Comma-separated list of user identifiers |
| assignee.not | query | optional | string | Comma-separated list of user identifiers |
| portfolios.any | query | optional | string | Comma-separated list of portfolio IDs |
| projects.any | query | optional | string | Comma-separated list of project IDs |
| projects.not | query | optional | string | Comma-separated list of project IDs |
| projects.all | query | optional | string | Comma-separated list of project IDs |
| sections.any | query | optional | string | Comma-separated list of section or column IDs |
| sections.not | query | optional | string | Comma-separated list of section or column IDs |
| sections.all | query | optional | string | Comma-separated list of section or column IDs |
| tags.any | query | optional | string | Comma-separated list of tag IDs |
| tags.not | query | optional | string | Comma-separated list of tag IDs |
| tags.all | query | optional | string | Comma-separated list of tag IDs |
| teams.any | query | optional | string | Comma-separated list of team IDs |
| followers.not | query | optional | string | Comma-separated list of user identifiers |
| created_by.any | query | optional | string | Comma-separated list of user identifiers |
| created_by.not | query | optional | string | Comma-separated list of user identifiers |
| assigned_by.any | query | optional | string | Comma-separated list of user identifiers |
| assigned_by.not | query | optional | string | Comma-separated list of user identifiers |
| liked_by.not | query | optional | string | Comma-separated list of user identifiers |
| commented_on_by.not | query | optional | string | Comma-separated list of user identifiers |
| due_on.before | query | optional | string | ISO 8601 date string |
| due_on.after | query | optional | string | ISO 8601 date string |
| due_on | query | optional | string | ISO 8601 date string or |
| due_at.before | query | optional | string | ISO 8601 datetime string |
| due_at.after | query | optional | string | ISO 8601 datetime string |
| start_on.before | query | optional | string | ISO 8601 date string |
| start_on.after | query | optional | string | ISO 8601 date string |
| start_on | query | optional | string | ISO 8601 date string or |
| created_on.before | query | optional | string | ISO 8601 date string |
| created_on.after | query | optional | string | ISO 8601 date string |
| created_on | query | optional | string | ISO 8601 date string or |
| created_at.before | query | optional | string | ISO 8601 datetime string |
| created_at.after | query | optional | string | ISO 8601 datetime string |
| completed_on.before | query | optional | string | ISO 8601 date string |
| completed_on.after | query | optional | string | ISO 8601 date string |
| completed_on | query | optional | string | ISO 8601 date string or |
| completed_at.before | query | optional | string | ISO 8601 datetime string |
| completed_at.after | query | optional | string | ISO 8601 datetime string |
| modified_on.before | query | optional | string | ISO 8601 date string |
| modified_on.after | query | optional | string | ISO 8601 date string |
| modified_on | query | optional | string | ISO 8601 date string or |
| modified_at.before | query | optional | string | ISO 8601 datetime string |
| modified_at.after | query | optional | string | ISO 8601 datetime string |
| is_blocking | query | optional | boolean | Filter to incomplete tasks with dependents |
| is_blocked | query | optional | boolean | Filter to tasks with incomplete dependencies |
| has_attachment | query | optional | boolean | Filter to tasks with attachments |
| completed | query | optional | boolean | Filter to completed tasks |
| is_subtask | query | optional | boolean | Filter to subtasks |
| sort_by | query | optional | string | One of |
| sort_ascending | query | optional | boolean | Default |
| opt_fields | query | optional | array | This endpoint returns a compact resource, which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. |
Successfully retrieved the section’s tasks.
This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
A valid authentication token was not provided with the request, so the API could not associate a user with the request.
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.
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.
There was a problem on Asana’s end. In the event of a server error the response body should contain an error phrase. These phrases can be used by Asana support to quickly look up the incident that caused the server error. Some errors are due to server load, and will not supply an error phrase.
GET /workspaces/{workspace_gid}/tasks/search