--- title: "Create Version Endpoint" description: "Details about the Create Version endpoint for Disguise Cloud" url: https://developer.disguise.one/cloud/drive/create-version/ --- # Create Version - [Endpoints](#endpoints) - [Response Structure](#response-structure) - [Versions](#versions) - [Response Example](#response-example) - [Success](#success) - [Errors](#errors) - [Request Parameters](#request-parameters) - [Request Example](#request-example) The `/version` endpoint of the Disguise Cloud Drive API allows you to create a new version of an existing asset within a specified drive. A version represents a new iteration of an asset within a drive. For instructions on how to upload the version, please see [How to Upload](/cloud/drive/request-upload#how-to-upload). ## Endpoints `POST https://drive-api.disguise.cloud/v1/drives/{{drive_id}}/content/{{content_id}}/version` Create a new version of an existing asset within the specified drive. The content ID is the asset you wish to version. ## Response Structure A successful response from the `/version` endpoint will be the same as the **Content** endpoint, but without the pagination wrapper. | Field | Type | Description | | --- | --- | --- | | **id** | string | The unique identifier of the content. | | **drive\_id** | string | The unique identifier of the drive. | | **parent\_id** | string | The unique identifier of the parent content, if applicable. Root folders will be the only piece of content that is missing this field. | | **name** | string | The name of the content. | | **versions** | array | A list of versions of the content. See the Versions table for more information. | | **is\_locked** | boolean | Whether the content is locked. When locked, the content can not be updated or deleted. | | **locked\_by\_id** | string | The unique identifier of the user who locked the content, if applicable. | | **uploaded\_by\_id** | string | The unique identifier of the user who uploaded the content, if applicable. | | **url** | string | The URL of the content, if applicable. | | **format** | string | The format of the content, if applicable. | | **thumbnail** | string | The URL of the thumbnail image of the content, if applicable. | | **thumbnail\_tiny** | string | The URL of the tiny thumbnail image of the content, if applicable. | | **type** | string | The type of the content (e.g., `folder`, `file`, `image`, `scene`, `video`, `previz`). | | **length** | integer | The length of the content, if applicable. | | **width** | integer | The width of the content, if applicable. | | **height** | integer | The height of the content, if applicable. | | **dimensions** | string | The dimensions of the content, if applicable. | | **size\_bytes** | integer | The size of the content in bytes. For folders, this will be the total size of all content in the folder. | | **status** | string | The status of the content (e.g., `pending`, `ready`). Refers to if the content has been finished processing (such as video encoding). | | **meta** | object | Additional metadata about the content, if applicable. Data structure is not guaranteed. | | **file\_extension** | string | The file extension of the content, if applicable. | | **is\_shared** | boolean | Whether the content is shared. | | **share\_slug** | string | The share slug of the content, if applicable. Only applies if the content was shared previously. | | **share\_url** | string | The share URL of the content, if applicable. Only applies if the content was shared previously. | | **description** | string | The description of the content, if applicable. | | **created\_at** | datetime | The date and time when the content was created. | | **updated\_at** | datetime | The date and time when the content was last updated. | | **children** | array | A list of child content items see the Children table for more information. | ### Versions | 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 POST https://drive-api.disguise.cloud/v1/drives/{{drive_id}}/content/{{content_id}}/version \ -H "Authorization: Token YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "My Asset Version", "file_extension": "png", "upload_uuid": "5c43e95e-11da-4a3b-953f-e0d0452f26dd" }' ``` ### Success A successful response will return a `201 Created` with the following JSON: **Please Note:** After an asset is uploaded, it will be processed. This will result in a `file` type and a status of `pending` until the processing is complete, and is expected behaviour. Once processing is complete, the asset will update to the proper type (such as `image`) with a status of `active`. ```json { "id": "b448945a-3d80-44d5-a2ed-8ec760955676", "drive_id": "3b5b9cab-073d-416a-bcf1-f2b3154fb0ee", "parent_id": "c71df693-d1ff-461d-9da6-b9f1ee9c6748", "name": "My Asset Version.png", "versions": [ { "id": "74878933-0ad8-4f37-abaa-6837009bb3ed", "asset_id": "b448945a-3d80-44d5-a2ed-8ec760955676", "label": null, "thumbnail": null, "version_number": 2, "filesize_bytes": null, "type": "image", "status": "pending", "url": "{{file_url}}", "is_active": true, "created_at": "2024-12-10T19:55:05.000000Z", "updated_at": "2024-12-10T19:55:06.000000Z", "uploaded_by_user": "e4686083-413d-49df-ad02-0f000fbf7be1", "uploaded_by_user_status": "active" }, { "id": "0ef21921-80ad-4a37-9097-7fc67c44f141", "asset_id": "b448945a-3d80-44d5-a2ed-8ec760955676", "label": null, "thumbnail": "{{file_url}}", "version_number": 1, "filesize_bytes": 11495995, "type": "image", "status": "ready", "url": "{{file_url}}", "is_active": false, "created_at": "2024-12-10T19:32:54.000000Z", "updated_at": "2024-12-10T19:32:58.000000Z", "uploaded_by_user": "e4686083-413d-49df-ad02-0f000fbf7be1", "uploaded_by_user_status": "active" } ], "is_locked": false, "locked_by_id": null, "uploaded_by_id": "e4686083-413d-49df-ad02-0f000fbf7be1", "url": "{{file_url}}", "format": null, "thumbnail": null, "thumbnail_tiny": null, "type": "image", "length": null, "width": null, "height": null, "dimensions": null, "size_bytes": null, "status": "pending", "meta": null, "file_extension": "png", "is_shared": false, "share_slug": null, "share_url": null, "description": null, "created_at": "2024-12-10T19:32:54.000000Z", "updated_at": "2024-12-10T19:55:06.000000Z", "children": null } ``` ### 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 you try to create a version before uploading a file, the API will return a `400 Bad Request` status code and the following JSON: ```json { "error": { "message": "Asset not found in storage", "details": "Please ensure the upload_uuid is correct and the file is uploaded" } } ``` If you try to upload a file that does not match the existing asset type, the API will return a `400 Bad Request` status code and the following JSON: ```json { "error": { "message": "Cannot upload to selected location", "details": "File type does not match the asset type" } } ``` ## Request Parameters The following parameters can be used with the `/version` endpoint for **POST** requests: | Parameter | Type | Description | | --- | --- | --- | | **name** | string | The name of the version to be created. | | **file\_extension** | string | The file extension of the version. | | **upload\_uuid** | string | The UUID of the uploaded file. | ## Request Example Below is an example of making a **POST** request to the `/version` endpoint to create a new version of an asset within a drive: ```bash curl -X POST https://drive-api.disguise.cloud/v1/drives/{{drive_id}}/content/{{content_id}}/version \ -H "Authorization: Token YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "My Asset Version", "file_extension": "png", "upload_uuid": "5c43e95e-11da-4a3b-953f-e0d0452f26dd" }' ```