Upload an attachment

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\""
Query Params
array of strings

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.

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

Body Params

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

string

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.

file

Required for asana attachments.

string
required

Required identifier of the parent task, project, or project_brief, as a string.

string

The URL of the external resource being attached. Required for attachments of type external.

string

The name of the external resource being attached. Required for attachments of type external.

boolean

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.

Responses

Response body
object
object

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.

string

Globally unique identifier of the resource, as a string.

string

The base type of this resource.

string

The name of the file.

string

The service hosting the attachment. Valid values are asana, dropbox, gdrive, onedrive, box, vimeo, and external.

date-time

The time at which this resource was created.

uri | null

The URL containing the content of the attachment.
Note: May be null if the attachment is hosted by Box and will be null if the attachment is a Video Message hosted by Vimeo. 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.

uri | null
string

The service hosting the attachment. Valid values are asana, dropbox, gdrive, box, and vimeo.

object | null

The task this attachment is attached to.

integer

The size of the attachment in bytes. Only present when the resource_subtype is asana.

uri | null

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.

boolean

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.

Language
Credentials
OAuth2
Request
Asana Home
Asana helps you manage projects, focus on what's important, and organize work in one place for seamless collaboration.
© 2023 Asana, Inc.