Cloud API
Access and manage your Disguise Cloud organisation, drives, and contents.
Access and manage your Disguise Cloud organisation, drives, and contents.
Welcome to the Cloud API documentation. This section will guide you through the process of using the Cloud API to interact with your account, including your organisation, drives, and content. The Cloud API is a RESTful API that allows you to interact with the Cloud programmatically, to automate tasks, integrate with other systems, and more.
All endpoints (unless otherwise stated) use a JSON request and response format.
The Cloud API is versioned, and the current version is v1. The API is designed to be backwards-compatible, so you can be confident that your code will
continue to work as we release new versions of the API. However, we recommend that you always use the latest version of the API to take advantage of new
features and improvements.
You can tell which version of the API you are using by looking at the base URL. For example, the base URL for version 1 of the Management API is https://api.disguise.cloud/v1.
There are two separate API instances for the Cloud API: the Management API and the Drive API. The Management API allows you to interact with your account, organisation, and drives. The Drive API allows you to interact with the content in your drives, such as images, videos, and 3D models.
The instances are:
https://api.disguise.cloud/v1https://drive-api.disguise.cloud/v1It is usual to work with both APIs in tandem, as the Management API is used to manage your account and drives, while the Drive API is used to manage the content within your drives.
A typical workflow might involve retrieving a list of drives using the Management API, then using the Drive API to upload content to a specific drive.
All requests to the Cloud API must be authenticated. To authenticate your requests, you will need an API key. You can generate an API key in the Cloud Dashboard. Please see the Authentication section for more information on how to authenticate your requests.
The Cloud API has rate limits in place to prevent abuse. The rate limits are per API key and per API endpoint. If you exceed the rate limits, you will
receive a 429 Too Many Requests response. Please see the Rate Limits section for more information on the rate limits.
The Cloud API is a RESTful API, which means that it uses standard HTTP methods to interact with resources. The API supports the following HTTP methods:
| HTTP Method | Description |
|---|---|
| GET | Retrieve a resource or a list of resources |
| POST | Create a new resource |
| PATCH | Update an existing resource |
| DELETE | Delete a resource |
Resources are grouped by endpoints, following standard RESTful conventions. Each endpoint represents a
collection of resources, with endpoints ending in a noun (e.g. list endpoints - /drives, /content)
usually being collections of resources.
The exception to this are endpoints that represents an action to take on a given resource that falls outside of the regular CRUD lifecycle (e.g. Archive Drive, Request Upload).
Endpoints ending in an ID represent individual resources (e.g. retrieve endpoints - /drives/{{drive_id}}, /content/{{content_id}}).
As per RESTful conventions, GET and POST requests are made to list or action endpoints and GET, PATCH and DELETE requests are to retrieve endpoints.
Note: You may notice there are some create endpoints that fall outside the standard CRUD lifecycle that
usually would be included as per standard RESTful conventions (e.g. Create Folder,
Create Asset). These endpoints are separated as the underlying resource is
shared across multiple use cases, and this helps clarify the purpose and intent of the endpoint.
It also allows you to provide non-resource specific data that is required such as the upload_uuid when creating assets.
Status codes are used to indicate the success or failure of a request. The API uses the following status codes:
| Status Code | Description |
|---|---|
| 200 OK | The request was successful |
| 201 Created | The resource was created successfully |
| 204 No Content | The request was successful, but there is no content to return |
| 400 Bad Request | The request was invalid |
| 401 Unauthorized | The request was not authenticated |
| 403 Forbidden | The request was authenticated, but the user does not have permission to access the resource |
| 404 Not Found | The resource was not found |
| 429 Too Many Requests | The rate limit has been exceeded |
| 500 Internal Server Error | An error occurred on the server, please contact support |