Content Management API > Upload

Update an upload

Depending on the attributes that you pass, you can use this endpoint to:

Update regular attributes like author, notes, copyright, default_field_metadata, etc.;
Rename the asset by passing a different basename attribute;
Upload a new version of the asset by passing a different path attribute;

Just like POST /uploads endpoint, an asyncronous job ID might be returned instead of the regular response. See the Create a new upload section for more details.

We strongly recommend to use our JS or Ruby client to upload new assets, as they provide helper methods that take care of all the details for you.

Query parameters

replace_strategyenum

Strategy to use when replacing the asset file. If not specified, a new URL will be generated.

Example:

"keep_url"

create_new_url

Generate a new URL for the asset (default behavior)

keep_url

Maintain the same URL by overwriting the file at the existing path

Body parameters

typestringRequired

Must be exactly "upload".

attributes.pathstringOptional

Upload path

Example:

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

attributes.basenamestringOptional

Upload basename

Example:

"digital-cats"

attributes.copyrightstring, nullOptional

Example:

"2020 DatoCMS"

attributes.authorstring, nullOptional

Author

Example:

"Mark Smith"

attributes.notesstring, nullOptional

Notes

Example:

"Nyan the cat"

attributes.tagsOptional

Returns

Returns a Job ID. You can then poll for thecompletion of the jobthat will eventually return a resource object of type upload

Other examples

1
PUT https://site-api.datocms.com/uploads/4124 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
    "id": "4124",
10
    "type": "upload",
11
    "attributes": {
12
      "author": "Mark",
13
      "copyright": "2020 DatoCMS",
14
      "default_field_metadata": {
15
        "alt": {
16
          "en": "Nyan the cat"
17
        },
18
        "title": {
19
          "en": "My cat"
20
        },
21
        "custom_data": {
22
          "en": {}
23
        }
24
      }
25
    }
26
  }
27
}

1
curl -g 'https://site-api.datocms.com/uploads/4124' \
2
  -X PUT \
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":{"id":"4124","type":"upload","attributes":{"author":"Mark","copyright":"2020 DatoCMS","default_field_metadata":{"alt":{"en":"Nyan the cat"},"title":{"en":"My cat"},"custom_data":{"en":{}}}}}}'

1
await fetch("https://site-api.datocms.com/uploads/4124", {
2
  method: "PUT",
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
      id: "4124",
12
      type: "upload",
13
      attributes: {
14
        author: "Mark",
15
        copyright: "2020 DatoCMS",
16
        default_field_metadata: {
17
          alt: { en: "Nyan the cat" },
18
          title: { en: "My cat" },
19
          custom_data: { en: {} },
20
        },
21
      },
22
    },
23
  }),
24
});

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",
10
    "id": "666",
11
    "attributes": {
12
      "size": 444,
13
      "width": 30,
14
      "height": 30,
15
      "path": "/205/1565776891-image.png",
16
      "url": "https://www.datocms-assets.com/205/1565776891-image.png",
17
      "basename": "image",
18
      "format": "jpg",
19
      "alt": "Nyan the cat",
20
      "title": "My cat",
21
      "is_image": true,
22
      "author": "Mark",
23
      "copyright": "2020 DatoCMS",
24
      "default_field_metadata": {
25
        "alt": {
26
          "en": "Nyan the cat"
27
        },
28
        "title": {
29
          "en": "My cat"
30
        },
31
        "custom_data": {
32
          "en": {}
33
        }
34
      }
35
    }
36
  }
37
}

1
PUT https://site-api.datocms.com/uploads/4124 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
    "id": "4124",
10
    "type": "upload",
11
    "attributes": {
12
      "basename": "this-is-the-new-file-name"
13
    }
14
  }
15
}

1
curl -g 'https://site-api.datocms.com/uploads/4124' \
2
  -X PUT \
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":{"id":"4124","type":"upload","attributes":{"basename":"this-is-the-new-file-name"}}}'

1
await fetch("https://site-api.datocms.com/uploads/4124", {
2
  method: "PUT",
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
      id: "4124",
12
      type: "upload",
13
      attributes: { basename: "this-is-the-new-file-name" },
14
    },
15
  }),
16
});

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
}

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
              "alt": {
32
                "en": "Nyan the cat"
33
              },
34
              "title": {
35
                "en": "My cat"
36
              },
37
              "custom_data": {
38
                "en": {}
39
              }
40
            }
41
          }
42
        }
43
      }
44
    }
45
  }
46
}