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_strategy enum

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

path string Optional

Upload path

Example:

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

basename string Optional

Upload basename

Example:

"digital-cats"

Example:

"2020 DatoCMS"

author string, null Optional

Author

Example:

"Mark Smith"

notes string, null Optional

Notes

Example:

"Nyan the cat"

tags Optional

Returns

Returns a resource object of type upload

Other examples

This example demonstrates how to update the metadata attributes of an existing asset without changing the underlying file.

You can update fields like:

author: The creator or photographer of the asset
copyright: Copyright information for the asset
default_field_metadata: Per-locale default metadata including alt text, title, focal point, and custom data

The default_field_metadata object allows you to set defaults that will be used when the asset is referenced in records, unless overridden at the record level.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const uploadId = "FWYwxZZ1SUG1ReKlzdDAEA";
8

9
  const updatedUpload = await client.uploads.update(uploadId, {
10
    author: "New author!",
11
    copyright: "New copyright",
12
    default_field_metadata: {
13
      en: {
14
        alt: "new default alt",
15
        title: "new default title",
16
        focal_point: {
17
          x: 0.3,
18
          y: 0.6,
19
        },
20
        custom_data: {},
21
      },
22
    },
23
  });
24

25
  console.log({
26
    id: updatedUpload.id,
27
    author: updatedUpload.author,
28
    copyright: updatedUpload.copyright,
29
    default_field_metadata: updatedUpload.default_field_metadata,
30
  });
31
}
32

33
run();

1
{
2
  id: 'FWYwxZZ1SUG1ReKlzdDAEA',
3
  author: 'New author!',
4
  copyright: 'New copyright',
5
  default_field_metadata: {
6
    en: {
7
      alt: 'new default alt',
8
      title: 'new default title',
9
      focal_point: [Object],
10
      custom_data: {}
11
    }
12
  }
13
}

This example demonstrates how to replace the file associated with an existing upload while keeping the same upload ID.

When replacing an asset, you have two options:

Create new URL (default): The new asset is available immediately with a fresh URL. The old URL will be purged from cache and will disappear after complete propagation. Use this when you need immediate availability of the new file.

Keep the original URL: Existing links continue to work automatically, but changes take 5-10 minutes to appear everywhere due to CDN and browser cache propagation. Some users may temporarily see the old version. Use this when you have many existing references and want to avoid updating URLs.

Important considerations for keep_url

The keep_url option is only available when the new file has the same format/extension as the original (e.g., replacing a .jpg with another .jpg/.jpeg). If the formats differ, you must use the default create_new_url strategy.

Also note that since different upload entities across environments can share the same asset URL, using keep_url will automatically update all uploads that reference this asset path. This ensures consistency across environments but means the change affects more than just the current upload.

The uploadLocalFileAndReturnPath() helper handles:

Requesting upload permissions from DatoCMS
Uploading the file to the storage bucket
Returning the path to use in the update call

1
import {
2
  buildClient,
3
  uploadLocalFileAndReturnPath,
4
} from "@datocms/cma-client-node";
5

6
async function run() {
7
  // Make sure the API token has access to the CMA, and is stored securely
8
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
9

10
  // Fetch the original uploads to show their URLs before replacement
11
  const original1 = await client.uploads.find("bDb8xUJIRaGteyJYldfKsA");
12
  const original2 = await client.uploads.find("II2mHvSkQESUl-2401HZgg");
13

14
  console.log("Before replacement:");
15
  console.log("  Upload 1 URL:", original1.url);
16
  console.log("  Upload 2 URL:", original2.url);
17

18
  // Upload the new file and get the path
19
  const newFilePath = await uploadLocalFileAndReturnPath(
20
    client,
21
    "./new-image.jpg",
22
  );
23

24
  // ============================================================
25
  // Option 1: Create new URL (default)
26
  // ============================================================
27
  // The new asset is available immediately with a fresh URL.
28
  // Use this when you need immediate availability.
29

30
  const uploadWithNewUrl = await client.uploads.update(
31
    "bDb8xUJIRaGteyJYldfKsA",
32
    { path: newFilePath },
33
  );
34

35
  // ============================================================
36
  // Option 2: Keep the original URL
37
  // ============================================================
38
  // Existing links work automatically, but changes take 5-10 minutes
39
  // to propagate. Use this when you have many existing references.
40

41
  const uploadKeepingUrl = await client.uploads.update(
42
    "II2mHvSkQESUl-2401HZgg",
43
    { path: newFilePath },
44
    { replace_strategy: "keep_url" },
45
  );
46

47
  console.log("\nAfter replacement:");
48
  console.log("  Option 1 (new URL):", uploadWithNewUrl.url);
49
  console.log("  Option 2 (keep URL):", uploadKeepingUrl.url);
50
}
51

52
run();

1
Before replacement:
2
  Upload 1 URL: https://www.datocms-assets.com/190734/1768292263-old-image.jpg
3
  Upload 2 URL: https://www.datocms-assets.com/190734/1768292270-old-image.jpg
4

5
After replacement:
6
  Option 1 (new URL): https://www.datocms-assets.com/190734/1768292279-new-image.jpg
7
  Option 2 (keep URL): https://www.datocms-assets.com/190734/1768292270-old-image.jpg

This example demonstrates how to rename an uploaded file in the CDN by changing its basename.

This is particularly useful for SEO purposes, as the filename becomes part of the asset's URL. Renaming allows you to use descriptive, keyword-rich filenames without needing to re-upload the file.

The basename is the filename without the extension. For example, setting basename to "premium-headphones" for a .jpg file would result in a URL ending in premium-headphones.jpg.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const uploadId = "ey4EL5V0QYCdODxbbUj2cQ";
8

9
  // Rename the uploaded file in the CDN (for SEO purposes)
10
  const updatedUpload = await client.uploads.update(uploadId, {
11
    basename: "this-will-be-the-new-file-basename",
12
  });
13

14
  console.log({
15
    id: updatedUpload.id,
16
    basename: updatedUpload.basename,
17
    path: updatedUpload.path,
18
    url: updatedUpload.url,
19
  });
20
}
21

22
run();

1
{
2
  id: 'ey4EL5V0QYCdODxbbUj2cQ',
3
  basename: 'this-will-be-the-new-file-basename',
4
  path: '/190729/1768291467-this-will-be-the-new-file-basename.jpeg',
5
  url: 'https://www.datocms-assets.com/190729/1768291467-this-will-be-the-new-file-basename.jpeg'
6
}

Update an upload

Query parameters

Body parameters

Returns

Other examples

Code

Returned output

Code

Returned output

Code

Returned output