---
title: "Versions Endpoint"
description: "Details about the Versions endpoint for Disguise Cloud"
url: https://developer.disguise.one/cloud/drive/versions/
---

# Versions

-   [Endpoints](#endpoints)
-   [Response Structure](#response-structure)
-   [Response Example](#response-example)
    -   [Success](#success)
    -   [Errors](#errors)
-   [Request Parameters](#request-parameters)
-   [Request Example](#request-example)

The `/versions` endpoint of the Disguise Cloud Drive API returns information about the versions of a specific asset. Each version represents a different iteration of the asset.

Please note that only **Pro** and **Studio** users have access to create new versions of an asset. All assets will have at least one version, which is the original upload.

Important

If you upload a new version to an asset that is on an organisation on the **Starter** plan, it will remove the previous version and replace it with the new version. This is because the **Starter** plan only supports a single version of an asset.

## Endpoints

`GET https://drive-api.disguise.cloud/v1/drives/{{drive_id}}/content/{{content_id}}/versions`

Retrieve a list of versions for the specified asset.

`GET https://drive-api.disguise.cloud/v1/drives/{{drive_id}}/content/{{content_id}}/versions/{{version_id}}`

Retrieve details of a specific version by its unique identifier.

`PATCH https://drive-api.disguise.cloud/v1/drives/{{drive_id}}/content/{{content_id}}/versions/{{version_id}}`

Update the details of a specific version by its unique identifier.

`DELETE https://drive-api.disguise.cloud/v1/drives/{{drive_id}}/content/{{content_id}}/versions/{{version_id}}`

Delete a specific version by its unique identifier. You can not delete the last remaining version of an asset. If you delete the active version, the next most recent version will become active.

## Response Structure

The responses from the `/versions` endpoint include the following fields:

| Field | Type | Description |
| --- | --- | --- |
| **id** | string | The unique identifier of the version. |
| **asset\_id** | string | The unique identifier of the asset associated with the version. |
| **label** | string | The label of the version, if set. |
| **thumbnail** | string | The URL of the thumbnail image of the version, if applicable. |
| **version\_number** | integer | The version number. This will increment with each new version. |
| **filesize\_bytes** | integer | The size of the version in bytes. |
| **type** | string | The type of the version (e.g., `file`, `image`, `scene`, `video`, `previz`). |
| **status** | string | The status of the version (e.g., `pending`, `ready`). Refers to if the content has been finished processing (such as video encoding). |
| **url** | string | The URL of the version. |
| **is\_active** | boolean | Whether the version is the content’s active version. The active version will be the one the outer level’s properties will refer to. |
| **created\_at** | datetime | The date and time when the version was created. |
| **updated\_at** | datetime | The date and time when the version was last updated. |
| **uploaded\_by\_user** | string | The unique identifier of the user who uploaded the version. |
| **uploaded\_by\_user\_status** | string | The status of the user who uploaded the version (e.g., `active`, `deleted`). |

## Response Example

```bash
curl -X GET https://drive-api.disguise.cloud/v1/drives/{{drive_id}}/content/{{content_id}}/versions \
-H "Authorization: Token YOUR_API_TOKEN"
```

### Success

A successful response will return a `200 OK` status code and the following JSON:

Please note this example excludes the pagination wrapper around the response. Please refer to the [pagination documentation](/cloud/pagination) for more information.

```json
[
  {
    "id": "e6989338-a01a-43fc-8b37-d7cb62974eaa",
    "asset_id": "4179dc26-88cb-49ab-af97-5a4ddc2ac446",
    "label": null,
    "thumbnail": "{{thumbnail_url}}",
    "version_number": 1,
    "filesize_bytes": 4742353,
    "type": "image",
    "status": "ready",
    "url": "{{file_url}}",
    "is_active": true,
    "created_at": "2024-12-03T21:02:09.000000Z",
    "updated_at": "2024-12-03T21:02:16.000000Z",
    "uploaded_by_user": "e4686083-413d-49df-ad02-0f000fbf7be1",
    "uploaded_by_user_status": "active"
  }
]
```

### Errors

If the drive is not found, the API will return a `404 Not Found` status code and the following JSON:

```json
{
  "error": {
    "message": "Drive not found",
    "details": "Drive not found"
  }
}
```

If the content is not found, the API will return a `404 Not Found` status code and the following JSON:

```json
{
  "error": {
    "message": "Content not found",
    "details": "Content not found"
  }
}
```

If the version is not found, the response will return a `404 Not Found` status code and the following JSON:

```json
{
  "error": {
    "message": "Content Version not found",
    "details": "Content Version not found"
  }
}
```

## Request Parameters

The following parameters can be used with the `/versions` endpoint for **PATCH** requests:

| Parameter | Type | Description |
| --- | --- | --- |
| **label** | string | The label for the version. |
| **set\_active** | boolean | Set to true to make this version active. This will deactivate all other versions. Note that setting this to false will do nothing, you must set true on another asset version to change the active version. |

## Request Example

Below is an example of making a **PATCH** request to the `/versions` endpoint to update the version’s label and  
setting it as the active version.

```bash
curl -X PATCH https://drive-api.disguise.cloud/v1/drives/{{drive_id}}/content/{{content_id}}/versions/{{version_id}} \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "label": "Version 1",
  "set_active": true
}'
```