The time at which this resource was created.

An array of strings identifying users. These can either be the string "me", an email, or the gid of a user.

A generic Asana Resource, containing a globally unique identifier.

Globally unique identifier of the resource, as a string.

Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.

Free-form textual information associated with the tag (i.e. its description).

A url that points directly to the object within Asana.

Projects

This value represents the sum of all the Time Tracking entries in the Actual Time field on a given Task. It is represented as a nullable long value.

*Conditional* Reflects the approval status of this task. This field is kept in sync with `completed`, meaning `pending` translates to false while `approved`, `rejected`, and `changes_requested` translate to true. If you set completed to true, this field will be set to `approved`.

The name of the section (i.e. the text displayed as the section header).

*Deprecated* Scheduling status of this task for the user it is assigned to. This field can only be set if the assignee is non-null. Setting this field to "inbox" or "upcoming" inserts it at the top of the section, while the other options will insert at the bottom.

True if the task is currently marked complete, false if not.

The time at which this task was completed, or null if the task is incomplete.

[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that this task depends on. The objects contain only the gid of the dependency.

[Opt In](/docs/inputoutput-options). Array of resources referencing tasks that depend on this task. The objects contain only the ID of the dependent.

The UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with `due_on`.

The localized date on which this task is due, or null if the task has no due date. This takes a date with `YYYY-MM-DD` format and should not be used together with `due_at`.

*OAuth Required*. *Conditional*. This field is returned only if external values are set or included by using [Opt In] (/docs/inputoutput-options).
The external field allows you to store app-specific metadata on tasks, including a gid that can be used to retrieve tasks and a data blob that can store app-specific character strings. Note that you will need to authenticate with Oauth to access or modify this data. Once an external gid is set, you can use the notation `external:custom_gid` to reference your object anywhere in the API where you may use the original object gid. See the page on Custom External Data for more details.

*Create-Only* An array of strings identifying users. These can either be the string "me", an email, or the gid of a user. In order to change followers on an existing task use `addFollowers` and `removeFollowers`.

*Deprecated - please use liked instead* True if the task is hearted by the authorized user, false if not.

*Deprecated - please use likes instead* Array of likes for users who have hearted this task.

[Opt In](/docs/inputoutput-options). The notes of the text with formatting as HTML.

[Opt In](/docs/inputoutput-options). In some contexts tasks can be rendered as a visual separator; for instance, subtasks can appear similar to [sections](/reference/sections) without being true `section` objects. If a `task` object is rendered this way in any context it will have the property `is_rendered_as_separator` set to `true`.

True if the task is liked by the authorized user, false if not.

Array of likes for users who have liked this task.

*Create-only*. Array of projects this task is associated with and the section it is in. At task creation time, this array can be used to add the task to specific sections. After task creation, these associations can be modified using the `addProject` and `removeProject` endpoints. Note that over time, more types of memberships may be added to this property.

The time at which this task was last modified.

*Note: This does not currently reflect any changes in
associations such as projects or comments that may have been
added or removed from the task.*

Free-form textual information associated with the task (i.e. its description).

*Deprecated - please use likes instead* The number of users who have hearted this task.

The number of users who have liked this task.

[Opt In](/docs/inputoutput-options). The number of subtasks on this task.


The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.
The resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date.

Date and time on which work begins for the task, or null if the task has no start time. This takes an ISO 8601 date string in UTC and should not be used together with `start_on`.
*Note: `due_at` must be present in the request when setting or unsetting the `start_at` parameter.*

The day on which work begins for the task , or null if the task has no start date. This takes a date with `YYYY-MM-DD` format and should not be used together with `start_at`.
*Note: `due_on` or `due_at` must be present in the request when setting or unsetting the `start_on` parameter.*

Tasks

Controls who can edit team name and description


Controls who can edit team visibility and trash teams


Controls who can accept or deny guest invites for a given team


The description of the team with formatting as HTML.


Controls who can accept or deny join team requests for a Membership by Request team


Controls who can accept or deny member invites for a given team


The visibility of the team to users in the same organization


Teams

A map of the user’s profile photo in various sizes, or null if no photo is set. Sizes provided are 21, 27, 36, 60, 128, and 1024. All images are in PNG format, except for 1024 (which is in JPEG format).

A string identifying a user. This can either be the string "me", an email, or the gid of a user.

Workspaces and organizations this user may access.
Note\: The API will only return workspaces and organizations that also contain the authenticated user.

Users

The email domains that are associated with this workspace.

Whether the workspace is an *organization*.

Workspaces

Asana

Get the full record for a single attachment.

Get an attachment

Deletes a specific, existing attachment.

Returns an empty data record.

Delete an attachment

Returns the compact records for all attachments on the object.

There are three possible `parent` values for this request: `project`, `project_brief`, and `task`. For a project, an attachment refers to a file uploaded to the "Key resources" section in the project Overview. For a project brief, an attachment refers to inline files in the project brief itself. For a task, an attachment refers to a file directly associated to that task.

Note that within the Asana app, inline images in the task description do not appear in the index of image thumbnails nor as stories in the task. However, requests made to `GET /attachments` for a task will return all of the images in the task, including inline images.

Get attachments from an object

Upload an attachment.

This method uploads an attachment on an object and returns the compact
record for the created attachment object. This is possible by either:

- Providing the URL of the external resource being attached, or
- Downloading the file content first and then uploading it as any other attachment. Note that it is not possible to attach
files from third party services such as Dropbox, Box, Vimeo & Google Drive via the API

The 100MB size limit on attachments in Asana is enforced on this endpoint.

This endpoint expects a multipart/form-data encoded request containing the full contents of the file to be uploaded.

Requests made should follow the HTTP/1.1 specification that line
terminators are of the form `CRLF` or `\r\n` outlined
[here](http://www.w3.org/Protocols/HTTP/1.1/draft-ietf-http-v11-spec-01#Basic-Rules) in order for the server to reliably and properly handle the request.

Upload an attachment

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.

Get audit log events

Make multiple requests in parallel to Asana's API.

Submit parallel requests

Returns a list of all of the custom fields settings on a project, in compact form. Note that, as in all queries to collections which return compact representation, `opt_fields` can be used to include more data than is returned in the compact representation. See the [getting started guide on input/output options](https://developers.asana.com/docs/#input-output-options) for more information.

Get a project's custom fields

Returns a list of all of the custom fields settings on a portfolio, in compact form.

Get a portfolio's custom fields

Creates a new custom field in a workspace. Every custom field is required
to be created in a specific workspace, and this workspace cannot be
changed once set.

A custom field’s name must be unique within a workspace and not conflict
with names of existing task properties such as `Due Date` or `Assignee`.
A custom field’s type must be one of `text`, `enum`, `multi_enum`, `number`,
`date`, or `people`.

Returns the full record of the newly created custom field.

Create a custom field

Get the complete definition of a custom field’s metadata.

Since custom fields can be defined for one of a number of types, and
these types have different data and behaviors, there are fields that are
relevant to a particular type. For instance, as noted above, enum_options
is only relevant for the enum type and defines the set of choices that
the enum could represent. The examples below show some of these
type-specific custom field definitions.

Get a custom field

A specific, existing custom field can be updated by making a PUT request on the URL for that custom field. Only the fields provided in the `data` block will be updated; any unspecified fields will remain unchanged
When using this method, it is best to specify only those fields you wish to change, or else you may overwrite changes made by another user since you last retrieved the custom field.
A custom field’s `type` cannot be updated.
An enum custom field’s `enum_options` cannot be updated with this endpoint. Instead see “Work With Enum Options” for information on how to update `enum_options`.
Locked custom fields can only be updated by the user who locked the field.
Returns the complete updated custom field record.

Update a custom field

A specific, existing custom field can be deleted by making a DELETE request on the URL for that custom field.
Locked custom fields can only be deleted by the user who locked the field.
Returns an empty data record.

Delete a custom field

Returns a list of the compact representation of all of the custom fields in a workspace.

Get a workspace's custom fields

Creates an enum option and adds it to this custom field’s list of enum options. A custom field can have at most 500 enum options (including disabled options). By default new enum options are inserted at the end of a custom field’s list.
Locked custom fields can only have enum options added by the user who locked the field.
Returns the full record of the newly created enum option.

Create an enum option

Moves a particular enum option to be either before or after another specified enum option in the custom field.
Locked custom fields can only be reordered by the user who locked the field.

Reorder a custom field's enum

Updates an existing enum option. Enum custom fields require at least one enabled enum option.
Locked custom fields can only be updated by the user who locked the field.
Returns the full record of the updated enum option.

Update an enum option

Returns the full record for all events that have occurred since the sync
token was created.

A `GET` request to the endpoint `/[path_to_resource]/events` can be made in
lieu of including the resource ID in the data for the request.

Asana limits a single sync token to 100 events. If more than 100 events exist
for a given resource, `has_more: true` will be returned in the response, indicating
that there are more events to pull. 

*Note: The resource returned will be the resource that triggered the
event. This may be different from the one that the events were requested
for. For example, a subscription to a project will contain events for
tasks contained within the project.*

Get events on a resource

Returns the complete updated goal relationship record for a single goal relationship.

Get a goal relationship

An existing goal relationship can be updated by making a PUT request on the URL for
that goal relationship. Only the fields provided in the `data` block will be updated;
any unspecified fields will remain unchanged.

Returns the complete updated goal relationship record.

Update a goal relationship

Returns compact goal relationship records.

Get goal relationships

Creates a goal relationship by adding a supporting resource to a given goal.

Returns the newly created goal relationship record.

Add a supporting goal relationship

Removes a goal relationship for a given parent goal.

Removes a supporting goal relationship

Returns the complete goal record for a single goal.

Get a goal

An existing goal can be updated by making a PUT request on the URL for
that goal. Only the fields provided in the `data` block will be updated;
any unspecified fields will remain unchanged.

Returns the complete updated goal record.

Update a goal

A specific, existing goal can be deleted by making a DELETE request on the URL for that goal.

Returns an empty data record.

Delete a goal

Get goals

Creates a new goal in a workspace or team.

Returns the full record of the newly created goal.

Create a goal

Creates and adds a goal metric to a specified goal. Note that this replaces an existing goal metric if one already exists.

Create a goal metric

Updates a goal's existing metric's `current_number_value` if one exists,
otherwise responds with a 400 status code.

Returns the complete updated goal metric record.

Update a goal metric

Adds followers to a goal. Returns the goal the followers were added to.
Each goal can be associated with zero or more followers in the system.
Requests to add/remove followers, if successful, will return the complete updated goal record, described above.

Add a collaborator to a goal

Removes followers from a goal. Returns the goal the followers were removed from.
Each goal can be associated with zero or more followers in the system.
Requests to add/remove followers, if successful, will return the complete updated goal record, described above.

Remove a collaborator from a goal

Returns a compact representation of all of the parent goals of a goal.

Get parent goals from a goal

Get a job by id

Returns compact `goal_membership`, `team_membership`, `project_membership`, `portfolio_membership`, or `workspace_membership` records. The possible types for `parent` in this request are `project`, `portfolio`, `team`, `goal`, and `workspace`. An additional member (user GID or team GID) can be passed in to filter to a specific membership. If a `parent` param is not provided, a `member`, `resource_subtype`, and `workspace` param must be provided.

Get multiple memberships

Creates a new membership in a `team`, `project`, `goal`, or `portfolio`.
`Teams` or `users` can be a member of `goals`. `Project`, `team`, and
`portfolios` have users as members.

Returns the full record of the newly created membership.

Create a membership

A specific, existing membership can be deleted by making a `DELETE` request
on the URL for that membership.

Returns an empty data record.

Delete a membership

An existing membership can be updated by making a `PUT` request on the URL for that goal. Only the fields provided in the `data` block will be updated; any unspecified fields will remain unchanged. Memberships on `project`, `portfolio`, `team`, and `goals` can be updated.

Update a membership

This method creates a request to export an Organization. Asana will complete the export at some point after you create the request.

Create an organization export request

Returns details of a previously-requested Organization export.

Get details on an org export request

Returns a list of portfolio memberships in compact representation. You must specify `portfolio`, `portfolio` and `user`, or `workspace` and `user`.

Get multiple portfolio memberships

Returns the complete portfolio record for a single portfolio membership.

Get a portfolio membership

Returns the compact portfolio membership records for the portfolio.

Get memberships from a portfolio

Returns a list of the portfolios in compact representation that are owned by the current API user.

Get multiple portfolios

Creates a new portfolio in the given workspace with the supplied name.

Note that portfolios created in the Asana UI may have some state
(like the “Priority” custom field) which is automatically added
to the portfolio when it is created. Portfolios created via our
API will *not* be created with the same initial state to allow
integrations to create their own starting state on a portfolio.

Create a portfolio

Returns the complete portfolio record for a single portfolio.

Get a portfolio

An existing portfolio can be updated by making a PUT request on the URL for
that portfolio. Only the fields provided in the `data` block will be updated;
any unspecified fields will remain unchanged.

Returns the complete updated portfolio record.

Update a portfolio

An existing portfolio can be deleted by making a DELETE request on
the URL for that portfolio.

Returns an empty data record.

Delete a portfolio

Get a list of the items in compact form in a portfolio.

Get portfolio items

Add an item to a portfolio.
Returns an empty data block.

Add a portfolio item

Remove an item from a portfolio.
Returns an empty data block.

Remove a portfolio item

Custom fields are associated with portfolios by way of custom field settings.  This method creates a setting for the portfolio.

Add a custom field to a portfolio

Removes a custom field setting from a portfolio.

Remove a custom field from a portfolio

Adds the specified list of users as members of the portfolio.
Returns the updated portfolio record.

Add users to a portfolio

Removes the specified list of users from members of the portfolio.
Returns the updated portfolio record.

Remove users from a portfolio

Get a project brief

An existing project brief can be updated by making a PUT request on the URL for
that project brief. Only the fields provided in the `data` block will be updated;
any unspecified fields will remain unchanged.

Returns the complete updated project brief record.

Update a project brief

Deletes a specific, existing project brief.

Returns an empty data record.

Delete a project brief

Creates a new project brief.

Returns the full record of the newly created project brief.

Create a project brief

Returns the complete project record for a single project membership.

Get a project membership

Returns the compact project membership records for the project.

Get memberships from a project

*Deprecated: new integrations should prefer the `/status_updates/{status_gid}` route.*

Returns the complete record for a single status update.

Get a project status

*Deprecated: new integrations should prefer the `/status_updates/{status_gid}` route.*

Deletes a specific, existing project status update.

Returns an empty data record.

Delete a project status

*Deprecated: new integrations should prefer the `/status_updates` route.*

Returns the compact project status update records for all updates on the project.

Get statuses from a project

*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.

Asana API Integration Profile

How to work with Tags in Asana API

Operations on Tags Collection

See Related Collections

Build every single integration your customers need with AI

Field Name	API Key	Type	Description
Gid	gid	string	Globally unique identifier of the resource, as a string.
Resource Type	resource_type	string	The base type of this resource.
Name	name	string	Name of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.
Color	color	string	Color of the tag.
Notes	notes	string	Free-form textual information associated with the tag (i.e. its description).