Uploads

The Upload API, available at upload.contentful.com (or upload.eu.contentful.com for EU data residency customers), provides Contentful SDKs with a direct file upload service. You can upload any binary data (including images, videos and text files) and associate the uploaded files with different Assets within a Space.

The Upload API enables the uploading of files to remote storage. To complete an upload, the uploaded file must be associated with an Asset and that asset must be processed. If the association and processing steps are not executed successfully within 24 hours after uploading, the file and its metadata will expire and be deleted from the storage area. The expiration date of the file is indicated in the API response data as expiresAt.

You can associate an Upload resource with more than one Asset and/or locale

Uploading a file

To upload a file, you send a POST request to the create upload endpoint with the binary data in the request body, and include Content-Type: application/octet-stream in the request headers. Depending on the size of your file, a success response may take some time to return. Once the upload finishes, you will receive an Upload resource in the response body.

Associating an upload with an asset

When the upload request is successful you will receive an Upload resource containing an upload_id within the sys.id field that references the uploaded file. You need to use the upload_id to associate the Upload resource with an Asset.

To associate an Upload resource with an Asset, you need to pass upload_id to the asset creation end point of the CMA with the following structure:

1
{
2
  "fields": {
3
      "title": {
4
          "en-US": "My cute cat pic"
5
      },
6
      "file": {
7
          "en-US": {
8
              "contentType": "image/png",
9
              "fileName": "cute_cat.png",
10
              "uploadFrom": {
11
                  "sys": {
12
                    "type": "Link",
13
                    "linkType": "Upload",
14
                    "id": "<use sys.id of an upload resource response here>"
15
                  }
16
              }
17
          }
18
      }
19
  }
20
}

Maximum file size

The maximum file size should not exceed 1000MB per uploaded asset. See our Fair Usage Policy for more information. If you try to upload a larger file you will receive a Request Timeout error from the API.

Resumability

The current version of the Upload API doesn’t support resumability. If you encounter an error during the upload process, you need to begin the process from the beginning. It’s the client’s responsibility to take recovery actions in case of an error.

Upload resource

The JSON structure for an Upload has the following structure:

1
"sys": {
2
    "id": "73DfxdBnwyhQNy95A8dvSf",
3
    "type": "Upload",
4
    "createdAt": "2017-02-21T07:49:25.000Z",
5
    "expiresAt": "2017-02-23T00:00:00.000Z",
6
    "space": {
7
        "sys": {
8
            "type": "Link",
9
            "linkType": "Space",
10
            "id": "qa65bkvd5q1q"
11
        }
12
    },
13
    "createdBy": {
14
        "sys": {
15
            "type": "Link",
16
            "linkType": "User",
17
            "id": "1QaAgxMYKvdas32K4v319F"
18
        }
19
    }
20
}

Upload a file

Uploads a file to temporary file storage. Include the binary data you want to send in the request body, and Content-Type: application/octet-stream in the headers.

Creating an upload resource

Retrieving an upload

Retrieves an unmodified image. This is the same URL from an asset’s file.url field, containing the token ids and image name.

Retrieve an upload

Deleting an upload

Deletes a file from temporary data storage and all the metadata associated with the given upload_id.

By default, all uploaded files are automatically deleted after 24 hours starting from when first upload request is issued.

Delete an upload