Asana is a versatile work management tool that helps teams organize tasks, projects, and collaborate effectively. Integrate the Asana API into your applications to automate workflows, manage tasks, and enhance your team's productivity.
To start using the Asana API, you'll need a Personal Access Token (PAT). Here's how you can generate one:
Learn more about [Asana API Authentication](https://developers.asana.com/docs/authentication
Once you have an access token, you're ready to set up your Superblocks integration.
Once your Asana integration is created, you can start calling
Asana actions in Superblocks APIs.
Asana actions are REST requests. To learn more about REST requests in
Superblocks, see the
Building REST requests guide.
Get multiple projects
Returns the compact project records for some filtered set of projects. Use one or more of the parameters provided to filter the projects returned.
*Note: This endpoint may timeout for large domains. Try filtering by team!*Create a project
Create a new project in a workspace or team.
Every project 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.
If the workspace for your project is an organization, you must also
supply a `team` to share the project with.
Returns the full record of the newly created project.Get a project
Returns the complete project record for a single project.Update a project
A specific, existing project 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.
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 project record.Delete a project
A specific, existing project can be deleted by making a DELETE request on
the URL for that project.
Returns an empty data record.Get projects a task is in
Returns a compact representation of all of the projects the task is in.Get a team's projects
Returns the compact project records for all projects in the team.Create a project in a team
Creates a project shared with the given team.
Returns the full record of the newly created project.Get all projects in a workspace
Returns the compact project records for all projects in the workspace.
*Note: This endpoint may timeout for large domains. Prefer the `/teams/{team_gid}/projects` endpoint.*Create a project in a workspace
Creates a project in the workspace.
If the workspace for your project is an organization, you must also
supply a team to share the project with.
Returns the full record of the newly created project.Add users to a project
Adds the specified list of users as members of the project. Note that a user being added as a member may also be added as a *follower* as a result of this operation. This is because the user's default notification settings (i.e., in the "Notifcations" tab of "My Profile Settings") will override this endpoint's default behavior of setting "Tasks added" notifications to `false`.
Returns the updated project record.Remove users from a project
Removes the specified list of users from members of the project.
Returns the updated project record.Get statuses from a project
*Deprecated: new integrations should prefer the `/status_updates` route.*
Returns the compact project status update records for all updates on the project.Create a project status
*Deprecated: new integrations should prefer the `/status_updates` route.*
Creates a new status update on the project.
Returns the full record of the newly created project status update.Search tasks in a workspace
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.
#### Premium access
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:
- The workspace in which the search is being performed is a premium workspace - The user is a member of a premium team inside the workspace
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.
#### Pagination
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](https://developers.asana.com/docs/#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.
#### Eventual consistency
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.
#### Rate limits
You may receive a `429 Too Many Requests` response if you hit any of our [rate limits](https://developers.asana.com/docs/#rate-limits).
#### Custom field parameters
| 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.*Get multiple 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](/reference/searchtasksforworkspace).Create a task
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.Get a task
Returns the complete task record for a single task.Update a task
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.Delete a task
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.Duplicate a task
Creates and returns a job that will asynchronously handle the duplication.Get tasks from a project
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.Get tasks from a section
*Board view only*: Returns the compact section records for all tasks within the given section.Get tasks from a tag
Returns the compact task records for all tasks with the given tag. Tasks can have more than one tag at a time.Get subtasks from a task
Returns a compact representation of all of the subtasks of a task.Create a subtask
Creates a new subtask and adds it to the parent task. Returns the full record for the newly created subtask.Set the parent of a task
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.Get dependencies from a task
Returns the compact representations of all of the dependencies of a task.Set dependencies for a task
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*.Unlink dependencies from a task
Unlinks a set of dependencies from this task.Get dependents from a task
Returns the compact representations of all of the dependents of a task.Set dependents for a task
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*.Unlink dependents from a task
Unlinks a set of dependents from this task.Add a project to a task
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.
Returns an empty data block.Remove a project from a task
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.Add a tag to a task
Adds a tag to a task. Returns an empty data block.Remove a tag from a task
Removes a tag from a task. Returns an empty data block.Add followers to a task
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.Remove followers from a task
Removes each of the specified followers from the task if they are following. Returns the complete, updated record for the affected task.Get memberships from a team
Returns the compact team memberships for the team.Create a team
Creates a team within the current workspace.Get a team
Returns the full record for a single team.Update a team
Updates a team within the current workspace.Get teams in a workspace
Returns the compact records for all teams in the workspace visible to the authorized user.Add a user to a team
The user making this call must be a member of the team in order to add others. The user being added must exist in the same organization as the team.
Returns the complete team membership record for the newly added user.Remove a user from a team
The user making this call must be a member of the team in order to remove themselves or others.Get time tracking entries for a task
Returns time tracking entries for a given task.Create a time tracking entry
Creates a time tracking entry on a given task.
Returns the record of the newly created time tracking entry.Get users in a team
Returns the compact records for all users that are members of the team.
Results are sorted alphabetically and limited to 2000. For more results use the `/users` endpoint.Get users in a workspace or organization
Returns the compact records for all users in the specified workspace or organization.
Results are sorted alphabetically and limited to 2000. For more results use the `/users` endpoint.Get user info
Retrieve info about the currently authenticated user.Get multiple users
Returns the user records for all users in all workspaces and organizations accessible to the authenticated user. Accepts an optional workspace ID parameter.
Results are sorted by user ID.Get a user
Returns the full user record for the single user with the provided ID.Get the workspace memberships for a workspace
Returns the compact workspace membership records for the workspace.Get multiple workspaces
Returns the compact records for all workspaces visible to the authorized user.Get a workspace
Returns the full workspace record for a single workspace.Update a workspace
A specific, existing workspace can be updated by making a PUT request on the URL for that workspace. Only the fields provided in the data block will be updated; any unspecified fields will remain unchanged.
Currently the only field that can be modified for a workspace is its name.
Returns the complete, updated workspace record.Add a user to a workspace or organization
Add a user to a workspace or organization.
The user can be referenced by their globally unique user ID or their email address. Returns the full user record for the invited user.Remove a user from a workspace or organization
Remove a user from a workspace or organization.
The user making this call must be an admin in the workspace. The user can be referenced by their globally unique user ID or their email address.
Returns an empty data record.Get audit log events
Retrieve the audit log events that have been captured in your domain.
This endpoint will return a list of [AuditLogEvent](/reference/audit-log-api) objects, sorted by creation time in ascending order. Note that the Audit Log API captures events from October 8th, 2021 and later. Queries for events before this date will not return results.
There are a number of query parameters (below) that can be used to filter the set of [AuditLogEvent](/reference/audit-log-api) objects that are returned in the response. Any combination of query parameters is valid. When no filters are provided, all of the events that have been captured in your domain will match.
The list of events will always be [paginated](/docs/pagination). The default limit is 1000 events. The next set of events can be retrieved using the `offset` from the previous response. If there are no events that match the provided filters in your domain, the endpoint will return `null` for the `next_page` field. Querying again with the same filters may return new events if they were captured after the last request. Once a response includes a `next_page` with an `offset`, subsequent requests can be made with the latest `offset` to poll for new events that match the provided filters.
*Note: If the filters you provided match events in your domain and `next_page` is present in the response, we will continue to send `next_page` on subsequent requests even when there are no more events that match the filters. This was put in place so that you can implement an audit log stream that will return future events that match these filters. If you are not interested in future events that match the filters you have defined, you can rely on checking empty `data` response for the end of current events that match your filters.*
When no `offset` is provided, the response will begin with the oldest events that match the provided filters. It is important to note that [AuditLogEvent](/reference/audit-log-api) objects will be permanently deleted from our systems after 90 days. If you wish to keep a permanent record of these events, we recommend using a SIEM tool to ingest and store these logs.and 45 moreTo use this action simply add the method, path, required query parameters, and body for the desired endpoint.
