---
title: "Asset Versions"
description: "<p>Retrieve and name the versions of an asset.</p>"
url: "https://www.contentstack.com/docs/developers/apis/assets-api/asset-versions"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-08-21"
---

# Asset Versions

Retrieve and name the versions of an asset.

## Name an asset version

### Name an asset version

**POST** `/api/spaces/{space_uid}/assets/{asset_uid}/versions/{version_number}/name`

The Name an asset version request assigns a name to a specific version of an asset so that you can identify it later.

#### URL Parameters

- **space_uid** (required)
  Enter the uid of the space that you want to retrieve.
- **asset_uid** (required)
  Enter the uid of the asset that you want to retrieve.
- **version_number** (required)
  Enter the version number of the asset. The value must be a positive integer.

#### Query Parameters

- **locale** (optional)
  Enter the locale code, such as en-us, of the asset version you want to name.
- **workspace** (optional)
  The workspace to work in. Defaults to the space’s default workspace, so a request that omits this parameter cannot see an asset held in any other workspace and fails with 404. Pass the workspace uid whenever you work outside the default, for example when a workspace is linked to a branch other than main.

#### Headers

- **authorization** (optional)
  OAuth access token authentication. Pass the token in the authorization header as Bearer <token>. This header takes an OAuth access token. It does not take a management token, and management tokens are not supported by this API.

Authentication is required. Every request must carry either this header or the authtoken header; a request with neither is rejected.
- **authtoken** (optional)
  Contentstack authtoken authentication. Pass your Contentstack authtoken in the authtoken header.

This is your authtoken, not your stack api\_key and not a management token. OpenAPI classifies any credential sent in a header as an API key, which is why some documentation viewers label this scheme apiKey. That label refers to the transport, not to a Contentstack API key.

Authentication is required. Every request must carry either this header or the authorization header; a request with neither is rejected.
- **x-cs-api-version** (required)
  Enter the Assets API version. Default is 4.

#### Sample Response

```json
{
  "notice": "string"
}
```

## Delete an asset version name

### Delete an asset version name

**DELETE** `/api/spaces/{space_uid}/assets/{asset_uid}/versions/{version_number}/name`

The Delete an asset version name request removes the name assigned to a specific version of an asset.

#### URL Parameters

- **space_uid** (required)
  Enter the uid of the space that you want to retrieve.
- **asset_uid** (required)
  Enter the uid of the asset that you want to retrieve.
- **version_number** (required)
  Enter the version number of the asset. The value must be a positive integer.

#### Query Parameters

- **locale** (optional)
  Enter the locale code, such as en-us, of the asset version whose name you want to delete.
- **workspace** (optional)
  The workspace to work in. Defaults to the space’s default workspace, so a request that omits this parameter cannot see an asset held in any other workspace and fails with 404. Pass the workspace uid whenever you work outside the default, for example when a workspace is linked to a branch other than main.

#### Headers

- **authorization** (optional)
  OAuth access token authentication. Pass the token in the authorization header as Bearer <token>. This header takes an OAuth access token. It does not take a management token, and management tokens are not supported by this API.

Authentication is required. Every request must carry either this header or the authtoken header; a request with neither is rejected.
- **authtoken** (optional)
  Contentstack authtoken authentication. Pass your Contentstack authtoken in the authtoken header.

This is your authtoken, not your stack api\_key and not a management token. OpenAPI classifies any credential sent in a header as an API key, which is why some documentation viewers label this scheme apiKey. That label refers to the transport, not to a Contentstack API key.

Authentication is required. Every request must carry either this header or the authorization header; a request with neither is rejected.
- **x-cs-api-version** (required)
  Enter the Assets API version. Default is 4.

#### Sample Response

```json
{
  "notice": "string"
}
```

## Get all asset versions

### Get all asset versions

**GET** `/api/spaces/{space_uid}/assets/{asset_uid}/versions`

The Get all asset versions request fetches the list of all versions of a specific asset. Use the query parameters to filter named versions and control the details the response includes.

#### URL Parameters

- **space_uid** (required)
  Enter the uid of the space that you want to retrieve.
- **asset_uid** (required)
  Enter the uid of the asset that you want to retrieve.

#### Query Parameters

- **skip** (optional)
  The skip parameter skips a specific number of items in the output. For example, if there are 20 items and you want to skip the first 2 to get only the last 18 in the response body, specify 2 here.
- **limit** (optional)
  The limit parameter returns a specific number of items (between 0 and 100) in your response based on the value you provide.
- **locale** (optional)
  Enter the locale code, such as en-us, to fetch the versions of the asset in a specific locale.
- **named** (optional)
  Set to true to fetch only the versions that have a name assigned. Default is false.
- **include_count** (optional)
  Set to true to include the total number of versions in the response. Default is false.
- **include_updated_at** (optional)
  Set to true to include the last updated timestamp of each version. Default is false.
- **include_updated_by** (optional)
  Set to true to include the uid of the user who last updated each version. Default is false.
- **workspace** (optional)
  The workspace to work in. Defaults to the space’s default workspace, so a request that omits this parameter cannot see an asset held in any other workspace and fails with 404. Pass the workspace uid whenever you work outside the default, for example when a workspace is linked to a branch other than main.

#### Headers

- **authorization** (optional)
  OAuth access token authentication. Pass the token in the authorization header as Bearer <token>. This header takes an OAuth access token. It does not take a management token, and management tokens are not supported by this API.

Authentication is required. Every request must carry either this header or the authtoken header; a request with neither is rejected.
- **authtoken** (optional)
  Contentstack authtoken authentication. Pass your Contentstack authtoken in the authtoken header.

This is your authtoken, not your stack api\_key and not a management token. OpenAPI classifies any credential sent in a header as an API key, which is why some documentation viewers label this scheme apiKey. That label refers to the transport, not to a Contentstack API key.

Authentication is required. Every request must carry either this header or the authorization header; a request with neither is rejected.
- **x-cs-api-version** (required)
  Enter the Assets API version. Default is 4.

#### Sample Response

```json
{
  "count": 0,
  "relation": "string",
  "versions": [
    {
      "_version": 0,
      "_version_name": "string",
      "locale": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "updated_by": "string"
    }
  ]
}
```

## Get a specific asset version

### Get a specific asset version

**GET** `/api/spaces/{space_uid}/assets/{asset_uid}/versions/{version_number}`

The Get a specific asset version request fetches the details of a single version of an asset using its version number.

#### URL Parameters

- **space_uid** (required)
  Enter the uid of the space that you want to retrieve.
- **asset_uid** (required)
  Enter the uid of the asset that you want to retrieve.
- **version_number** (required)
  Enter the version number of the asset. The value must be a positive integer.

#### Query Parameters

- **locale** (optional)
  Enter the locale code, such as en-us, to fetch the asset version in a specific locale.
- **workspace** (optional)
  The workspace to work in. Defaults to the space’s default workspace, so a request that omits this parameter cannot see an asset held in any other workspace and fails with 404. Pass the workspace uid whenever you work outside the default, for example when a workspace is linked to a branch other than main.

#### Headers

- **authorization** (optional)
  OAuth access token authentication. Pass the token in the authorization header as Bearer <token>. This header takes an OAuth access token. It does not take a management token, and management tokens are not supported by this API.

Authentication is required. Every request must carry either this header or the authtoken header; a request with neither is rejected.
- **authtoken** (optional)
  Contentstack authtoken authentication. Pass your Contentstack authtoken in the authtoken header.

This is your authtoken, not your stack api\_key and not a management token. OpenAPI classifies any credential sent in a header as an API key, which is why some documentation viewers label this scheme apiKey. That label refers to the transport, not to a Contentstack API key.

Authentication is required. Every request must carry either this header or the authorization header; a request with neither is rejected.
- **x-cs-api-version** (required)
  Enter the Assets API version. Default is 4.

#### Sample Response

```json
{
  "_id": "string",
  "uid": "string",
  "object_type": "string",
  "title": "string",
  "description": "string",
  "file_name": "string",
  "parent_uid": "string",
  "path": [
    {
      "uid": "string",
      "title": "string"
    }
  ],
  "owner_uid": "string",
  "co_owners": [
    {
      "uid": "string",
      "name": "string"
    }
  ],
  "permanent_url": "string",
  "permanent_url_slug": "string",
  "content_type": "string",
  "asset_type_uid": "string",
  "file_size": 0,
  "tags": [
    "string"
  ],
  "is_dir": true,
  "asset_id": "string",
  "url": "string",
  "locale": "string",
  "dimensions": {
    "height": 0,
    "width": 0
  },
  "status": "IN_PROGRESS",
  "version": 0,
  "org_uid": "string",
  "space_uid": "string",
  "user_defined_fields": {},
  "visual_markups": [
    {
      "type": "Hotspot",
      "title": "string",
      "description": "string",
      "url": "http://example.com",
      "coordinates": {
        "x": 0,
        "y": 0,
        "width": 0,
        "height": 0
      }
    }
  ],
  "publish_details": [
    {
      "locale": "string",
      "environment": "string",
      "time": "2019-08-24T14:15:22Z",
      "user": "string",
      "version": 0,
      "action": "string",
      "job_id": "string",
      "scheduled_at": "2019-08-24T14:15:22Z",
      "workspace_uid": "string",
      "origin": "string"
    }
  ],
  "_version_name": {
    "title": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "updated_by": "string"
  },
  "created_by": "string",
  "updated_by": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "is_deleted": true
}
```