---
title: "Cloud API"
description: "Learn how to use the Cloud API"
url: https://developer.disguise.one/cloud/introduction/
---

# Cloud API

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.

## Versioning

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`.

## API Instances

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:

-   **Management API**: `https://api.disguise.cloud/v1`
-   **Drive API**: `https://drive-api.disguise.cloud/v1`

It 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.

## Authentication

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](/cloud/authentication) section for more information on how to authenticate your requests.

## Rate Limits

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](/cloud/rate-limits) section for more information on the rate limits.

## RESTful API

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](/cloud/management/drive-archive/), [Request Upload](/cloud/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](/cloud/drive/create-folder/),  
[Create Asset](/cloud/drive/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

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 |