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

# Content

-   [Endpoints](#endpoints)
-   [Response Structure](#response-structure)
    -   [Versions](#versions)
    -   [Children](#children)
-   [Response Example](#response-example)
    -   [Folder](#folder)
    -   [File](#file)
    -   [Errors](#errors)
-   [Request Parameters](#request-parameters)
-   [Request Example](#request-example)

The `/content` endpoint of the Disguise Cloud Drive API returns information about the requested drive’s content. A piece of content represents any file or folder within a drive. The term **assets** are used to represent files, while folders are simply referred to as **folders**.

The endpoint structure is the same for both **files** and **folders**, please refer to the `type` field in the response to determine the type of content:

| Type | Description |
| --- | --- |
| **folder** | Represents a folder in the system, and will contain an array of `children` representing the contents of the folder. |
| **image** | Represents image files. Examples include .jpg, .png, etc. |
| **video** | Represents video files. Examples includes .mp4, .mov, etc. |
| **scene** | Represents 3D model files. Examples include .obj, .fbx, etc. |
| **previz** | Represents Previz files. Examples include the main file created by the Previz application or Previz files created by the Disguise Designer and uploaded to the cloud. |
| **file** | Represents all other file types that cannot be processed or previewed in the web interface. Examples include .zip, .txt, etc. |

While all fields are included in the response, some fields may be empty depending on the type of content.

Please Note

While the terms **content**, **assets**, and **folders** are used throughout this documentation, be aware that the API will often refer to all of these as **assets** in requests and responses as they all share the same underlying resource.

  

We have separated them out in the documentation and requests to make it easier to understand the different use cases but please ensure you verify the `type` field in the response to determine the type of content.

## Endpoints

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

Retrieve a list of content for the specified drive.

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

Retrieve details of specific piece of content by its unique identifier.

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

Update the details of specific piece of content by its unique identifier.

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

Delete a specific piece of content by its unique identifier. If deleting a folder, all child content will also be deleted.

## Response Structure

The responses from all `/content` endpoints include the following fields:

| 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

Versions represent different iterations of the content, applicable only to file based content.

Each version will have its own unique identifier and metadata. Please note that while all file based content have versions, the ability to add additional versions is only available for **Pro** and **Studio** accounts.

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.

To further interact with versions, please refer to the [Versions endpoint](/cloud/drive/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`). |

### Children

The `children` field is an array of child content items, applicable only to folders.

| Field | Type | Description |
| --- | --- | --- |
| **id** | string | The unique identifier of the child content. Can be used to further query the child content to get more details. |
| **name** | string | The name of the child content. |
| **type** | string | The type of the child content (e.g., `folder`, `file`, `image`, `scene`, `video`, `previz`). |
| **size\_bytes** | integer | The size of the child content in bytes. |

## Response Example

### Folder

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

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

```json
{
  "id": "1cb5e233-908b-4799-80d7-943b86d3916c",
  "drive_id": "3b5b9cab-073d-416a-bcf1-f2b3154fb0ee",
  "parent_id": null,
  "name": "My Folder",
  "versions": [],
  "is_locked": false,
  "locked_by_id": null,
  "uploaded_by_id": null,
  "url": null,
  "format": null,
  "thumbnail": null,
  "thumbnail_tiny": null,
  "type": "folder",
  "length": null,
  "width": null,
  "height": null,
  "dimensions": null,
  "size_bytes": 23925053,
  "status": "pending",
  "meta": null,
  "file_extension": null,
  "is_shared": false,
  "share_slug": null,
  "share_url": null,
  "description": null,
  "created_at": "2024-11-27T21:05:01.000000Z",
  "updated_at": "2024-12-03T21:03:03.000000Z",
  "children": [
    {
      "id": "4179dc26-88cb-49ab-af97-5a4ddc2ac446",
      "name": "light-streaks-01.jpg",
      "type": "image",
      "size_bytes": 4742353
    },
    {
      "id": "4b4ff0e4-8252-491b-ba7b-a41e572cedcf",
      "name": "notes.txt",
      "type": "file",
      "size_bytes": 11
    },
    {
      "id": "b34a1137-64af-4dea-89b9-521bc78b46d7",
      "name": "model.usdz",
      "type": "scene",
      "size_bytes": 3842733
    },
    {
      "id": "5636a1e6-e436-4722-b6c2-eea7727c9387",
      "name": "project_backup.zip",
      "type": "file",
      "size_bytes": 15339956
    }
  ]
}
```

### File

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

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

```json
{
  "id": "4179dc26-88cb-49ab-af97-5a4ddc2ac446",
  "drive_id": "3b5b9cab-073d-416a-bcf1-f2b3154fb0ee",
  "parent_id": "1cb5e233-908b-4799-80d7-943b86d3916c",
  "name": "light-streaks-01.jpg",
  "versions": [
    {
      "id": "26898d90-769f-4909-b1bd-d4b29cad7134",
      "asset_id": "4179dc26-88cb-49ab-af97-5a4ddc2ac446",
      "label": null,
      "thumbnail": "{{thumbnail_url}}",
      "version_number": 3,
      "filesize_bytes": 4742353,
      "type": "image",
      "status": "ready",
      "url": "{{file_url}}",
      "is_active": true,
      "created_at": "2024-12-03T21:02:24.000000Z",
      "updated_at": "2024-12-03T21:02:48.000000Z",
      "uploaded_by_user": "e4686083-413d-49df-ad02-0f000fbf7be1",
      "uploaded_by_user_status": "active"
    },
    {
      "id": "6d0ac632-1a3a-4968-9007-f3439af4e44b",
      "asset_id": "4179dc26-88cb-49ab-af97-5a4ddc2ac446",
      "label": null,
      "thumbnail": "{{thumbnail_url}}",
      "version_number": 2,
      "filesize_bytes": 4742353,
      "type": "image",
      "status": "ready",
      "url": "{{file_url}}",
      "is_active": false,
      "created_at": "2024-12-03T21:02:18.000000Z",
      "updated_at": "2024-12-03T21:02:31.000000Z",
      "uploaded_by_user": "e4686083-413d-49df-ad02-0f000fbf7be1",
      "uploaded_by_user_status": "active"
    },
    {
      "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": false,
      "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"
    }
  ],
  "is_locked": false,
  "locked_by_id": null,
  "uploaded_by_id": "e4686083-413d-49df-ad02-0f000fbf7be1",
  "url": "{{file_url}}",
  "format": "image/jpeg",
  "thumbnail": "{{thumbnail_url}}",
  "thumbnail_tiny": "{{thumbnail_tiny_url}}",
  "type": "image",
  "length": null,
  "width": null,
  "height": null,
  "dimensions": "7680 x 4320",
  "size_bytes": 4742353,
  "status": "ready",
  "meta": {
    "width": 7680,
    "format": "image/jpeg",
    "height": 4320,
    "dimensions": "7680 x 4320"
  },
  "file_extension": "jpg",
  "is_shared": false,
  "share_slug": null,
  "share_url": null,
  "description": null,
  "created_at": "2024-12-03T21:02:09.000000Z",
  "updated_at": "2024-12-03T21:03:13.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"
  }
}
```

When attempting to move content to a parent that cannot be found, the response will return a `404 Not Found` status code and the following JSON:

```json
{
  "error": {
    "message": "Parent not found",
    "details": "Ensure the parent is a folder that belongs to the same project."
  }
}
```

When attempting to move content to a parent that is not a folder, the response will return a `404 Not Found` status code and the following JSON:

```json
{
  "error": {
    "message": "Destination must be a folder.",
    "details": "Destination must be a folder."
  }
}
```

When attempting to patch content that is locked, the response will return a `404 Not Found` status code and the following JSON:

```json
{
  "error": {
    "message": "Content is locked",
    "details": "Content is locked"
  }
}
```

## Request Parameters

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

| Parameter | Type | Description |
| --- | --- | --- |
| **parent\_id** | string | The unique identifier of the parent content. Can be used to move the content to a new folder. |
| **name** | string | The name of the content. |
| **is\_locked** | boolean | Whether the content is locked. Changing this to true will prevent further updates or deletions until it is unlocked. |
| **description** | string | The description of the content. |

## Request Example

Below is an example of making a **PATCH** request to the `/content` endpoint to update the content’s title.

```bash
curl -X PATCH https://drive-api.disguise.cloud/v1/drives/{{drive_id}}/content/{{content_id}} \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "My New Folder Name",
  "description": "This is a new description for the folder."
}'
```