Sample - Asana API
POST/attachments

Upload an attachment

Required scope: attachments:write

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 in order for the server to reliably and properly handle the request.

For file names that contain non-ASCII characters, the file name should be URL-encoded. For example, a file named résumé.pdf should be encoded as r%C3%A9sum%C3%A9.pdf and the filename parameter in the Content-Disposition header should be set to the encoded file name.

Below is an example of a cURL request with the Content-Disposition header:

export ASANA_PAT="<YOUR_ASANA_PERSONAL_ACCESS_TOKEN>"
export PARENT_ID="<PARENT_GID>"
export ENCODED_NAME="r%C3%A9sum%C3%A9.pdf"
curl --location 'https://app.asana.com/api/1.0/attachments' \
  --header 'Content-Type: multipart/form-data' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $ASANA_PAT" \
  --form "parent=$PARENT_ID" \
  --form "file=@/Users/exampleUser/Downloads/résumé.pdf;headers=\"Content-Disposition: form-data; name="file"; filename="$ENCODED_NAME.pdf"; filename*=UTF-8''$ENCODED_NAME.pdf\""
  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

1 parameter · 6 body fields
opt_fieldsarray<string>optional
This endpoint returns a 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. Properties can include nested fields. To learn more, see the [input/output options guide](/docs/inputoutput-options#selecting-nested-fields).

The file you want to upload.

Note when using curl:

Be sure to add an ‘@’ before the file path, and use the --form option instead of the -d option.

When uploading PDFs with curl, force the content-type to be pdf by appending the content type to the file path: --form "file=@file.pdf;type=application/pdf".

resource_subtypestringoptional
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.
Allowed:asanaexternal
filestringoptional
Required for `asana` attachments.
parentstringrequired
Required identifier of the parent task, project, or project_brief, as a string.
urlstringoptional
The URL of the external resource being attached. Required for attachments of type `external`.
namestringoptional
The name of the external resource being attached. Required for attachments of type `external`.
connect_to_appbooleanoptional
*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. This property can only be set if an OAuth token is used to authenticate the request. Criteria for displaying app widget: 1. An OAuth token must be used to authenticate the request 2. The app needs to have its `widget_metadata_url` configured in the developer console 3. The task the attachment is being attached to must be in a project with the app installed

6 status codes
200Successfully uploaded the attachment to the parent object.
dataobjectoptional
400This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
errorsarray<object>optional
401A valid authentication token was not provided with the request, so the API could not associate a user with the request.
errorsarray<object>optional
403The 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.
errorsarray<object>optional
404Either 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.
errorsarray<object>optional
500There 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.
errorsarray<object>optional

Error handling

A 400 is returned: This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again. A 401 is returned: A valid authentication token was not provided with the request, so the API could not associate a user with the request. A 403 is returned: 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. A 404 is returned: 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. A 500 is returned: 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.