# 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](https://www.datocms.com/docs/content-management-api/resources/upload.md#create) 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`**

- Type: enum
- Example: `"keep_url"`

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

<details>
<summary>Show enum values</summary>

**`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

</details>

## Body parameters

**`path`**

- Optional
- Type: string
- Example: `"/45/1496845848-digital-cats.jpg"`

Upload path

**`basename`**

- Optional
- Type: string
- Example: `"digital-cats"`

Upload basename

**`copyright`**

- Optional
- Type: string, null
- Example: `"2020 DatoCMS"`

Copyright

**`author`**

- Optional
- Type: string, null
- Example: `"Mark Smith"`

Author

**`notes`**

- Optional
- Type: string, null
- Example: `"Nyan the cat"`

Notes

**`tags`**

- Optional
- Type: Array\<string\>
- Example: `["cats"]`

Tags

**`default_field_metadata`**

- Optional
- Type: object

Patch the asset's default metadata. Send any subset of `alt`/`title`/`custom_data`/`focal_point`/`poster_time` — missing keys preserve their stored values. See the response shape for the full structure and per-key semantics.

<details>
<summary>Show object format</summary>

**`alt`**

- Optional
- Type: object
- Example: `{ en: "Alternate text" }`

Alternate text per locale

**`title`**

- Optional
- Type: object
- Example: `{ en: "Title" }`

Title per locale

**`custom_data`**

- Optional
- Type: object
- Example: `{ en: { add_watermark: true } }`

Object with arbitrary metadata, per locale

**`focal_point`**

- Optional
- Type: object, null

Focal point (only for image assets)

<details>
<summary>Show object format</summary>

**`x`**

- Required
- Type: number
- Example: `0.5`

Horizontal position expressed as float between 0 and 1

**`y`**

- Required
- Type: number
- Example: `0.5`

Vertical position expressed as float between 0 and 1

</details>

**`poster_time`**

- Optional
- Type: number, null
- Example: `12.5`

Poster time in seconds (only for video assets). Float seconds into the video used to generate the thumbnail; null uses Mux's default (middle of the video)

</details>

**`creator`**

- Optional
- Type: [ResourceLinkage\<"account"\>](https://www-draft.datocms.com/docs/content-management-api/resources/account.md), [ResourceLinkage\<"access_token"\>](https://www-draft.datocms.com/docs/content-management-api/resources/access_token.md), [ResourceLinkage\<"user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/user.md), [ResourceLinkage\<"sso_user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/sso_user.md), [ResourceLinkage\<"organization"\>](https://www-draft.datocms.com/docs/content-management-api/resources/organization.md)

The entity (account/collaborator/access token) who created the asset

**`upload_collection`**

- Optional
- Type: [ResourceLinkage\<"upload_collection"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload_collection.md), null

Upload collection to which the asset belongs

## Returns

Returns a resource object of type [upload](https://www.datocms.com/docs/content-management-api/resources/upload.md)

## Other examples

###### Example Update asset attributes

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`**: Default metadata for the asset. `alt`, `title`, and `custom_data` are keyed by locale, while `focal_point` (images) and `poster_time` (videos) are single, non-localized values

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.

Code

```javascript
import { buildClient } from "@datocms/cma-client-node";

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

  const uploadId = "FWYwxZZ1SUG1ReKlzdDAEA";

  const updatedUpload = await client.uploads.update(uploadId, {
    author: "New author!",
    copyright: "New copyright",
    default_field_metadata: {
      alt: { en: "new default alt" },
      title: { en: "new default title" },
      custom_data: { en: {} },
      focal_point: {
        x: 0.3,
        y: 0.6,
      },
    },
  });

  console.log({
    id: updatedUpload.id,
    author: updatedUpload.author,
    copyright: updatedUpload.copyright,
    default_field_metadata: updatedUpload.default_field_metadata,
  });
}

run();
```

Returned output

```javascript
{
  id: 'FWYwxZZ1SUG1ReKlzdDAEA',
  author: 'New author!',
  copyright: 'New copyright',
  default_field_metadata: {
    alt: { en: 'new default alt' },
    title: { en: 'new default title' },
    custom_data: { en: {} },
    focal_point: { x: 0.3, y: 0.6 },
    poster_time: null
  }
}
```


###### Example Replace the asset file

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.

> [!WARNING] 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

Code

```javascript
import {
  buildClient,
  uploadLocalFileAndReturnPath,
} from "@datocms/cma-client-node";

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

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

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

  // Upload the new file and get the path
  const newFilePath = await uploadLocalFileAndReturnPath(
    client,
    "./new-image.jpg",
  );

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

  const uploadWithNewUrl = await client.uploads.update(
    "bDb8xUJIRaGteyJYldfKsA",
    { path: newFilePath },
  );

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

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

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

run();
```

Returned output

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

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


###### Example Rename the file

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`.

Code

```javascript
import { buildClient } from "@datocms/cma-client-node";

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

  const uploadId = "ey4EL5V0QYCdODxbbUj2cQ";

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

  console.log({
    id: updatedUpload.id,
    basename: updatedUpload.basename,
    path: updatedUpload.path,
    url: updatedUpload.url,
  });
}

run();
```

Returned output

```javascript
{
  id: 'ey4EL5V0QYCdODxbbUj2cQ',
  basename: 'this-will-be-the-new-file-basename',
  path: '/190729/1768291467-this-will-be-the-new-file-basename.jpeg',
  url: 'https://www.datocms-assets.com/190729/1768291467-this-will-be-the-new-file-basename.jpeg'
}
```

## Related content in "Content Management API"

- [Content Management API Overview](https://www.datocms.com/docs/content-management-api.md)
- [Using the JavaScript CMA client](https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients.md)
- [API versioning](https://www.datocms.com/docs/content-management-api/api-versioning.md)
- [Authentication](https://www.datocms.com/docs/content-management-api/authentication.md)
- [Environments](https://www.datocms.com/docs/content-management-api/setting-the-environment.md)
- [Error codes & handling failures (CMA)](https://www.datocms.com/docs/content-management-api/errors.md)
- [Pagination](https://www.datocms.com/docs/content-management-api/pagination.md)
- [Asynchronous jobs](https://www.datocms.com/docs/content-management-api/async-jobs.md)
- [CMA Technical Limits & Rate Limits](https://www.datocms.com/docs/content-management-api/technical-limits.md)
- [Record](https://www.datocms.com/docs/content-management-api/resources/item.md)
- [Scheduled publication](https://www.datocms.com/docs/content-management-api/resources/scheduled-publication.md)
- [Scheduled unpublishing](https://www.datocms.com/docs/content-management-api/resources/scheduled-unpublishing.md)
- [Upload](https://www.datocms.com/docs/content-management-api/resources/upload.md)
- [Create a new upload](https://www.datocms.com/docs/content-management-api/resources/upload/create.md)
- [List all uploads](https://www.datocms.com/docs/content-management-api/resources/upload/instances.md)
- [Retrieve an upload](https://www.datocms.com/docs/content-management-api/resources/upload/self.md)
- [Delete an upload](https://www.datocms.com/docs/content-management-api/resources/upload/destroy.md)
- [Update an upload](https://www.datocms.com/docs/content-management-api/resources/upload/update.md)
- [Referenced records](https://www.datocms.com/docs/content-management-api/resources/upload/references.md)
- [Add tags to assets in bulk](https://www.datocms.com/docs/content-management-api/resources/upload/bulk_tag.md)
- [Put assets into a collection in bulk](https://www.datocms.com/docs/content-management-api/resources/upload/bulk_set_upload_collection.md)
- [Destroy uploads](https://www.datocms.com/docs/content-management-api/resources/upload/bulk_destroy.md)
- [Site](https://www.datocms.com/docs/content-management-api/resources/site.md)
- [Model/Block model](https://www.datocms.com/docs/content-management-api/resources/item-type.md)
- [Field](https://www.datocms.com/docs/content-management-api/resources/field.md)
- [Fieldset](https://www.datocms.com/docs/content-management-api/resources/fieldset.md)
- [Record version](https://www.datocms.com/docs/content-management-api/resources/item-version.md)
- [Upload permission](https://www.datocms.com/docs/content-management-api/resources/upload-request.md)
- [Upload track](https://www.datocms.com/docs/content-management-api/resources/upload-track.md)
- [Manual tags](https://www.datocms.com/docs/content-management-api/resources/upload-tag.md)
- [Smart tags](https://www.datocms.com/docs/content-management-api/resources/upload-smart-tag.md)
- [Upload Collection](https://www.datocms.com/docs/content-management-api/resources/upload-collection.md)
- [Search Index](https://www.datocms.com/docs/content-management-api/resources/search-index.md)
- [Search result](https://www.datocms.com/docs/content-management-api/resources/search-result.md)
- [Search indexing activity](https://www.datocms.com/docs/content-management-api/resources/search-index-event.md)
- [Environment](https://www.datocms.com/docs/content-management-api/resources/environment.md)
- [Maintenance mode](https://www.datocms.com/docs/content-management-api/resources/maintenance-mode.md)
- [Menu Item](https://www.datocms.com/docs/content-management-api/resources/menu-item.md)
- [Schema Menu Item](https://www.datocms.com/docs/content-management-api/resources/schema-menu-item.md)
- [Uploads filter](https://www.datocms.com/docs/content-management-api/resources/upload-filter.md)
- [Model filter](https://www.datocms.com/docs/content-management-api/resources/item-type-filter.md)
- [Plugin](https://www.datocms.com/docs/content-management-api/resources/plugin.md)
- [Workflow](https://www.datocms.com/docs/content-management-api/resources/workflow.md)
- [Asynchronous job](https://www.datocms.com/docs/content-management-api/resources/job.md)
- [Job result](https://www.datocms.com/docs/content-management-api/resources/job-result.md)
- [Account](https://www.datocms.com/docs/content-management-api/resources/account.md)
- [Organization](https://www.datocms.com/docs/content-management-api/resources/organization.md)
- [Invitation](https://www.datocms.com/docs/content-management-api/resources/site-invitation.md)
- [Collaborator](https://www.datocms.com/docs/content-management-api/resources/user.md)
- [Role](https://www.datocms.com/docs/content-management-api/resources/role.md)
- [API token](https://www.datocms.com/docs/content-management-api/resources/access-token.md)
- [Webhook](https://www.datocms.com/docs/content-management-api/resources/webhook.md)
- [Webhook call](https://www.datocms.com/docs/content-management-api/resources/webhook-call.md)
- [Build trigger](https://www.datocms.com/docs/content-management-api/resources/build-trigger.md)
- [Deploy activity](https://www.datocms.com/docs/content-management-api/resources/build-event.md)
- [Subscription limit](https://www.datocms.com/docs/content-management-api/resources/subscription-limit.md)
- [Subscription feature](https://www.datocms.com/docs/content-management-api/resources/subscription-feature.md)
- [SSO Settings](https://www.datocms.com/docs/content-management-api/resources/sso-settings.md)
- [SSO User](https://www.datocms.com/docs/content-management-api/resources/sso-user.md)
- [SSO Group](https://www.datocms.com/docs/content-management-api/resources/sso-group.md)
- [White-label settings](https://www.datocms.com/docs/content-management-api/resources/white-label-settings.md)
- [Audit log event](https://www.datocms.com/docs/content-management-api/resources/audit-log-event.md)