Content Management API > Upload

Create a new upload

⚠️ We highly advocate for utilizing our JavaScript client when uploading new assets, as it comes equipped with high-level helper methods that handle all the nitty-gritty for you.

Uploading a new asset to a DatoCMS project manually is a process that necessitates several HTTP calls. This approach significantly accelerates the upload process for DatoCMS, as it eliminates the need for us to act as an intermediary between you, the user aiming to upload an asset, and the storage bucket.

File uploads via HTTP is a multi-step process.

In this first step, you send a POST request to the /upload-requests endpoint to obtain a presigned bucket URL for later use. No actual file upload occurs yet; you're just authenticating and retrieving necessary metadata.

1
POST https://site-api.datocms.com/upload-requests HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3
5
Content-Type: application/vnd.api+json
6

7
{
8
  "data": {
9
    "type": "upload_request",
10
    "attributes": {
11
      "filename": "image.png"
12
    }
13
  }
14
}

1
curl -g 'https://site-api.datocms.com/upload-requests' \
2
  -X POST \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3" \
6
  -H "Content-Type: application/vnd.api+json" \
7
  --data-binary '{"data":{"type":"upload_request","attributes":{"filename":"image.png"}}}'

1
await fetch("https://site-api.datocms.com/upload-requests", {
2
  method: "POST",
3
  headers: {
4
    Authorization: "Bearer YOUR-API-TOKEN",
5
    Accept: "application/json",
6
    "X-Api-Version": "3",
7
    "Content-Type": "application/vnd.api+json",
8
  },
9
  body: JSON.stringify({
10
    data: { type: "upload_request", attributes: { filename: "image.png" } },
11
  }),
12
});

1
HTTP/1.1 202 Accepted
2
Content-Type: application/json
3
Cache-Control: cache-control: max-age=0, private, must-revalidate
4
X-RateLimit-Limit: 30
5
X-RateLimit-Remaining: 28
6

7
{
8
  "data": {
9
    "id": "/160228/1745427779-image.png",
10
    "type": "upload_request",
11
    "attributes": {
12
      "url": "https://datocms-assets.6c36efb897e5eae1d2a887cfa632eea9.eu.r2.cloudflarestorage.com/160228/1745427779-image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=blahblah...",
13
      "request_headers": {
14
        "X-Addition-Header-To-Add-In-Step-2": "some-value"
15
      }
16
    }
17
  }
18
}

With the presigned bucket URL from step 1, you now have the information you need in order to upload the actual file to the bucket. This uploads the file from your computer to the bucket storage (for regular users, it is Cloudflare R2, but Enterprise plans can specify different options).

Requirements:

The HTTP method MUST be a PUT to the bucket URL.
The signed bucket URL is the data.attributes.url property of the previous step's JSON response.
Each header specified in the data.attributes.request_headers property of the previous step's JSON response MUST be set as an HTTP request header in this request. Although this property is often empty, it sometimes contains essential information for certain buckets (like enterprise assets to be saved to Azure Blob Storage).
You should always add the proper Content-Type header, like Content-Type: application/pdf. This is especially important for any uploads that are NOT images, as for those, that's the only way we know the format of the file.
The content of the file must be inserted as the raw binary body of the request (no multipart upload).

Experiencing a Missing x-amz-content-sha256 error? This issue occurs if an HTTP Authorization header is included in your request. The URL data.attributes.url already has a signature, so adding an Authorization header will confuse the endpoint. Remove the header, which may be there due to code reuse or inherited authentication in Postman, and try again.

1
PUT https://datocms-assets.6c36efb897e5eae1d2a887cfa632eea9.eu.r2.cloudflarestorage.com/160228/1745427779-image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=blahblah... HTTP/1.1
2
Content-Type: image/png
3
X-Addition-Header-To-Add-In-Step-2: some-value
4

5
<YOUR_FILE_BINARY_CONTENT>

1
curl -g 'https://datocms-assets.6c36efb897e5eae1d2a887cfa632eea9.eu.r2.cloudflarestorage.com/160228/1745427779-image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=blahblah...' \
2
  -X PUT \
3
  -H "Content-Type: image/png" \
4
  -H "X-Addition-Header-To-Add-In-Step-2: some-value" \
5
  --data-binary '<YOUR_FILE_BINARY_CONTENT>'

1
await fetch(
2
  "https://datocms-assets.6c36efb897e5eae1d2a887cfa632eea9.eu.r2.cloudflarestorage.com/160228/1745427779-image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=blahblah...",
3
  {
4
    method: "PUT",
5
    headers: {
6
      "Content-Type": "image/png",
7
      "X-Addition-Header-To-Add-In-Step-2": "some-value",
8
    },
9
    body: "<YOUR_FILE_BINARY_CONTENT>",
10
  },
11
);

1
HTTP/1.1 202 Accepted
2
Server: cloudflare
3

4
{
5
  "data": {
6
    "type": "job",
7
    "id": "4235"
8
  }
9
}

This step initiates a background job to associate your uploaded file with a new asset in DatoCMS.

Background jobs typically complete in 3-5 seconds but may take longer under heavy load. Once the background job is completed, the asset will automatically appear in your DatoCMS media area.

To start the background job, make a POST request to the /uploads endpoint with a JSON body like the example below. In your request, data.attributes.path should be the data.id from Step 1's response.

The response will include a job ID indicating that the creation process has started. Use this ID in Step 4 to check the job completion status and any potential errors.

Notes:

If you choose to provide default field metadata, the alt, title, and custom_data fields are ALL required.
Validation errors will not be immediately returned in this step. You must perform the next step (retrieve the job result) to see any errors that might have occurred.
To improve batch upload throughput, submit multiple files in parallel rather than sequentially. Once you receive a 202 response with a job ID for one upload, immediately submit another file without waiting for the first to complete. This significantly reduces total upload time: just remember to track each job ID separately to check individual completion status and any errors.

1
POST https://site-api.datocms.com/uploads HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3
5
Content-Type: application/vnd.api+json
6

7
{
8
  "data": {
9
    "type": "upload",
10
    "attributes": {
11
      "path": "/160228/1745427779-image.png",
12
      "author": "Mark",
13
      "copyright": "2020 DatoCMS",
14
      "default_field_metadata": {
15
        "en": {
16
          "alt": "Nyan the cat",
17
          "title": "My cat",
18
          "custom_data": {}
19
        }
20
      }
21
    }
22
  }
23
}

1
curl -g 'https://site-api.datocms.com/uploads' \
2
  -X POST \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3" \
6
  -H "Content-Type: application/vnd.api+json" \
7
  --data-binary '{"data":{"type":"upload","attributes":{"path":"/160228/1745427779-image.png","author":"Mark","copyright":"2020 DatoCMS","default_field_metadata":{"en":{"alt":"Nyan the cat","title":"My cat","custom_data":{}}}}}}'

1
await fetch("https://site-api.datocms.com/uploads", {
2
  method: "POST",
3
  headers: {
4
    Authorization: "Bearer YOUR-API-TOKEN",
5
    Accept: "application/json",
6
    "X-Api-Version": "3",
7
    "Content-Type": "application/vnd.api+json",
8
  },
9
  body: JSON.stringify({
10
    data: {
11
      type: "upload",
12
      attributes: {
13
        path: "/160228/1745427779-image.png",
14
        author: "Mark",
15
        copyright: "2020 DatoCMS",
16
        default_field_metadata: {
17
          en: { alt: "Nyan the cat", title: "My cat", custom_data: {} },
18
        },
19
      },
20
    },
21
  }),
22
});

1
HTTP/1.1 202 Accepted
2
Content-Type: application/json
3
Cache-Control: cache-control: max-age=0, private, must-revalidate
4
X-RateLimit-Limit: 30
5
X-RateLimit-Remaining: 28
6

7
{
8
  "data": {
9
    "type": "job",
10
    "id": "facf9248be977002c9bae231"
11
  }
12
}

This is the final step in the upload creation lifecycle.

Whereas the previous step started the background job, this endpoint tells you the real-time status of that job. This is how you verify the success or failure of an upload.

Although technically an optional step, we still recommend querying this endpoint a few times in order to keep track of the upload lifecycle. You should keep polling until it either completely succeeds or fails early.

This endpoint tells you several useful things:

While the job is still processing, the endpoint will return a 404 status code. Keep querying once every second or two until you either get a success or failure state.
If the job finishes successfully (i.e., the S3-like upload was successfully associated with a DatoCMS asset), you will get back a 200 status code and the successfully associated upload object in the payload. At this point, the asset will be available in the DatoCMS media area.
If the job fails due to a validation or other error, you will immediately get back a 422 or similar error code. Check payload.data[] for any objects of type: "api_error", and its attributes.details.code and attributes.details.message will tell you specifically what failed.
Once the job either succeeds or fails, the job result will persist for approximately 15 minutes. After that, it will 404 again.

On validation failure

This is an example 422 validation failure response:

1
{
2
  "data": {
3
    "id": "c628b8ccf485a127775c635a",
4
    "type": "job_result",
5
    "attributes": {
6
      "payload": {
7
        "data": [
8
          {
9
            "id": "6a1131",
10
            "type": "api_error",
11
            "attributes": {
12
              "code": "INVALID_FIELD",
13
              "details": {
14
                "field": "default_field_metadata.en",
15
                "code": "INVALID_FORMAT",
16
                "message": "Must contain alt, title and custom_data"
17
              },
18
              "doc_url": "https://www.datocms.com/docs/content-management-api/errors#INVALID_FIELD"
19
            }
20
          }
21
        ]
22
      },
23
      "status": 422,
24
      "statusText": "Unprocessable Entity"
25
    }
26
  }
27
}

Validation errors should be available within a second or two under typical conditions. If you don't get an error, it's safe to assume the job is still processing... just keep polling and you should get a success soon afterward. The whole process usually takes only 3-5 seconds per image, but can be a little slower under heavy load.

On success

A successful response would look like the "HTTP Response" below.

1
GET https://site-api.datocms.com/job-results/facf9248be977002c9bae231 HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3
5
Content-Type: application/vnd.api+json

1
curl -g 'https://site-api.datocms.com/job-results/facf9248be977002c9bae231' \
2
   \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3" \
6
  -H "Content-Type: application/vnd.api+json"

1
await fetch(
2
  "https://site-api.datocms.com/job-results/facf9248be977002c9bae231",
3
  {
4
    headers: {
5
      Authorization: "Bearer YOUR-API-TOKEN",
6
      Accept: "application/json",
7
      "X-Api-Version": "3",
8
      "Content-Type": "application/vnd.api+json",
9
    },
10
  },
11
);

1
HTTP/1.1 202 Accepted
2
Content-Type: application/json
3
Cache-Control: cache-control: max-age=0, private, must-revalidate
4
X-RateLimit-Limit: 30
5
X-RateLimit-Remaining: 28
6

7
{
8
  "data": {
9
    "type": "job-result",
10
    "id": "facf9248be977002c9bae231",
11
    "attributes": {
12
      "status": 200,
13
      "payload": {
14
        "data": {
15
          "type": "upload",
16
          "id": "666",
17
          "attributes": {
18
            "size": 444,
19
            "width": 30,
20
            "height": 30,
21
            "path": "/160228/1745427779-image.png",
22
            "url": "https://www.datocms-assets.com/160228/1745427779-image.png",
23
            "basename": "image",
24
            "format": "jpg",
25
            "alt": "Nyan the cat",
26
            "title": "My cat",
27
            "is_image": true,
28
            "author": "Mark",
29
            "copyright": "2020 DatoCMS",
30
            "default_field_metadata": {
31
              "en": {
32
                "alt": "Nyan the cat",
33
                "title": "My cat",
34
                "custom_data": {}
35
              }
36
            }
37
          }
38
        }
39
      }
40
    }
41
  }
42
}

Body parameters

id string Optional

RFC 4122 UUID of upload expressed in URL-safe base64 format

Example:

"q0VNpiNQSkG6z0lif_O1zg"

type string Required

Must be exactly "upload".

attributes.path string Required

Upload path

Example:

"/45/1496845848-digital-cats.jpg"

attributes.copyright string, null Optional

Example:

"2020 DatoCMS"

attributes.author string, null Optional

Author

Example:

"Mark Smith"

attributes.notes string, null Optional

Notes

Example:

"Nyan the cat"

attributes.default_field_metadata object Optional

For each of the project's locales, the default metadata to apply if nothing is specified at record's level.

Example:

{
  en: {
    title: "this is the default title",
    alt: "this is the default alternate text",
    custom_data: { foo: "bar" },
    focal_point: { x: 0.5, y: 0.5 },
  },
}

attributes.tags Optional

Returns

Returns a Job ID. You can then poll for the completion of the job that will eventually return a resource object of type upload

Create a new upload

HTTP Request

CURL Request

fetch() Request

HTTP Response

HTTP Request

CURL Request

fetch() Request

HTTP Response

HTTP Request

CURL Request

fetch() Request

HTTP Response

On validation failure

On success

HTTP Request

CURL Request

fetch() Request

HTTP Response

Body parameters

Returns