Query structured spec data via REST or MCP. Get exactly what your agent needs.
https://app.asana.com/api/1.0
/allocations
Returns a list of allocations filtered to a specific project or user.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| parent | query | optional | string | Globally unique identifier for the project to filter allocations by. |
| assignee | query | optional | string | Globally unique identifier for the user the allocation is assigned to. |
| workspace | query | optional | string | Globally unique identifier for the workspace. |
| 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 allocations.
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 /allocations
/allocations
Creates a new allocation.
Returns the full record of the newly created allocation.
| 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 allocation to create.
application/json
AllocationsCreateRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ effort | object | optional |
| └ type | string | optional |
| └ value | number | optional |
| └ end_date | string | required |
| └ start_date | string | required |
| └ parent | string | required |
| └ assignee | string | required |
Successfully created a new allocation.
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 /allocations
/allocations/{allocation_gid}
A specific, existing allocation can be deleted by making a DELETE request on the URL for that allocation.
Returns an empty data record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| allocation_gid | path | optional | string | Globally unique identifier for the allocation. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
Successfully deleted the specified allocation.
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 /allocations/{allocation_gid}
/allocations/{allocation_gid}
Returns the complete allocation record for a single allocation.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| allocation_gid | path | optional | string | Globally unique identifier for the allocation. |
| 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 record for a single allocation.
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 /allocations/{allocation_gid}
/allocations/{allocation_gid}
An existing allocation can be updated by making a PUT request on the URL for
that allocation. Only the fields provided in the data block will be updated;
any unspecified fields will remain unchanged.
Returns the complete updated allocation record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| allocation_gid | path | optional | string | Globally unique identifier for the allocation. |
| 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 updated fields for the allocation.
application/json
AllocationsUpdateRecordByIdRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ effort | object | optional |
| └ type | string | optional |
| └ value | number | optional |
| └ end_date | string | optional |
| └ start_date | string | optional |
| └ parent | string | optional |
| └ assignee | string | optional |
Successfully updated the allocation.
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 /allocations/{allocation_gid}
/attachments
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.
| 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 |
| 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 attachments.
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 /attachments
/attachments
Upload an attachment.
This method uploads an attachment on an object and returns the compact
record for the created attachment object. This is possible by either:
The 100MB size limit on attachments in Asana is enforced on this endpoint.
This endpoint expects a multipart/form-data encoded request containing the full contents of the file to be uploaded.
Requests made should follow the HTTP/1.1 specification that line
terminators are of the form CRLF or \r\n outlined
here in order for the server to reliably and properly handle the request.
| 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 file you want to upload.
Note when using curl:
Be sure to add an ‘@’ before the file path, and use the --form
option instead of the -d option.
When uploading PDFs with curl, force the content-type to be pdf by
appending the content type to the file path: --form
"file=@file.pdf;type=application/pdf".
multipart/form-data
AttachmentRequest
| Property | Type | Required |
|---|---|---|
| url | string | optional |
| file | string | optional |
| name | string | optional |
| parent | string | required |
| connect_to_app | boolean | optional |
| resource_subtype | string | optional |
Successfully uploaded the attachment to the parent object.
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 /attachments
/attachments/{attachment_gid}
Deletes a specific, existing attachment.
Returns an empty data record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| attachment_gid | path | optional | string | Globally unique identifier for the attachment. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
Successfully deleted the specified attachment.
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 /attachments/{attachment_gid}
/attachments/{attachment_gid}
Get the full record for a single attachment.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| attachment_gid | path | optional | string | Globally unique identifier for the attachment. |
| 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 record for a single attachment.
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.
You have exceeded one of the enforced rate limits in the API. See the documentation on rate limiting for more information.
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.
There is an issue between the load balancers and Asana’s API.
Either the upstream service is unavailable to the API, or the API has been intentionally shut off.
This request took too long to complete.
GET /attachments/{attachment_gid}
/workspaces/{workspace_gid}/audit_log_events
Retrieve the audit log events that have been captured in your domain.
This endpoint will return a list of AuditLogEvent objects, sorted by creation time in ascending order. Note that the Audit Log API captures events from October 8th, 2021 and later. Queries for events before this date will not return results.
There are a number of query parameters (below) that can be used to filter the set of AuditLogEvent objects that are returned in the response. Any combination of query parameters is valid. When no filters are provided, all of the events that have been captured in your domain will match.
The list of events will always be paginated. The default limit is 1000 events. The next set of events can be retrieved using the offset from the previous response. If there are no events that match the provided filters in your domain, the endpoint will return null for the next_page field. Querying again with the same filters may return new events if they were captured after the last request. Once a response includes a next_page with an offset, subsequent requests can be made with the latest offset to poll for new events that match the provided filters.
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 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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| workspace_gid | path | optional | string | Globally unique identifier for the workspace or organization. |
| start_at | query | optional | string | Filter to events created after this time (inclusive). |
| end_at | query | optional | string | Filter to events created before this time (exclusive). |
| event_type | query | optional | string | Filter to events of this type. |
| actor_type | query | optional | string | Filter to events with an actor of this type. |
| actor_gid | query | optional | string | Filter to events triggered by the actor with this ID. |
| resource_gid | query | optional | string | Filter to events with this resource ID. |
| limit | query | optional | integer | Results per page. |
| offset | query | optional | string | Offset token. |
AuditLogEvents were successfully retrieved.
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}/audit_log_events
/batch
Make multiple requests in parallel to Asana’s API.
| 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 requests to batch together via the Batch API.
application/json
BatchApiSubmitParallelRequestsRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ actions | array | optional |
| └ data | object | optional |
| └ method | string | required |
| └ options | object | optional |
| └ limit | integer | optional |
| └ fields | array | optional |
| └ offset | integer | optional |
| └ relative_path | string | required |
Successfully completed the requested batch API operations.
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 /batch
/portfolios/{portfolio_gid}/custom_field_settings
Returns a list of all of the custom fields settings on a portfolio, in compact form.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| portfolio_gid | path | optional | string | Globally unique identifier for the portfolio. |
| 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 custom field settings objects for a portfolio.
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 /portfolios/{portfolio_gid}/custom_field_settings
/projects/{project_gid}/custom_field_settings
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 documentation for input/output options for more information.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| 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 custom field settings objects for a project.
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}/custom_field_settings
/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.
| 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 custom field object to create.
application/json
CustomFieldsCreateNewFieldRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ type | string | optional |
| └ enabled | boolean | optional |
| └ id_prefix | string | optional |
| └ date_value | object | optional |
| └ date | string | optional |
| └ date_time | string | optional |
| └ enum_value | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ color | string | optional |
| └ enabled | boolean | optional |
| └ text_value | string | optional |
| └ enum_options | array | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ color | string | optional |
| └ enabled | boolean | optional |
| └ number_value | number | optional |
| └ display_value | string | optional |
| └ is_formula_field | boolean | optional |
| └ resource_subtype | string | optional |
| └ multi_enum_values | array | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ color | string | optional |
| └ enabled | boolean | optional |
| └ representation_type | string | optional |
| └ format | string | optional |
| └ precision | integer | optional |
| └ description | string | optional |
| └ custom_label | string | optional |
| └ …8 more | object | optional |
Custom field successfully created.
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 /custom_fields
/custom_fields/{custom_field_gid}
A specific, existing custom field can be deleted by making a DELETE request on the URL for that custom field.
Locked custom fields can only be deleted by the user who locked the field.
Returns an empty data record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| custom_field_gid | path | optional | string | Globally unique identifier for the custom field. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
The custom field was successfully deleted.
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 /custom_fields/{custom_field_gid}
/custom_fields/{custom_field_gid}
Get the complete definition of a custom field’s metadata.
Since custom fields can be defined for one of a number of types, and
these types have different data and behaviors, there are fields that are
relevant to a particular type. For instance, as noted above, enum_options
is only relevant for the enum type and defines the set of choices that
the enum could represent. The examples below show some of these
type-specific custom field definitions.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| custom_field_gid | path | optional | string | Globally unique identifier for the custom field. |
| 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 complete definition of a custom field’s metadata.
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 /custom_fields/{custom_field_gid}
/custom_fields/{custom_field_gid}
A specific, existing custom field can be updated by making a PUT request on the URL for that custom field. Only the fields provided in the data block will be updated; any unspecified fields will remain unchanged
When using this method, it is best to specify only those fields you wish to change, or else you may overwrite changes made by another user since you last retrieved the custom field.
A custom field’s type cannot be updated.
An enum custom field’s enum_options cannot be updated with this endpoint. Instead see “Work With Enum Options” for information on how to update enum_options.
Locked custom fields can only be updated by the user who locked the field.
Returns the complete updated custom field record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| custom_field_gid | path | optional | string | Globally unique identifier for the custom field. |
| 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 custom field object with all updated properties.
application/json
CustomFieldsUpdateFieldRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ type | string | optional |
| └ enabled | boolean | optional |
| └ id_prefix | string | optional |
| └ date_value | object | optional |
| └ date | string | optional |
| └ date_time | string | optional |
| └ enum_value | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ color | string | optional |
| └ enabled | boolean | optional |
| └ text_value | string | optional |
| └ enum_options | array | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ color | string | optional |
| └ enabled | boolean | optional |
| └ number_value | number | optional |
| └ display_value | string | optional |
| └ is_formula_field | boolean | optional |
| └ resource_subtype | string | optional |
| └ multi_enum_values | array | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ color | string | optional |
| └ enabled | boolean | optional |
| └ representation_type | string | optional |
| └ format | string | optional |
| └ precision | integer | optional |
| └ description | string | optional |
| └ custom_label | string | optional |
| └ …8 more | object | optional |
The custom field was successfully updated.
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 /custom_fields/{custom_field_gid}
/custom_fields/{custom_field_gid}/enum_options
Creates an enum option and adds it to this custom field’s list of enum options. A custom field can have at most 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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| custom_field_gid | path | optional | string | Globally unique identifier for the custom field. |
| 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 enum option object to create.
application/json
CustomFieldsAddEnumOptionRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ color | string | optional |
| └ enabled | boolean | optional |
| └ insert_after | string | optional |
| └ insert_before | string | optional |
Custom field enum option successfully created.
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 /custom_fields/{custom_field_gid}/enum_options
/custom_fields/{custom_field_gid}/enum_options/insert
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| custom_field_gid | path | optional | string | Globally unique identifier for the custom field. |
| 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 enum option object to create.
application/json
CustomFieldsReorderEnumOptionRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ enum_option | string | required |
| └ after_enum_option | string | optional |
| └ before_enum_option | string | optional |
Custom field enum option successfully reordered.
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 /custom_fields/{custom_field_gid}/enum_options/insert
/enum_options/{enum_option_gid}
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| enum_option_gid | path | required | string | Globally unique identifier for the enum option. |
| 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 enum option object to update
application/json
CustomFieldsUpdateEnumOptionRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ color | string | optional |
| └ enabled | boolean | optional |
Successfully updated the specified custom field enum.
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 /enum_options/{enum_option_gid}
/workspaces/{workspace_gid}/custom_fields
Returns a list of the compact representation of all of the custom fields in a workspace.
| 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 all custom fields for the given workspace.
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}/custom_fields
/events
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| resource | query | required | string | A resource ID to subscribe to. The resource can be a task, project, or goal. |
| sync | query | optional | string | A sync token received from the last request, or none on first sync. Events will be returned from the point in time that the sync token was generated. |
| 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 events.
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.
The request is missing or has an expired sync token.
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 /events
/goal_relationships
Returns compact goal relationship records.
| 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. |
| supported_goal | query | required | string | Globally unique identifier for the supported goal in the goal relationship. |
| resource_subtype | query | optional | string | If provided, filter to goal relationships with a given resource_subtype. |
| 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 goal relationships.
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 /goal_relationships
/goal_relationships/{goal_relationship_gid}
Returns the complete updated goal relationship record for a single goal relationship.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| goal_relationship_gid | path | optional | string | Globally unique identifier for the goal relationship. |
| 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 record for the goal relationship.
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 /goal_relationships/{goal_relationship_gid}
/goal_relationships/{goal_relationship_gid}
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| goal_relationship_gid | path | optional | string | Globally unique identifier for the goal relationship. |
| 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 updated fields for the goal relationship.
application/json
GoalRelationshipsUpdateGoalRelationshipRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ resource_subtype | string | optional |
| └ contribution_weight | number | optional |
| └ supporting_resource | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ supported_goal | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ owner | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
Successfully updated the goal relationship.
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 /goal_relationships/{goal_relationship_gid}
/goals/{goal_gid}/addSupportingRelationship
Creates a goal relationship by adding a supporting resource to a given goal.
Returns the newly created goal relationship record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| goal_gid | path | optional | string | Globally unique identifier for the goal. |
| 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 supporting resource to be added to the goal
application/json
GoalRelationshipsCreateSupportingRelationshipRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ insert_after | string | optional |
| └ insert_before | string | optional |
| └ contribution_weight | number | optional |
| └ supporting_resource | string | required |
Successfully created the goal relationship.
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 /goals/{goal_gid}/addSupportingRelationship
/goals/{goal_gid}/removeSupportingRelationship
Removes a goal relationship for a given parent goal.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| goal_gid | path | optional | string | Globally unique identifier for the goal. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
The supporting resource to be removed from the goal
application/json
GoalRelationshipsRemoveSupportingRelationshipRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ supporting_resource | string | required |
Successfully removed the goal relationship.
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 /goals/{goal_gid}/removeSupportingRelationship
/goals
Returns compact goal records.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| portfolio | query | optional | string | Globally unique identifier for supporting portfolio. |
| project | query | optional | string | Globally unique identifier for supporting project. |
| task | query | optional | string | Globally unique identifier for supporting task. |
| is_workspace_level | query | optional | boolean | Filter to goals with is_workspace_level set to query value. Must be used with the workspace parameter. |
| team | query | optional | string | Globally unique identifier for the team. |
| workspace | query | optional | string | Globally unique identifier for the workspace. |
| time_periods | query | optional | array | Globally unique identifiers for the time periods. |
| 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 goals.
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 /goals
/goals
Creates a new goal in a workspace or team.
Returns the full record of the newly created goal.
| 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 goal to create.
application/json
GoalsCreateNewGoalRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ liked | boolean | optional |
| └ notes | string | optional |
| └ due_on | string | optional |
| └ start_on | string | optional |
| └ html_notes | string | optional |
| └ is_workspace_level | boolean | optional |
| └ team | string | optional |
| └ owner | string | optional |
| └ workspace | string | optional |
| └ time_period | string | optional |
| └ followers | array | optional |
Successfully created a new goal.
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 /goals
/goals/{goal_gid}
A specific, existing goal can be deleted by making a DELETE request on the URL for that goal.
Returns an empty data record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| goal_gid | path | optional | string | Globally unique identifier for the goal. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
Successfully deleted the specified goal.
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 /goals/{goal_gid}
/goals/{goal_gid}
Returns the complete goal record for a single goal.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| goal_gid | path | optional | string | Globally unique identifier for the goal. |
| 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 record for a single goal.
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 /goals/{goal_gid}
/goals/{goal_gid}
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| goal_gid | path | optional | string | Globally unique identifier for the goal. |
| 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 updated fields for the goal.
application/json
GoalsUpdateGoalRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ liked | boolean | optional |
| └ notes | string | optional |
| └ due_on | string | optional |
| └ start_on | string | optional |
| └ html_notes | string | optional |
| └ is_workspace_level | boolean | optional |
| └ team | string | optional |
| └ owner | string | optional |
| └ workspace | string | optional |
| └ time_period | string | optional |
| └ status | string | optional |
Successfully updated the goal.
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 /goals/{goal_gid}
/goals/{goal_gid}/addFollowers
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| goal_gid | path | optional | string | Globally unique identifier for the goal. |
| 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 be added as collaborators
application/json
GoalsAddCollaboratorsToGoalRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ followers | array | required |
Successfully added users as collaborators.
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 /goals/{goal_gid}/addFollowers
/goals/{goal_gid}/parentGoals
Returns a compact representation of all of the parent goals of a goal.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| goal_gid | path | optional | string | Globally unique identifier for the goal. |
| 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 goal’s parent goals.
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 /goals/{goal_gid}/parentGoals
/goals/{goal_gid}/removeFollowers
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| goal_gid | path | optional | string | Globally unique identifier for the goal. |
| 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 be removed as collaborators
application/json
GoalsRemoveFollowersFromGoalRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ followers | array | required |
Successfully removed users as collaborators.
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 /goals/{goal_gid}/removeFollowers
/goals/{goal_gid}/setMetric
Creates and adds a goal metric to a specified goal. Note that this replaces an existing goal metric if one already exists.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| goal_gid | path | optional | string | Globally unique identifier for the goal. |
| 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 goal metric to create.
application/json
GoalsCreateMetricRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ unit | string | optional |
| └ precision | integer | optional |
| └ currency_code | string | optional |
| └ progress_source | string | optional |
| └ resource_subtype | string | optional |
| └ target_number_value | number | optional |
| └ current_number_value | number | optional |
| └ initial_number_value | number | optional |
| └ current_display_value | string | optional |
Successfully created a new goal metric.
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 /goals/{goal_gid}/setMetric
/goals/{goal_gid}/setMetricCurrentValue
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| goal_gid | path | optional | string | Globally unique identifier for the goal. |
| 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 updated fields for the goal metric.
application/json
GoalsUpdateMetricCurrentValueRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ current_number_value | number | optional |
Successfully updated the goal metric.
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 /goals/{goal_gid}/setMetricCurrentValue
/jobs/{job_gid}
Returns the full record for a job.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| job_gid | path | optional | string | Globally unique identifier for the job. |
| 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 Job.
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 /jobs/{job_gid}
/memberships
Returns compact goal_membership or project_membership records. The possible types for parent in this request are goal or project. An additional member (user GID or team GID) can be passed in to filter to a specific membership.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
| parent | query | optional | string | Globally unique identifier for |
| member | query | optional | string | Globally unique identifier for |
| 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 membership.
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 /memberships
/memberships
Creates a new membership in a goal or project. Teams or users can be a member
of goals or projects.
Returns the full record of the newly created membership.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
The updated fields for the membership.
application/json
MembershipsCreateNewRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ access_level | string | optional |
| └ role | string | optional |
| └ member | string | optional |
| └ parent | string | optional |
Successfully created the requested membership.
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 /memberships
/memberships/{membership_gid}
A specific, existing membership for a goal or project can be deleted by making a DELETE request
on the URL for that membership.
Returns an empty data record.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| membership_gid | path | optional | string | Globally unique identifier for the membership. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
Successfully deleted the requested membership.
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 /memberships/{membership_gid}
/memberships/{membership_gid}
Returns compact project_membership record for a single membership. GET only supports project memberships currently
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| membership_gid | path | optional | string | Globally unique identifier for the membership. |
| 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 record for a single membership.
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 /memberships/{membership_gid}
/memberships/{membership_gid}
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 goals and projects can be updated.
Returns the full record of the updated membership.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| membership_gid | path | optional | string | Globally unique identifier for the membership. |
| opt_pretty | query | optional | boolean | Provides “pretty” output. |
The membership to update.
application/json
MembershipsUpdateMembershipRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ access_level | string | optional |
Successfully updated the requested membership.
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 /memberships/{membership_gid}
/organization_exports
This method creates a request to export an Organization. Asana will complete the export at some point after you create the request.
| 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 organization to export.
application/json
OrganizationExportsCreateExportRequestRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ organization | string | optional |
Successfully created organization export request.
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 /organization_exports
/organization_exports/{organization_export_gid}
Returns details of a previously-requested Organization export.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| organization_export_gid | path | optional | string | Globally unique identifier for the organization export. |
| 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 organization export object.
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 /organization_exports/{organization_export_gid}
/portfolio_memberships
Returns a list of portfolio memberships in compact representation. You must specify portfolio, portfolio and user, or workspace and user.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| portfolio | query | optional | string | The portfolio to filter results on. |
| workspace | query | optional | string | The workspace to filter results on. |
| user | query | optional | string | A string identifying a user. This can either be the string “me”, an email, or the gid of a user. |
| 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 portfolio memberships.
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 /portfolio_memberships
/portfolio_memberships/{portfolio_membership_gid}
Returns the complete portfolio record for a single portfolio membership.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| portfolio_membership_gid | path | optional | string | — |
| 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 requested portfolio membership.
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 /portfolio_memberships/{portfolio_membership_gid}
/portfolios/{portfolio_gid}/portfolio_memberships
Returns the compact portfolio membership records for the portfolio.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| portfolio_gid | path | optional | string | Globally unique identifier for the portfolio. |
| user | query | optional | string | A string identifying a user. This can either be the string “me”, an email, or the gid of a user. |
| 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 portfolio’s memberships.
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 /portfolios/{portfolio_gid}/portfolio_memberships
/portfolios
Returns a list of the portfolios in compact representation that are owned by the current API user.
| 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 | required | string | The workspace or organization to filter portfolios on. |
| owner | query | optional | string | The user who owns the portfolio. Currently, API users can only get a list of portfolios that they themselves own, unless the request is made from a Service Account. In the case of a Service Account, if this parameter is specified, then all portfolios owned by this parameter are returned. Otherwise, all portfolios across the workspace are returned. |
| 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 portfolios.
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 /portfolios
/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.
| 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 portfolio to create.
application/json
PortfoliosCreateNewPortfolioRecordRequest
| Property | Type | Required |
|---|---|---|
| data | object | optional |
| └ gid | string | optional |
| └ resource_type | string | optional |
| └ name | string | optional |
| └ color | string | optional |
| └ public | boolean | optional |
| └ members | array | optional |
| └ workspace | string | optional |
Successfully created portfolio.
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 /portfolios
AddCustomFieldSettingRequest
{
"type": "object",
"required": [
"custom_field"
],
"properties": {
"custom_field": {
"type": "string",
"example": "14916",
"description": "The custom field to associate with this container."
},
"insert_after": {
"type": "string",
"example": "1331",
"description": "A gid of a Custom Field Setting on this container, after which the new Custom Field Setting will be added. `insert_before` and `insert_after` parameters cannot both be specified."
},
"is_important": {
"type": "boolean",
"example": true,
"description": "Whether this field should be considered important to this container (for instance, to display in the list view of items in the container)."
},
"insert_before": {
"type": "string",
"example": "1331",
"description": "A gid of a Custom Field Setting on this container, before which the new Custom Field Setting will be added. `insert_before` and `insert_after` parameters cannot both be specified."
}
}
}
AddFollowersRequest
{
"type": "object",
"required": [
"followers"
],
"properties": {
"followers": {
"type": "string",
"example": 521621621373,
"description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user."
}
}
}
AddMembersRequest
{
"type": "object",
"required": [
"members"
],
"properties": {
"members": {
"type": "string",
"example": 521621621373,
"description": "An array of strings identifying users. These can either be the string \"me\", an email, or the gid of a user."
}
}
}
AllocationBase
{
"allOf": [
{
"$ref": "#/components/schemas/AsanaResource"
},
{
"type": "object",
"properties": {
"effort": {
"type": "object",
"nullable": true,
"properties": {
"type": {
"enum": [
"hours",
"percent"
],
"type": "string",
"description": "The units used for tracking effort on an allocation, either \"hours\" or \"percent\"."
},
"value": {
"type": "number",
"example": 50,
"description": "The numeric effort value on the allocation."
}
},
"description": "The amount of time associated with the allocation, represented as a percentage or number of hours"
},
"end_date": {
"type": "string",
"format": "date",
"example": "2024-02-28",
"description": "The localized day on which the allocation ends."
},
"start_date": {
"type": "string",
"format": "date",
"example": "2024-02-28",
"description": "The localized day on which the allocation starts."
}
},
"x-docs-overrides": {
"properties.resource_type.example": "allocation"
}
}
]
}
AllocationRequest
{
"allOf": [
{
"$ref": "#/components/schemas/AllocationBase"
},
{
"type": "object",
"properties": {
"parent": {
"type": "string",
"description": "Globally unique identifier for the project the allocation is on."
},
"assignee": {
"type": "string",
"description": "Globally unique identifier for the user who is assigned to the allocation."
}
}
}
]
}
AllocationResponse
{
"allOf": [
{
"$ref": "#/components/schemas/AllocationBase"
},
{
"type": "object",
"properties": {
"parent": {
"$ref": "#/components/schemas/ProjectCompact",
"type": "object",
"description": "The project the allocation is on."
},
"assignee": {
"$ref": "#/components/schemas/UserCompact",
"type": "object",
"description": "The user who is assigned to the allocation."
},
"created_by": {
"$ref": "#/components/schemas/UserCompact",
"type": "object",
"description": "The user who created the allocation."
},
"resource_subtype": {
"type": "string",
"example": "project_allocation",
"description": "The subtype of the allocation."
}
}
}
]
}
AllocationsCreateRecordRequest
{
"type": "object",
"properties": {
"data": {
"allOf": [
{
"$ref": "#/components/schemas/AllocationRequest"
},
{
"type": "object",
"required": [
"assignee",
"end_date",
"parent",
"start_date"
]
}
]
}
}
}
AllocationsCreateRecordResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/AllocationResponse"
}
}
}
AllocationsDeleteAllocationByIdResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/EmptyResponse"
}
}
}
AllocationsGetMultipleResponse
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AllocationResponse"
}
},
"next_page": {
"$ref": "#/components/schemas/NextPage"
}
}
}
AllocationsGetRecordByIdResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/AllocationResponse"
}
}
}
AllocationsUpdateRecordByIdRequest
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/AllocationRequest"
}
}
}
AllocationsUpdateRecordByIdResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/AllocationResponse"
}
}
}
AsanaNamedResource
{
"allOf": [
{
"$ref": "#/components/schemas/AsanaResource"
},
{
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "Bug Task",
"description": "The name of the object."
}
}
}
]
}
AsanaResource
{
"type": "object",
"properties": {
"gid": {
"type": "string",
"example": "12345",
"readOnly": true,
"description": "Globally unique identifier of the resource, as a string.",
"x-insert-after": false
},
"resource_type": {
"type": "string",
"example": "task",
"readOnly": true,
"description": "The base type of this resource.",
"x-insert-after": "gid"
}
},
"description": "A generic Asana Resource, containing a globally unique identifier."
}
AttachmentCompact
{
"allOf": [
{
"$ref": "#/components/schemas/AsanaResource"
},
{
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "Screenshot.png",
"readOnly": true,
"description": "The name of the file."
},
"resource_subtype": {
"type": "string",
"example": "dropbox",
"description": "The service hosting the attachment. Valid values are `asana`, `dropbox`, `gdrive`, `onedrive`, `box`, `vimeo`, and `external`."
}
},
"description": "An *attachment* object represents any file attached to a task in Asana, whether it’s an uploaded file or one associated via a third-party service such as Dropbox or Google Drive.",
"x-docs-overrides": {
"properties.resource_type.example": "attachment"
}
}
]
}
AttachmentRequest
{
"type": "object",
"required": [
"parent"
],
"properties": {
"url": {
"type": "string",
"description": "The URL of the external resource being attached. Required for attachments of type `external`.\n"
},
"file": {
"type": "string",
"format": "binary",
"description": "Required for `asana` attachments.\n"
},
"name": {
"type": "string",
"description": "The name of the external resource being attached. Required for attachments of type `external`.\n"
},
"parent": {
"type": "string",
"description": "Required identifier of the parent task, project, or project_brief, as a string.\n"
},
"connect_to_app": {
"type": "boolean",
"description": "*Optional*. Only relevant for external attachments with a parent task. A boolean indicating whether the current app should be connected with the attachment for the purposes of showing an app components widget. Requires the app to have been added to a project the parent task is in.\n"
},
"resource_subtype": {
"enum": [
"asana",
"dropbox",
"gdrive",
"onedrive",
"box",
"vimeo",
"external"
],
"type": "string",
"example": "external",
"description": "The type of the attachment. Must be one of the given values. If not specified, a file attachment of type `asana` will be assumed. Note that if the value of `resource_subtype` is `external`, a `parent`, `name`, and `url` must also be provided.\n"
}
}
}
AttachmentResponse
{
"allOf": [
{
"$ref": "#/components/schemas/AttachmentCompact"
},
{
"type": "object",
"properties": {
"host": {
"type": "string",
"example": "dropbox",
"readOnly": true,
"description": "The service hosting the attachment. Valid values are `asana`, `dropbox`, `gdrive`, `box`, and `vimeo`."
},
"size": {
"type": "integer",
"example": 12345,
"readOnly": true,
"description": "The size of the attachment in bytes. Only present when the `resource_subtype` is `asana`."
},
"parent": {
"allOf": [
{
"$ref": "#/components/schemas/TaskCompact"
},
{
"type": "object",
"nullable": true,
"readOnly": true,
"properties": {
"resource_subtype": {
"type": "string",
"example": "default_task",
"nullable": true,
"description": "The resource subtype of the parent resource that the filter applies to."
}
},
"description": "The task this attachment is attached to."
}
]
},
"view_url": {
"type": "string",
"format": "uri",
"example": "https://www.dropbox.com/s/123/Screenshot.png",
"nullable": true,
"readOnly": true,
"description": "The URL where the attachment can be viewed, which may be friendlier to users in a browser than just directing them to a raw file. May be null if no view URL exists for the service."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2012-02-22T02:06:58.147Z",
"readOnly": true,
"description": "The time at which this resource was created."
},
"download_url": {
"type": "string",
"format": "uri",
"example": "https://s3.amazonaws.com/assets/123/Screenshot.png",
"nullable": true,
"readOnly": true,
"description": "The URL containing the content of the attachment.\n*Note:* May be null if the attachment is hosted by [Box](https://www.box.com/) and will be null if the attachment is a Video Message hosted by [Vimeo](https://vimeo.com/). If present, this URL may only be valid for two minutes from the time of retrieval. You should avoid persisting this URL somewhere and just refresh it on demand to ensure you do not keep stale URLs."
},
"permanent_url": {
"type": "string",
"format": "uri",
"example": "https://s3.amazonaws.com/assets/123/Screenshot.png",
"nullable": true,
"readOnly": true,
"description": ""
},
"connected_to_app": {
"type": "boolean",
"readOnly": true,
"description": "Whether the attachment is connected to the app making the request for the purposes of showing an app components widget. Only present when the `resource_subtype` is `external` or `gdrive`."
}
}
}
]
}
AttachmentsDeleteSpecificResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/EmptyResponse"
}
}
}
AttachmentsGetAllForObjectResponse
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AttachmentCompact"
}
},
"next_page": {
"$ref": "#/components/schemas/NextPage"
}
}
}
AttachmentsGetAttachmentRecordResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/AttachmentResponse"
}
}
}
AttachmentsUploadAttachmentResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/AttachmentResponse"
}
}
}
AuditLogApiGetAuditLogEventsResponse
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AuditLogEvent"
}
},
"next_page": {
"$ref": "#/components/schemas/NextPage"
}
}
}
AuditLogEvent
{
"type": "object",
"properties": {
"gid": {
"type": "string",
"example": "12345",
"description": "Globally unique identifier of the `AuditLogEvent`, as a string.",
"x-insert-after": false
},
"actor": {
"$ref": "#/components/schemas/AuditLogEventActor"
},
"context": {
"$ref": "#/components/schemas/AuditLogEventContext"
},
"details": {
"$ref": "#/components/schemas/AuditLogEventDetails"
},
"resource": {
"$ref": "#/components/schemas/AuditLogEventResource"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2021-01-01T00:00:00.000Z",
"description": "The time the event was created."
},
"event_type": {
"type": "string",
"example": "task_deleted",
"description": "The type of the event."
},
"event_category": {
"type": "string",
"example": "deletion",
"description": "The category that this `event_type` belongs to."
}
},
"description": "An object representing a single event within an Asana domain.\n\nEvery audit log event is comprised of an `event_type`, `actor`, `resource`, and `context`. Some events will include additional metadata about the event under `details`. See our [currently supported list of events](/docs/audit-log-events#supported-audit-log-events) for more details."
}
AuditLogEventActor
{
"type": "object",
"properties": {
"gid": {
"type": "string",
"example": "1111",
"description": "Globally unique identifier of the actor, if it is a user."
},
"name": {
"type": "string",
"example": "Greg Sanchez",
"description": "The name of the actor, if it is a user."
},
"email": {
"type": "string",
"example": "gregsanchez@example.com",
"description": "The email of the actor, if it is a user."
},
"actor_type": {
"enum": [
"user",
"asana",
"asana_support",
"anonymous",
"external_administrator"
],
"type": "string",
"example": "user",
"description": "The type of actor.\nCan be one of `user`, `asana`, `asana_support`, `anonymous`, or `external_administrator`."
}
},
"description": "The entity that triggered the event. Will typically be a user."
}
AuditLogEventContext
{
"type": "object",
"properties": {
"user_agent": {
"type": "string",
"example": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
"description": "The user agent of the client that initiated the event, if applicable."
},
"context_type": {
"enum": [
"web",
"desktop",
"mobile",
"asana_support",
"asana",
"email",
"api"
],
"type": "string",
"example": "web",
"description": "The type of context.\nCan be one of `web`, `desktop`, `mobile`, `asana_support`, `asana`, `email`, or `api`."
},
"oauth_app_name": {
"type": "string",
"description": "The name of the OAuth App that initiated the event.\nOnly present if the `api_authentication_method` is `oauth`."
},
"client_ip_address": {
"type": "string",
"example": "1.1.1.1",
"description": "The IP address of the client that initiated the event, if applicable."
},
"api_authentication_method": {
"enum": [
"cookie",
"oauth",
"personal_access_token",
"service_account"
],
"type": "string",
"description": "The authentication method used in the context of an API request.\nOnly present if the `context_type` is `api`. Can be one of `cookie`, `oauth`, `personal_access_token`, or `service_account`."
}
},
"description": "The context from which this event originated."
}
AuditLogEventDetails
{
"type": "object",
"properties": {
"group": {
"type": "object",
"additionalProperties": true
},
"new_value": {
"type": "string",
"nullable": true
},
"old_value": {
"type": "string",
"nullable": true
}
},
"description": "Event specific details. The schema will vary depending on the `event_type`.",
"additionalProperties": true
}
AuditLogEventResource
{
"type": "object",
"properties": {
"gid": {
"type": "string",
"example": "1111",
"description": "Globally unique identifier of the resource."
},
"name": {
"type": "string",
"example": "Example Task",
"nullable": true,
"description": "The name of the resource."
},
"email": {
"type": "string",
"description": "The email of the resource, if applicable."
},
"resource_type": {
"type": "string",
"example": "task",
"description": "The type of resource."
},
"resource_subtype": {
"type": "string",
"example": "milestone",
"description": "The subtype of resource. Most resources will not have a subtype."
}
},
"description": "The primary object that was affected by this event."
}
BatchApiSubmitParallelRequestsRequest
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/BatchRequest"
}
}
}
BatchApiSubmitParallelRequestsResponse
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BatchResponse"
}
}
}
}
BatchRequest
{
"type": "object",
"properties": {
"actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BatchRequestAction"
}
}
},
"description": "A request object for use in a batch request."
}
BatchRequestAction
{
"type": "object",
"required": [
"relative_path",
"method"
],
"properties": {
"data": {
"type": "object",
"example": {
"assignee": "me",
"workspace": "1337"
},
"description": "For `GET` requests, this should be a map of query parameters you would have normally passed in the URL. Options and pagination are not accepted here; put them in `options` instead. For `POST`, `PATCH`, and `PUT` methods, this should be the content you would have normally put in the data field of the body."
},
"method": {
"enum": [
"get",
"post",
"put",
"delete",
"patch",
"head"
],
"type": "string",
"example": "get",
"description": "The HTTP method you wish to emulate for the action."
},
"options": {
"type": "object",
"example": {
"limit": 3,
"fields": [
"name",
"notes",
"completed"
]
},
"properties": {
"limit": {
"type": "integer",
"example": 50,
"description": "Pagination limit for the request."
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"name",
"gid",
"notes",
"completed"
],
"description": "The fields to retrieve in the request."
},
"offset": {
"type": "integer",
"example": null,
"description": "Pagination offset for the request."
}
},
"description": "Pagination (`limit` and `offset`) and output options (`fields` or `expand`) for the action. “Pretty” JSON output is not an available option on individual actions; if you want pretty output, specify that option on the parent request."
},
"relative_path": {
"type": "string",
"example": "/tasks/123",
"description": "The path of the desired endpoint relative to the API’s base URL. Query parameters are not accepted here; put them in `data` instead."
}
},
"description": "An action object for use in a batch request."
}
BatchResponse
{
"type": "object",
"properties": {
"body": {
"type": "object",
"example": {
"data": {
"gid": "1967",
"name": "Hello, world!",
"notes": "How are you today?",
"completed": false
}
},
"description": "The JSON body that the invoked endpoint returned."
},
"headers": {
"type": "object",
"example": {
"location": "/tasks/1234"
},
"description": "A map of HTTP headers specific to this result. This is primarily used for returning a `Location` header to accompany a `201 Created` result. The parent HTTP response will contain all common headers."
},
"status_code": {
"type": "integer",
"example": 200,
"description": "The HTTP status code that the invoked endpoint returned."
}
},
"description": "A response object returned from a batch request."
}
CreateMembershipRequest
{
"allOf": [
{
"$ref": "#/components/schemas/MembershipRequest"
},
{
"type": "object",
"properties": {
"role": {
"type": "string",
"example": "editor",
"deprecated": true,
"description": "*Deprecated: new integrations should use access_level* The role given to the member. Optional argument, will default to `commenter` for goals and the default project role for projects. Can be `editor` or `commenter` for goals. Can be `admin`,`editor` or `commenter` for projects."
},
"member": {
"type": "string",
"example": 12345,
"description": "The gid of the user or team."
},
"parent": {
"type": "string",
"example": "987654",
"description": "The gid of the `goal` or `project` to add the member to."
}
}
}
]
}
CreateTimeTrackingEntryRequest
{
"type": "object",
"properties": {
"entered_on": {
"type": "string",
"format": "date",
"example": "2023-03-19",
"description": "*Optional*. The day that this entry is logged on. Defaults to today if not specified"
},
"duration_minutes": {
"type": "integer",
"example": 12,
"description": "Time in minutes tracked by the entry. Must be greater than 0"
}
}
}
CustomFieldBase
{
"allOf": [
{
"$ref": "#/components/schemas/CustomFieldCompact"
},
{
"type": "object",
"properties": {
"format": {
"enum": [
"currency",
"identifier",
"percentage",
"custom",
"duration",
"none"
],
"type": "string",
"example": "custom",
"description": "The format of this custom field."
},
"precision": {
"type": "integer",
"example": 2,
"description": "Only relevant for custom fields of type ‘Number’. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.\nFor percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.\nThe identifier format will always have a precision of 0."
},
"description": {
"type": "string",
"example": "Development team priority",
"description": "[Opt In](https://raw.githubusercontent.com). The description of the custom field."
},
"custom_label": {
"type": "string",
"example": "gold pieces",
"nullable": true,
"description": "This is the string that appears next to the custom field value. This will be null if the `format` is not `custom`."
},
"enum_options": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnumOption"
},
"description": "*Conditional*. Only relevant for custom fields of type `enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](https://raw.githubusercontent.com)."
},
"currency_code": {
"type": "string",
"example": "EUR",
"nullable": true,
"description": "ISO 4217 currency code to format this custom field. This will be null if the `format` is not `currency`."
},
"asana_created_field": {
"enum": [
"a_v_requirements",
"account_name",
"actionable",
"align_shipping_link",
"align_status",
"allotted_time",
"appointment",
"approval_stage",
"approved",
"article_series",
"board_committee",
"browser",
"campaign_audience",
"campaign_project_status",
"campaign_regions",
"channel_primary",
"client_topic_type",
"complete_by",
"contact",
"contact_email_address",
"content_channels",
"content_channels_needed",
"content_stage",
"content_type",
"contract",
"contract_status",
"cost",
"creation_stage",
"creative_channel",
"creative_needed",
"creative_needs",
"data_sensitivity",
"deal_size",
"delivery_appt",
"delivery_appt_date",
"department",
"department_responsible",
"design_request_needed",
"design_request_type",
"discussion_category",
"do_this_task",
"editorial_content_status",
"editorial_content_tag",
"editorial_content_type",
"effort",
"effort_level",
"est_completion_date",
"estimated_time",
"estimated_value",
"expected_cost",
"external_steps_needed",
"favorite_idea",
"feedback_type",
"financial",
"funding_amount",
"grant_application_process",
"hiring_candidate_status",
"idea_status",
"ids_link",
"ids_patient_link",
"implementation_stage",
"insurance",
"interview_area",
"interview_question_score",
"itero_scan_link",
"job_s_applied_to",
"lab",
"launch_status",
"lead_status",
"localization_language",
"localization_market_team",
"localization_status",
"meeting_minutes",
"meeting_needed",
"minutes",
"mrr",
"must_localize",
"name_of_foundation",
"need_to_follow_up",
"next_appointment",
"next_steps_sales",
"num_people",
"number_of_user_reports",
"office_location",
"onboarding_activity",
"owner",
"participants_needed",
"patient_date_of_birth",
"patient_email",
"patient_phone",
"patient_status",
"phone_number",
"planning_category",
"point_of_contact",
"position",
"post_format",
"prescription",
"priority",
"priority_level",
"product",
"product_stage",
"progress",
"project_size",
"project_status",
"proposed_budget",
"publish_status",
"reason_for_scan",
"referral",
"request_type",
"research_status",
"responsible_department",
"responsible_team",
"risk_assessment_status",
"room_name",
"sales_counterpart",
"sentiment",
"shipping_link",
"social_channels",
"stage",
"status",
"status_design",
"status_of_initiative",
"system_setup",
"task_progress",
"team",
"team_marketing",
"team_responsible",
"time_it_takes_to_complete_tasks",
"timeframe",
"treatment_type",
"type_work_requests_it",
"use_agency",
"user_name",
"vendor_category",
"vendor_type",
"word_count",
null
],
"type": "string",
"example": "priority",
"nullable": true,
"readOnly": true,
"description": "*Conditional*. A unique identifier to associate this field with the template source of truth."
},
"custom_label_position": {
"enum": [
"prefix",
"suffix",
null
],
"type": "string",
"example": "suffix",
"nullable": true,
"description": "Only relevant for custom fields with `custom` format. This depicts where to place the custom label. This will be null if the `format` is not `custom`."
},
"is_global_to_workspace": {
"type": "boolean",
"example": true,
"readOnly": true,
"description": "This flag describes whether this custom field is available to every container in the workspace. Before project-specific custom fields, this field was always true."
},
"has_notifications_enabled": {
"type": "boolean",
"example": true,
"description": "*Conditional*. This flag describes whether a follower of a task with this field should receive inbox notifications from changes to this field."
}
}
}
]
}
CustomFieldCompact
{
"allOf": [
{
"$ref": "#/components/schemas/AsanaResource"
},
{
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "Status",
"description": "The name of the custom field."
},
"type": {
"enum": [
"text",
"enum",
"multi_enum",
"number",
"date",
"people"
],
"type": "string",
"readOnly": true,
"description": "*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.\n"
},
"enabled": {
"type": "boolean",
"example": true,
"readOnly": true,
"description": "*Conditional*. Determines if the custom field is enabled or not."
},
"id_prefix": {
"type": "string",
"example": "ID",
"nullable": true,
"description": "This field is the unique custom ID string for the custom field."
},
"date_value": {
"type": "object",
"nullable": true,
"properties": {
"date": {
"type": "string",
"example": "2024-08-23",
"description": "A string representing the date in YYYY-MM-DD format."
},
"date_time": {
"type": "string",
"example": "2024-08-23T22:00:00.000Z",
"description": "A string representing the date in ISO 8601 format. If no time value is selected, the value of `date-time` will be `null`."
}
},
"description": "*Conditional*. Only relevant for custom fields of type `date`. This object reflects the chosen date (and optionally, time) value of a `date` custom field. If no date is selected, the value of `date_value` will be `null`."
},
"enum_value": {
"allOf": [
{
"$ref": "#/components/schemas/EnumOption"
},
{
"type": "object",
"nullable": true,
"description": "*Conditional*. Only relevant for custom fields of type `enum`. This object is the chosen value of an `enum` custom field."
}
]
},
"text_value": {
"type": "string",
"example": "Some Value",
"nullable": true,
"description": "*Conditional*. This string is the value of a `text` custom field."
},
"enum_options": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnumOption"
},
"description": "*Conditional*. Only relevant for custom fields of type `enum`. This array specifies the possible values which an `enum` custom field can adopt. To modify the enum options, refer to [working with enum options](https://raw.githubusercontent.com)."
},
"number_value": {
"type": "number",
"example": 5.2,
"nullable": true,
"description": "*Conditional*. This number is the value of a `number` custom field."
},
"display_value": {
"type": "string",
"example": "blue",
"nullable": true,
"readOnly": true,
"description": "A string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types."
},
"is_formula_field": {
"type": "boolean",
"example": false,
"description": "*Conditional*. This flag describes whether a custom field is a formula custom field."
},
"resource_subtype": {
"enum": [
"text",
"enum",
"multi_enum",
"number",
"date",
"people"
],
"type": "string",
"example": "text",
"readOnly": true,
"description": "The type of the custom field. Must be one of the given values.\n"
},
"multi_enum_values": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnumOption"
},
"description": "*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field."
},
"representation_type": {
"enum": [
"text",
"enum",
"multi_enum",
"number",
"date",
"people",
"formula",
"custom_id"
],
"type": "string",
"example": "number",
"readOnly": true,
"description": "This field tells the type of the custom field."
}
},
"description": "Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [custom fields](https://raw.githubusercontent.com) developer documentation for more information about how custom fields relate to various resources in Asana.\n\nUsers in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-fields), which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code `403 Forbidden`.",
"x-docs-overrides": {
"properties.resource_type.example": "custom_field"
}
}
]
}
CustomFieldRequest
{
"allOf": [
{
"$ref": "#/components/schemas/CustomFieldBase"
},
{
"type": "object",
"required": [
"workspace"
],
"properties": {
"workspace": {
"type": "string",
"example": "1331",
"description": "*Create-Only* The workspace to create a custom field in."
},
"owned_by_app": {
"type": "boolean",
"description": "*Allow-listed*. Instructs the API that this Custom Field is app-owned. This parameter is allow-listed to specific apps at this point in time. For apps that are not allow-listed, providing this parameter will result in a `403 Forbidden`."
},
"people_value": {
"type": "array",
"items": {
"type": "string",
"description": "The GID of a user."
},
"example": [
"12345"
],
"description": "*Conditional*. Only relevant for custom fields of type `people`. This array of user GIDs reflects the users to be written to a `people` custom field. Note that *write* operations will replace existing users (if any) in the custom field with the users specified in this array."
}
}
}
]
}
CustomFieldResponse
{
"allOf": [
{
"$ref": "#/components/schemas/CustomFieldBase"
},
{
"type": "object",
"properties": {
"id_prefix": {
"type": "string",
"example": "ID",
"nullable": true,
"description": "This field is the unique custom ID string for the custom field."
},
"created_by": {
"allOf": [
{
"$ref": "#/components/schemas/UserCompact"
},
{
"nullable": true
}
]
},
"people_value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UserCompact"
},
"description": "*Conditional*. Only relevant for custom fields of type `people`. This array of [compact user](https://raw.githubusercontent.com) objects reflects the values of a `people` custom field."
},
"is_formula_field": {
"type": "boolean",
"example": false,
"description": "*Conditional*. This flag describes whether a custom field is a formula custom field."
},
"is_value_read_only": {
"type": "boolean",
"example": false,
"description": "*Conditional*. This flag describes whether a custom field is read only."
},
"representation_type": {
"enum": [
"text",
"enum",
"multi_enum",
"number",
"date",
"people",
"formula",
"custom_id"
],
"type": "string",
"example": "number",
"readOnly": true,
"description": "This field tells the type of the custom field."
}
}
}
]
}
CustomFieldSettingCompact
{
"allOf": [
{
"$ref": "#/components/schemas/AsanaResource"
},
{
"type": "object",
"description": "Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.",
"x-docs-overrides": {
"properties.resource_type.example": "custom_field_setting"
}
}
]
}
CustomFieldSettingResponse
{
"allOf": [
{
"$ref": "#/components/schemas/CustomFieldSettingCompact"
},
{
"type": "object",
"properties": {
"parent": {
"allOf": [
{
"$ref": "#/components/schemas/ProjectCompact"
},
{
"type": "object",
"readOnly": true,
"description": "The parent to which the custom field is applied. This can be a project or portfolio and indicates that the tasks or projects that the parent contains may be given custom field values for this custom field."
}
]
},
"project": {
"allOf": [
{
"$ref": "#/components/schemas/ProjectCompact"
},
{
"type": "object",
"readOnly": true,
"description": "*Deprecated: new integrations should prefer the `parent` field.* The id of the project that this custom field settings refers to."
}
]
},
"custom_field": {
"allOf": [
{
"$ref": "#/components/schemas/CustomFieldResponse"
},
{
"type": "object",
"readOnly": true,
"description": "The custom field that is applied to the `parent`."
}
]
},
"is_important": {
"type": "boolean",
"example": false,
"readOnly": true,
"description": "`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio."
}
}
}
]
}
CustomFieldSettingsGetPortfolioCustomFieldSettingsResponse
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomFieldSettingResponse"
}
},
"next_page": {
"$ref": "#/components/schemas/NextPage"
}
}
}
CustomFieldSettingsGetProjectCustomFieldSettingsResponse
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomFieldSettingResponse"
}
},
"next_page": {
"$ref": "#/components/schemas/NextPage"
}
}
}
CustomFieldsAddEnumOptionRequest
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/EnumOptionRequest"
}
}
}
CustomFieldsAddEnumOptionResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/EnumOption"
}
}
}
CustomFieldsCreateNewFieldRecordRequest
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/CustomFieldRequest"
}
}
}
CustomFieldsCreateNewFieldRecordResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/CustomFieldResponse"
}
}
}
CustomFieldsDeleteFieldRecordResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/EmptyResponse"
}
}
}
CustomFieldsGetMetadataResponse
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/CustomFieldResponse"
}
}
}
CustomFieldsListWorkspaceCustomFieldsResponse
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomFieldResponse"
}
},
"next_page": {
"$ref": "#/components/schemas/NextPage"
}
}
}
| Version | Endpoints | Schemas | Ingested | Status |
|---|---|---|---|---|
| 1.0 | 189 | 435 | 2026-05-11 | current |
| 1.0 | 189 | 435 | 2026-04-16 |