> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server.

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 `Asset`s 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](/references/content-management-api/assets#asset-processing). 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](#upload-a-file) 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](/references/content-management-api/assets) with the following structure:

```json
{
  "fields": {
      "title": {
          "en-US": "My cute cat pic"
      },
      "file": {
          "en-US": {
              "contentType": "image/png",
              "fileName": "cute_cat.png",
              "uploadFrom": {
                  "sys": {
                    "type": "Link",
                    "linkType": "Upload",
                    "id": "<use sys.id of an upload resource response here>"
                  }
              }
          }
      }
  }
}
```

## Maximum file size

The maximum file size should not exceed 1000MB per uploaded asset. See our [Fair Usage Policy](https://www.contentful.com/r/knowledgebase/fair-use/) 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:

```json
"sys": {
    "id": "73DfxdBnwyhQNy95A8dvSf",
    "type": "Upload",
    "createdAt": "2017-02-21T07:49:25.000Z",
    "expiresAt": "2017-02-23T00:00:00.000Z",
    "space": {
        "sys": {
            "type": "Link",
            "linkType": "Space",
            "id": "qa65bkvd5q1q"
        }
    },
    "createdBy": {
        "sys": {
            "type": "Link",
            "linkType": "User",
            "id": "1QaAgxMYKvdas32K4v319F"
        }
    }
}
```

## Upload a file

> **Info**
>
> The API base URL for this action is `https://upload.contentful.com` or `https://upload.eu.contentful.com` for EU data residency customers.

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](/references/content-management-api/uploads/create-an-upload-resource)

## Retrieving an upload

> **Info**
>
> The API base URL for this action is `https://upload.contentful.com` or `https://upload.eu.contentful.com` for EU data residency customers.

Retrieves an unmodified image. This is the same URL from an [asset's](#reference/assets) `file.url` field, containing the token ids and image name.

[Retrieve an upload](/references/content-management-api/uploads/retrieve-an-upload)

## Deleting an upload

> **Info**
>
> The API base URL for this action is `https://upload.contentful.com` or `https://upload.eu.contentful.com` for EU data residency customers.

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

> **Info**
>
> This action can not be undone.

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

[Delete an upload](/references/content-management-api/uploads/delete-an-upload)


## API Docs

- Uploads [Create an upload resource](https://contentful.com/developers/docs/references/content-management-api/uploads/create-an-upload-resource.md)
- Uploads [Retrieve an upload](https://contentful.com/developers/docs/references/content-management-api/uploads/retrieve-an-upload.md)
- Uploads [Delete an upload](https://contentful.com/developers/docs/references/content-management-api/uploads/delete-an-upload.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://contentful.com/developers/docs/openapi.json)
- [OpenAPI YAML](https://contentful.com/developers/docs/openapi.yaml)