Asana

Work management and project tracking

developers.asana.com/docs ↗

Version

1.0

OpenAPI

3.0.0

Endpoints

189

Schemas

435

80

Quality

Updated

3 days ago

Productivity productivity project-management tasks

Use this API in your AI agent

Query structured spec data via REST or MCP. Get exactly what your agent needs.

Get API Key

Server URLs

https://app.asana.com/api/1.0

Endpoints

Clear filters

GET POST PUT PATCH DELETE

Allocations 1 endpoints

PUT /allocations/{allocation_gid} Update an allocation

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.

operationId: Allocations_updateRecordById

Parameters

Name	In	Required	Type	Description
allocation_gid	path	optional	string	Globally unique identifier for the allocation.
opt_pretty	query	optional	boolean	Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

required

The updated fields for the allocation.

application/json

schema 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

Responses

200

Successfully updated the allocation.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

The authentication and request syntax was valid but the server is refusing to complete the request. This can happen if you try to read or write to objects or properties that the user does not have access to.

404

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.

500

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}

Customfields 2 endpoints

PUT /custom_fields/{custom_field_gid} Update a custom field

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

operationId: CustomFields_updateFieldRecord

Parameters

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. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

The custom field object with all updated properties.

application/json

schema 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

Responses

200

The custom field was successfully updated.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /custom_fields/{custom_field_gid}

PUT /enum_options/{enum_option_gid} Update an enum option

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.

operationId: CustomFields_updateEnumOption

Parameters

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. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

The enum option object to update

application/json

schema CustomFieldsUpdateEnumOptionRequest

Property	Type	Required
data	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ name	string	optional
└ color	string	optional
└ enabled	boolean	optional

Responses

200

Successfully updated the specified custom field enum.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /enum_options/{enum_option_gid}

Goalrelationships 1 endpoints

PUT /goal_relationships/{goal_relationship_gid} Update a goal relationship

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

Returns the complete updated goal relationship record.

operationId: GoalRelationships_updateGoalRelationshipRecord

Parameters

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. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

required

The updated fields for the goal relationship.

application/json

schema 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

Responses

200

Successfully updated the goal relationship.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /goal_relationships/{goal_relationship_gid}

Goals 1 endpoints

PUT /goals/{goal_gid} Update a goal

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

Returns the complete updated goal record.

operationId: Goals_updateGoalRecord

Parameters

Name	In	Required	Type	Description
goal_gid	path	optional	string	Globally unique identifier for the goal.
opt_pretty	query	optional	boolean	Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

required

The updated fields for the goal.

application/json

schema 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

Responses

200

Successfully updated the goal.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /goals/{goal_gid}

Memberships 1 endpoints

PUT /memberships/{membership_gid} Update a membership

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

Returns the full record of the updated membership.

operationId: Memberships_updateMembershipRecord

Parameters

Name	In	Required	Type	Description
membership_gid	path	optional	string	Globally unique identifier for the membership.
opt_pretty	query	optional	boolean	Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.

Request Body

required

The membership to update.

application/json

schema MembershipsUpdateMembershipRecordRequest

Property	Type	Required
data	object	optional
└ access_level	string	optional

Responses

200

Successfully updated the requested membership.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /memberships/{membership_gid}

Portfolios 1 endpoints

PUT /portfolios/{portfolio_gid} Update a portfolio

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

Returns the complete updated portfolio record.

operationId: Portfolios_updatePortfolioRecord

Parameters

Name	In	Required	Type	Description
portfolio_gid	path	optional	string	Globally unique identifier for the portfolio.
opt_pretty	query	optional	boolean	Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

required

The updated fields for the portfolio.

application/json

schema PortfoliosUpdatePortfolioRecordRequest

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

Responses

200

Successfully updated the portfolio.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /portfolios/{portfolio_gid}

Projectbriefs 1 endpoints

PUT /project_briefs/{project_brief_gid} Update a project brief

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

Returns the complete updated project brief record.

operationId: ProjectBriefs_updateBriefRecord

Parameters

Name	In	Required	Type	Description
project_brief_gid	path	optional	string	Globally unique identifier for the project brief.
opt_pretty	query	optional	boolean	Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

required

The updated fields for the project brief.

application/json

schema ProjectBriefsUpdateBriefRecordRequest

Property	Type	Required
data	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ title	string	optional
└ html_text	string	optional
└ text	string	optional

Responses

200

Successfully updated the project brief.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /project_briefs/{project_brief_gid}

Projects 1 endpoints

PUT /projects/{project_gid} Update a project

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

When using this method, it is best to specify only those fields you wish
to change, or else you may overwrite changes made by another user since
you last retrieved the task.

Returns the complete updated project record.

operationId: Projects_updateProjectRecord

Parameters

Name	In	Required	Type	Description
project_gid	path	optional	string	Globally unique identifier for the project.
opt_pretty	query	optional	boolean	Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

required

The updated fields for the project.

application/json

schema ProjectsUpdateProjectRecordRequest

Property	Type	Required
data	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ name	string	optional
└ color	string	optional
└ notes	string	optional
└ due_on	string	optional
└ public	boolean	optional
└ members	array	optional
└ gid	string	optional
└ resource_type	string	optional
└ name	string	optional
└ archived	boolean	optional
└ due_date	string	optional
└ start_on	string	optional
└ created_at	string	optional
└ html_notes	string	optional
└ modified_at	string	optional
└ default_view	string	optional
└ current_status	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ title	string	optional
└ text	string	optional
└ color	string	optional
└ html_text	string	optional
└ author	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ name	string	optional
└ created_at	string	optional
└ created_by	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ name	string	optional
└ modified_at	string	optional
└ privacy_setting	string	optional
└ default_access_level	string	optional
└ current_status_update	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ title	string	optional
└ resource_subtype	string	optional
└ custom_field_settings	array	optional
└ gid	string	optional
└ resource_type	string	optional
└ parent	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ name	string	optional
└ project	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ name	string	optional
└ custom_field	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
└ enum_value	object	optional
└ text_value	string	optional
└ enum_options	array	optional
└ number_value	number	optional
└ display_value	string	optional
└ is_formula_field	boolean	optional
└ resource_subtype	string	optional
└ multi_enum_values	array	optional
└ representation_type	string	optional
└ format	string	optional
└ precision	integer	optional
└ description	string	optional
└ custom_label	string	optional
└ …8 more	object	optional
└ is_important	boolean	optional
└ …6 more	object	optional

Responses

200

Successfully updated the project.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /projects/{project_gid}

Sections 1 endpoints

PUT /sections/{section_gid} Update a section

A specific, existing section can be updated by making a PUT request on
the URL for that project. Only the fields provided in the data block
will be updated; any unspecified fields will remain unchanged. (note that
at this time, the only field that can be updated is the name field.)

When using this method, it is best to specify only those fields you wish
to change, or else you may overwrite changes made by another user since
you last retrieved the task.

Returns the complete updated section record.

operationId: Sections_updateSectionRecord

Parameters

Name	In	Required	Type	Description
section_gid	path	optional	string	The globally unique identifier for the section.
opt_pretty	query	optional	boolean	Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

The section to create.

application/json

schema SectionsUpdateSectionRecordRequest

Property	Type	Required
data	object	optional
└ name	string	required
└ insert_after	string	optional
└ insert_before	string	optional

Responses

200

Successfully updated the specified section.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /sections/{section_gid}

Stories 1 endpoints

PUT /stories/{story_gid} Update a story

Updates the story and returns the full record for the updated story. Only comment stories can have their text updated, and only comment stories and attachment stories can be pinned. Only one of text and html_text can be specified.

operationId: Stories_updateFullRecord

Parameters

Name	In	Required	Type	Description
story_gid	path	optional	string	Globally unique identifier for the story.
opt_pretty	query	optional	boolean	Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

required

The comment story to update.

application/json

schema StoriesUpdateFullRecordRequest

Property	Type	Required
data	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ text	string	optional
└ html_text	string	optional
└ is_pinned	boolean	optional
└ created_at	string	optional
└ sticker_name	string	optional
└ resource_subtype	string	optional

Responses

200

Successfully retrieved the specified story.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /stories/{story_gid}

Tags 1 endpoints

PUT /tags/{tag_gid} Update a tag

Updates the properties of a tag. Only the fields provided in the data
block will be updated; any unspecified fields will remain unchanged.

When using this method, it is best to specify only those fields you wish
to change, or else you may overwrite changes made by another user since
you last retrieved the tag.

Returns the complete updated tag record.

operationId: Tags_updateTagRecord

Parameters

Name	In	Required	Type	Description
tag_gid	path	optional	string	Globally unique identifier for the tag.
opt_pretty	query	optional	boolean	Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Responses

200

Successfully updated the specified tag.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /tags/{tag_gid}

Tasks 1 endpoints

PUT /tasks/{task_gid} Update a task

A specific, existing task can be updated by making a PUT request on the
URL for that task. Only the fields provided in the data block will be
updated; any unspecified fields will remain unchanged.

When using this method, it is best to specify only those fields you wish
to change, or else you may overwrite changes made by another user since
you last retrieved the task.

Returns the complete updated task record.

operationId: Tasks_updateTaskRecord

Parameters

Name	In	Required	Type	Description
task_gid	path	optional	string	The task to operate on.
opt_pretty	query	optional	boolean	Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

required

The task to update.

application/json

schema TasksUpdateTaskRecordRequest

Property	Type	Required
data	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ name	string	optional
└ created_by	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ resource_subtype	string	optional
└ liked	boolean	optional
└ likes	array	optional
└ gid	string	optional
└ user	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ name	string	optional
└ notes	string	optional
└ due_at	string	optional
└ due_on	string	optional
└ hearts	array	optional
└ gid	string	optional
└ user	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ name	string	optional
└ hearted	boolean	optional
└ external	object	optional
└ gid	string	optional
└ data	string	optional
└ start_at	string	optional
└ start_on	string	optional
└ completed	boolean	optional
└ num_likes	integer	optional
└ created_at	string	optional
└ dependents	array	optional
└ gid	string	optional
└ resource_type	string	optional
└ html_notes	string	optional
└ …19 more	object	optional

Responses

200

Successfully updated the specified task.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /tasks/{task_gid}

Teams 1 endpoints

PUT /teams/{team_gid} Update a team

Updates a team within the current workspace.

operationId: Teams_updateTeamRecord

Parameters

Name	In	Required	Type	Description
team_gid	path	optional	string	Globally unique identifier for the team.
opt_pretty	query	optional	boolean	Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

required

The team to update.

application/json

schema TeamsUpdateTeamRecordRequest

Property	Type	Required
data	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ name	string	optional
└ visibility	string	optional
└ description	string	optional
└ organization	string	optional
└ html_description	string	optional
└ team_member_removal_access_level	string	optional
└ guest_invite_management_access_level	string	optional
└ join_request_management_access_level	string	optional
└ member_invite_management_access_level	string	optional
└ edit_team_name_or_description_access_level	string	optional
└ edit_team_visibility_or_trash_team_access_level	string	optional

Responses

200

Successfully updated the team.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /teams/{team_gid}

Timetrackingentries 1 endpoints

PUT /time_tracking_entries/{time_tracking_entry_gid} Update a time tracking entry

A specific, existing time tracking entry can be updated by making a PUT request on
the URL for that time tracking entry. Only the fields provided in the data block
will be updated; any unspecified fields will remain unchanged.

When using this method, it is best to specify only those fields you wish
to change, or else you may overwrite changes made by another user since
you last retrieved the task.

Returns the complete updated time tracking entry record.

operationId: TimeTrackingEntries_updateTimeTrackingEntry

Parameters

Name	In	Required	Type	Description
time_tracking_entry_gid	path	optional	string	Globally unique identifier for the time tracking entry.
opt_pretty	query	optional	boolean	Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

required

The updated fields for the time tracking entry.

application/json

schema TimeTrackingEntriesUpdateTimeTrackingEntryRequest

Property	Type	Required
data	object	optional
└ entered_on	string	optional
└ duration_minutes	integer	optional

Responses

200

Successfully updated the time tracking entry.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /time_tracking_entries/{time_tracking_entry_gid}

Webhooks 1 endpoints

PUT /webhooks/{webhook_gid} Update a webhook

An existing webhook’s filters can be updated by making a PUT request on the URL for that webhook. Note that the webhook’s previous filters array will be completely overwritten by the filters sent in the PUT request.

operationId: Webhooks_updateWebhookFilters

Parameters

Name	In	Required	Type	Description
webhook_gid	path	optional	string	Globally unique identifier for the webhook.
opt_pretty	query	optional	boolean	Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

required

The updated filters for the webhook.

application/json

schema WebhooksUpdateWebhookFiltersRequest

Property	Type	Required
data	object	optional
└ filters	array	optional
└ action	string	optional
└ fields	array	optional
└ resource_type	string	optional
└ resource_subtype	string	optional

Responses

200

Successfully updated the webhook.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /webhooks/{webhook_gid}

Workspaces 1 endpoints

PUT /workspaces/{workspace_gid} Update a workspace

A specific, existing workspace can be updated by making a PUT request on the URL for that workspace. Only the fields provided in the data block will be updated; any unspecified fields will remain unchanged.
Currently the only field that can be modified for a workspace is its name.
Returns the complete, updated workspace record.

operationId: Workspaces_updateWorkspaceRecord

Parameters

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. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging.
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.

Request Body

required

The workspace object with all updated properties.

application/json

schema WorkspacesUpdateWorkspaceRecordRequest

Property	Type	Required
data	object	optional
└ gid	string	optional
└ resource_type	string	optional
└ name	string	optional

Responses

200

Update for the workspace was successful.

400

This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.

401

A valid authentication token was not provided with the request, so the API could not associate a user with the request.

403

404

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.

500

PUT /workspaces/{workspace_gid}

Load more endpoints

Schemas

object 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."
    }
  }
}

object 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."
    }
  }
}

object 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."
    }
  }
}

object 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"
      }
    }
  ]
}

object 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."
        }
      }
    }
  ]
}

object 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."
        }
      }
    }
  ]
}

object AllocationsCreateRecordRequest

{
  "type": "object",
  "properties": {
    "data": {
      "allOf": [
        {
          "$ref": "#/components/schemas/AllocationRequest"
        },
        {
          "type": "object",
          "required": [
            "assignee",
            "end_date",
            "parent",
            "start_date"
          ]
        }
      ]
    }
  }
}

object AllocationsCreateRecordResponse

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/AllocationResponse"
    }
  }
}

object AllocationsDeleteAllocationByIdResponse

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/EmptyResponse"
    }
  }
}

object AllocationsGetMultipleResponse

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AllocationResponse"
      }
    },
    "next_page": {
      "$ref": "#/components/schemas/NextPage"
    }
  }
}

object AllocationsGetRecordByIdResponse

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/AllocationResponse"
    }
  }
}

object AllocationsUpdateRecordByIdRequest

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/AllocationRequest"
    }
  }
}

object AllocationsUpdateRecordByIdResponse

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/AllocationResponse"
    }
  }
}

object AsanaNamedResource

{
  "allOf": [
    {
      "$ref": "#/components/schemas/AsanaResource"
    },
    {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "example": "Bug Task",
          "description": "The name of the object."
        }
      }
    }
  ]
}

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."
}

object 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"
      }
    }
  ]
}

object 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"
    }
  }
}

object 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`."
        }
      }
    }
  ]
}

object AttachmentsDeleteSpecificResponse

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/EmptyResponse"
    }
  }
}

object AttachmentsGetAllForObjectResponse

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AttachmentCompact"
      }
    },
    "next_page": {
      "$ref": "#/components/schemas/NextPage"
    }
  }
}

object AttachmentsGetAttachmentRecordResponse

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/AttachmentResponse"
    }
  }
}

object AttachmentsUploadAttachmentResponse

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/AttachmentResponse"
    }
  }
}

object AuditLogApiGetAuditLogEventsResponse

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AuditLogEvent"
      }
    },
    "next_page": {
      "$ref": "#/components/schemas/NextPage"
    }
  }
}

object 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."
}

object 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."
}

object 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."
}

object 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
}

object 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."
}

object BatchApiSubmitParallelRequestsRequest

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/BatchRequest"
    }
  }
}

object BatchApiSubmitParallelRequestsResponse

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/BatchResponse"
      }
    }
  }
}

object BatchRequest

{
  "type": "object",
  "properties": {
    "actions": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/BatchRequestAction"
      }
    }
  },
  "description": "A request object for use in a batch request."
}

object 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."
}

object 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."
}

object 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."
        }
      }
    }
  ]
}

object 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"
    }
  }
}

object 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."
        }
      }
    }
  ]
}

object 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"
      }
    }
  ]
}

object 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."
        }
      }
    }
  ]
}

object 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."
        }
      }
    }
  ]
}

object 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"
      }
    }
  ]
}

object 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."
        }
      }
    }
  ]
}

object CustomFieldSettingsGetPortfolioCustomFieldSettingsResponse

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CustomFieldSettingResponse"
      }
    },
    "next_page": {
      "$ref": "#/components/schemas/NextPage"
    }
  }
}

object CustomFieldSettingsGetProjectCustomFieldSettingsResponse

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CustomFieldSettingResponse"
      }
    },
    "next_page": {
      "$ref": "#/components/schemas/NextPage"
    }
  }
}

object CustomFieldsAddEnumOptionRequest

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/EnumOptionRequest"
    }
  }
}

object CustomFieldsAddEnumOptionResponse

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/EnumOption"
    }
  }
}

object CustomFieldsCreateNewFieldRecordRequest

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/CustomFieldRequest"
    }
  }
}

object CustomFieldsCreateNewFieldRecordResponse

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/CustomFieldResponse"
    }
  }
}

object CustomFieldsDeleteFieldRecordResponse

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/EmptyResponse"
    }
  }
}

object CustomFieldsGetMetadataResponse

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/CustomFieldResponse"
    }
  }
}

object CustomFieldsListWorkspaceCustomFieldsResponse

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CustomFieldResponse"
      }
    },
    "next_page": {
      "$ref": "#/components/schemas/NextPage"
    }
  }
}

Load more schemas

Versions

Version	Endpoints	Schemas	Ingested	Status
1.0	189	435	2026-05-11	current
1.0	189	435	2026-04-16