Asana

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

Add a custom field to a project Custom fields are associated with projects by way of custom field settings. This method creates a setting for the project.

Set dependencies for a task Marks a set of tasks as dependencies of this task, if they are not already dependencies. *A task can have at most 30 dependents and dependencies combined*.

Set dependents for a task Marks a set of tasks as dependents of this task, if they are not already dependents. *A task can have at most 30 dependents and dependencies combined*.

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

Add followers to a project Adds the specified list of users as followers to the project. Followers are a subset of members who have opted in to receive "tasks added" notifications for a project. Therefore, if the users are not already members of the project, they will also become members as a result of this operation. Returns the updated project record.

Add followers to a task Adds followers to a task. Returns an empty data block. Each task can be associated with zero or more followers in the system. Requests to add/remove followers, if successful, will return the complete updated task record, described above.

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

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

Add users to a project Adds the specified list of users as members of the project. Note that a user being added as a member may also be added as a *follower* as a result of this operation. This is because the user's default notification settings (i.e., in the "Notifcations" tab of "My Profile Settings") will override this endpoint's default behavior of setting "Tasks added" notifications to `false`. Returns the updated project record.

Add a project to a task Adds the task to the specified project, in the optional location specified. If no location arguments are given, the task will be added to the end of the project. `addProject` can also be used to reorder a task within a project or section that already contains it. At most one of `insert_before`, `insert_after`, or `section` should be specified. Inserting into a section in an non-order-dependent way can be done by specifying section, otherwise, to insert within a section in a particular place, specify `insert_before` or `insert_after` and a task within the section to anchor the position of this task. Returns an empty data block.

Add a supporting goal relationship Creates a goal relationship by adding a supporting resource to a given goal. Returns the newly created goal relationship record.

Add a tag to a task Adds a tag to a task. Returns an empty data block.

Add task to section Add a task to a specific, existing section. This will remove the task from other sections of the project. The task will be inserted at the top of a section unless an insert_before or insert_after parameter is declared. This does not work for separators (tasks with the resource_subtype of section).

Add a user to a team The user making this call must be a member of the team in order to add others. The user being added must exist in the same organization as the team. Returns the complete team membership record for the newly added user.

Add a user to a workspace or organization. The user can be referenced by their globally unique user ID or their email address. Returns the full user record for the invited user.

Upload an attachment. This method uploads an attachment on an object and returns the compact record for the created attachment object. This is possible by either: - Providing the URL of the external resource being attached, or - Downloading the file content first and then uploading it as any other attachment. Note that it is not possible to attach files from third party services such as Dropbox, Box, Vimeo & Google Drive via the API The 100MB size limit on attachments in Asana is enforced on this endpoint. This endpoint expects a multipart/form-data encoded request containing the full contents of the file to be uploaded. Requests made should follow the HTTP/1.1 specification that line terminators are of the form `CRLF` or `\r\n` outlined [here](http://www.w3.org/Protocols/HTTP/1.1/draft-ietf-http-v11-spec-01#Basic-Rules) in order for the server to reliably and properly handle the request.

Submit parallel requests Make multiple requests in parallel to Asana's API.

Create a custom field Creates a new custom field in a workspace. Every custom field is required to be created in a specific workspace, and this workspace cannot be changed once set. A custom field’s name must be unique within a workspace and not conflict with names of existing task properties such as `Due Date` or `Assignee`. A custom field’s type must be one of `text`, `enum`, `multi_enum`, `number`, `date`, or `people`. Returns the full record of the newly created custom field.

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

Create a goal Creates a new goal in a workspace or team. Returns the full record of the newly created goal.

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

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

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

Create a project Create a new project in a workspace or team. Every project is required to be created in a specific workspace or organization, and this cannot be changed once set. Note that you can use the `workspace` parameter regardless of whether or not it is an organization. If the workspace for your project is an organization, you must also supply a `team` to share the project with. Returns the full record of the newly created project.

Create a project brief Creates a new project brief. Returns the full record of the newly created project brief.

Create a project in a team Creates a project shared with the given team. Returns the full record of the newly created project.

Create a project in a workspace Returns the compact project records for all projects in the workspace. If the workspace for your project is an organization, you must also supply a team to share the project with. Returns the full record of the newly created project.

Create a project status *Deprecated: new integrations should prefer the `/status_updates` route.* Creates a new status update on the project. Returns the full record of the newly created project status update.

Create a section in a project Creates a new section in a project. Returns the full record of the newly created section.

Create a status update Creates a new status update on an object. Returns the full record of the newly created status update.

Create a story on a task Adds a story to a task. This endpoint currently only allows for comment stories to be created. The comment will be authored by the currently authenticated user, and timestamped when the server receives the request. Returns the full record for the new story added to the task.

Create a subtask Creates a new subtask and adds it to the parent task. Returns the full record for the newly created subtask.

Create a tag Creates a new tag in a workspace or organization. Every tag is required to be created in a specific workspace or organization, and this cannot be changed once set. Note that you can use the workspace parameter regardless of whether or not it is an organization. Returns the full record of the newly created tag.

Create a tag in a workspace Creates a new tag in a workspace or organization. Every tag is required to be created in a specific workspace or organization, and this cannot be changed once set. Note that you can use the workspace parameter regardless of whether or not it is an organization. Returns the full record of the newly created tag.

Create a task Creating a new task is as easy as POSTing to the `/tasks` endpoint with a data block containing the fields you’d like to set on the task. Any unspecified fields will take on default values. Every task is required to be created in a specific workspace, and this workspace cannot be changed once set. The workspace need not be set explicitly if you specify `projects` or a `parent` task instead.

Create a team Creates a team within the current workspace.

Establish a webhook Establishing a webhook is a two-part process. First, a simple HTTP POST request initiates the creation similar to creating any other resource. Next, in the middle of this request comes the confirmation handshake. When a webhook is created, we will send a test POST to the target with an `X-Hook-Secret` header. The target must respond with a `200 OK` or `204 No Content` and a matching `X-Hook-Secret` header to confirm that this webhook subscription is indeed expected. We strongly recommend storing this secret to be used to verify future webhook event signatures. The POST request to create the webhook will then return with the status of the request. If you do not acknowledge the webhook’s confirmation handshake it will fail to setup, and you will receive an error in response to your attempt to create it. This means you need to be able to receive and complete the webhook *while* the POST request is in-flight (in other words, have a server that can handle requests asynchronously). Invalid hostnames like localhost will recieve a 403 Forbidden status code. ``` # Request curl -H "Authorization: Bearer " \ -X POST https://app.asana.com/api/1.0/webhooks \ -d "resource=8675309" \ -d "target=https://example.com/receive-webhook/7654" ``` ``` # Handshake sent to https://example.com/ POST /receive-webhook/7654 X-Hook-Secret: b537207f20cbfa02357cf448134da559e8bd39d61597dcd5631b8012eae53e81 ``` ``` # Handshake response sent by example.com HTTP/1.1 200 X-Hook-Secret: b537207f20cbfa02357cf448134da559e8bd39d61597dcd5631b8012eae53e81 ``` ``` # Response HTTP/1.1 201 { "data": { "gid": "43214", "resource": { "gid": "8675309", "name": "Bugs" }, "target": "https://example.com/receive-webhook/7654", "active": false, "last_success_at": null, "last_failure_at": null, "last_failure_content": null } } ```

Delete an attachment Deletes a specific, existing attachment. Returns an empty data record.

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

Delete a goal A specific, existing goal can be deleted by making a DELETE request on the URL for that goal. Returns an empty data record.

Delete a portfolio An existing portfolio can be deleted by making a DELETE request on the URL for that portfolio. Returns an empty data record.

Delete a project A specific, existing project can be deleted by making a DELETE request on the URL for that project. Returns an empty data record.

Delete a project brief Deletes a specific, existing project brief. Returns an empty data record.

Delete a project status *Deprecated: new integrations should prefer the `/status_updates/{status_gid}` route.* Deletes a specific, existing project status update. Returns an empty data record.

Delete a section A specific, existing section can be deleted by making a DELETE request on the URL for that section. Note that sections must be empty to be deleted. The last remaining section cannot be deleted. Returns an empty data block.

Delete a status update Deletes a specific, existing status update. Returns an empty data record.

Delete a story Deletes a story. A user can only delete stories they have created. Returns an empty data record.

Delete a tag A specific, existing tag can be deleted by making a DELETE request on the URL for that tag. Returns an empty data record.

Delete a task A specific, existing task can be deleted by making a DELETE request on the URL for that task. Deleted tasks go into the “trash” of the user making the delete request. Tasks can be recovered from the trash within a period of 30 days; afterward they are completely removed from the system. Returns an empty data record.