Sorry, no results found for "".

Show examples in:

Endpoint info

Body parameters

Returns

Available examples

Step 1: Request an upload permission

Step 2: Upload file to the storage bucket

Step 3: Create the actual upload (and get back the async job)

Step 4: Retrieve the job result and check for errors

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.

First, send a POST request to the /upload-requests endpoint to obtain the location on which to perform the physical file upload:

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
    "type": "upload_request",
10
    "id": "/7/1455102967-image.png",
11
    "attributes": {
12
      "url": "https://dato-images.s3.eu-west-1.amazonaws.com/205/1565776891-image.png?x-amz-acl=public-read&...",
13
      "request_headers": {
14
        "X-Foo": "bar"
15
      }
16
    }
17
  }
18
}

Now it is possible to use the obtained information to build an HTTP request that effectively uploads the file:

The HTTP method MUST be PUT
The URL is the one specified in the url attribute of the previous response
Each header specified in the request_headers attribute of the previous response MUST be set as a request header
It is possible to add a Content-Type header to specify the type of file being uploaded
The content of the file must be inserted as the raw body of the request (no multipart upload)

1
PUT https://dato-images.s3.eu-west-1.amazonaws.com/205/1565776891-image.png?x-amz-acl=public-read&... HTTP/1.1
2
Content-Type: image/png
3
X-Foo: bar
4

5
<YOUR_FILE_BINARY_CONTENT>

1
curl -g 'https://dato-images.s3.eu-west-1.amazonaws.com/205/1565776891-image.png?x-amz-acl=public-read&...' \
2
  -X PUT \
3
  -H "Content-Type: image/png" \
4
  -H "X-Foo: bar" \
5
  --data-binary '<YOUR_FILE_BINARY_CONTENT>'

1
await fetch(
2
  "https://dato-images.s3.eu-west-1.amazonaws.com/205/1565776891-image.png?x-amz-acl=public-read&...",
3
  {
4
    method: "PUT",
5
    headers: { "Content-Type": "image/png", "X-Foo": "bar" },
6
    body: "<YOUR_FILE_BINARY_CONTENT>",
7
  },
8
);

1
HTTP/1.1 202 Accepted
2
X-Amz-Request-Rd: XXX
3
Server: AmazonS3
4

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

This step initiates a long-running background job to associate your S3 upload to the correct asset in DatoCMS. It normally takes 3-5 seconds, but can sometimes take a bit longer under heavy load. Once the background job is completed, the asset will appear in your DatoCMS media area.

To start the job, make a POST request to the /uploads endpoint with the path being the ID of the request made on step 1. You'll get back a job ID, which you can separately query in the next step in order to check on the background job status.

Notes:

If you choose to provide default field metadata, the alt, title, and custom_data fields are required.
Also, please note that validation errors will not be immediately returned in this step. You must use the next step (retrieve the job result) to see any errors that might've occurred.
If you are uploading multiple files and trying to optimize upload performance, it is safe to start another upload as soon as this step is done (i.e., you got back a 202 indicating the background job has started). However, you should still check the background job status for each file a few seconds later to be sure each one completed without error. See next step for details.

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": "/205/1565776891-image.png",
12
      "author": "Mark",
13
      "copyright": "2020 DatoCMS",
14
      "default_field_metadata": {
15
        // Alt, title, and custom_data are required with default metadata
16
        "en": {
17
          "alt": "Nyan the cat",
18
          "title": "My cat",
19
          "custom_data": {}
20
        }
21
      }
22
    }
23
  }
24
}

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 '{
8
  "data": {
9
    "type": "upload",
10
    "attributes": {
11
      "path": "/205/1565776891-image.png",
12
      "author": "Mark",
13
      "copyright": "2020 DatoCMS",
14
      "default_field_metadata": {
15
        // Alt, title, and custom_data are required with default metadata
16
        "en": {
17
          "alt": "Nyan the cat",
18
          "title": "My cat",
19
          "custom_data": {}
20
        }
21
      }
22
    }
23
  }
24
}
25
'

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: '{\n  "data": {\n    "type": "upload",\n    "attributes": {\n      "path": "/205/1565776891-image.png",\n      "author": "Mark",\n      "copyright": "2020 DatoCMS",\n      "default_field_metadata": {\n        // Alt, title, and custom_data are required with default metadata\n        "en": {\n          "alt": "Nyan the cat",\n          "title": "My cat",\n          "custom_data": {}\n        }\n      }\n    }\n  }\n}\n',
10
});

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 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": "/205/1565776891-image.png",
22
            "url": "https://www.datocms-assets.com/205/1565776891-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

Did this doc help you?

Need help?

Explore our forum, contact support, or connect with our sales team . You can also chat live with other users in our Slack channel.