# API Documentation

> Welcome to the CloudConvert API

Welcome to the CloudConvert API Documentation! This is the documentation for version 2 of the API (`/v2` prefix).

On this page, you will find general information about the terminology and about formatting and authenticating requests.
You can use the menu on the left to jump directly to the endpoint documentation.

A good start is trying out the [Job Builder](https://cloudconvert.com/job-builder): It allows you to generate and try out requests using a graphical interface.
You can also have a look at the [Quickstart Guide](https://cloudconvert.com/docs/raw/getting-started/quickstart-guide.md) to get up and running quickly.

## SDKs

For API v2, official PHP, Node.js, Python, Ruby, Java and .NET SDKs are available.

<card-group className="grid-cols-2,sm:grid-cols-4">
<card icon="code-php" target="_blank" title="PHP SDK" to="https://github.com/cloudconvert/cloudconvert-php">



</card>

<card icon="code-laravel" target="_blank" title="Laravel SDK" to="https://github.com/cloudconvert/cloudconvert-laravel">



</card>

<card icon="code-nodejs" target="_blank" title="Node.js SDK" to="https://github.com/cloudconvert/cloudconvert-node">



</card>

<card icon="code-python" target="_blank" title="Python SDK" to="https://github.com/cloudconvert/cloudconvert-python">



</card>

<card icon="code-ruby" target="_blank" title="Ruby SDK" to="https://github.com/cloudconvert/cloudconvert-ruby">



</card>

<card icon="code-java" target="_blank" title="Java SDK" to="https://github.com/cloudconvert/cloudconvert-java">



</card>

<card icon="code-dotnet" target="_blank" title=".NET SDK" to="https://github.com/cloudconvert/cloudconvert-dotnet">



</card>

<card icon="code-bash" target="_blank" title="CLI" to="https://github.com/cloudconvert/cloudconvert-cli">



</card>
</card-group>

## Integrations

- **Zapier**<br />


There is a [Zapier integration](https://zapier.com/apps/cloudconvert) for API v2 available.
Zapier allows you to connect CloudConvert with 5,000+ apps and create automated workflows using a graphical interface.
- **Microsoft Power Automate**<br />


Build automated processes with flows in [Microsoft Power Automate](https://powerautomate.microsoft.com/en-us/connectors/details/shared_cloudconvert/cloudconvert/).
Power Automate allows you to automate repetitive, mundane tasks with ease.
You can build complex workflows involving multiple apps using drag and drop in a graphical interface.
- **Make (formerly Integromat)**<br />

[Make](https://www.make.com/en/integrations/cloudconvert?pc=cloudconvert&utm_source=cloudconvert&utm_medium=partner&utm_campaign=cloudconvert-partner-program) is integrated with the CloudConvert API v2.
Thanks to the handy Make scenario builder, you can drag and drop your desired apps together to create powerful workflows without writing any code.
- **n8n**<br />

[n8n](https://n8n.io) is an open-source workflow automation tool.
We have built a [CloudConvert integration](https://n8n.io/integrations/cloudconvert/) as a certified community node.

## Base URL and Region Endpoints

The base URL of the API is `https://api.cloudconvert.com/v2`.

By default, CloudConvert automatically selects the nearest processing region based on your IP address.
You can use a specific region by using the region-specific endpoints or setting a fixed region in your account settings.

The main endpoints are:

<table>
<thead>
  <tr>
    <th>
      Endpoint
    </th>
    
    <th>
      Region
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        https://api.cloudconvert.com
      </code>
    </td>
    
    <td>
      Automatically selects the nearest processing region, unless overridden by account region settings.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        https://eu-central.api.cloudconvert.com
      </code>
    </td>
    
    <td>
      <code>
        eu-central
      </code>
      
      : Germany
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        https://us-east.api.cloudconvert.com
      </code>
    </td>
    
    <td>
      <code>
        us-east
      </code>
      
      : Virginia, USA
    </td>
  </tr>
</tbody>
</table>

## Sandbox API

Besides the Live API, CloudConvert has a Sandbox API.
The sandbox API allows you to perform unlimited jobs and tasks without consuming your credits.
The only limitation is that it only allows a limited set of whitelisted files.
The sandbox API is meant to be used for development purposes and integration tests.

The base URL of the Sandbox API is `https://sandbox.api.cloudconvert.com/v2`.

## Terminology

### Jobs & Tasks

Processing files is done via **jobs** in the terminology of the CloudConvert REST API.
Each job consists of one or more **tasks**.

For example, the first task of a job could import a file from an S3 bucket.
The second task could convert this file to a different format, and the final task of the job could export the file back to an S3 bucket.

It would also be possible to have multiple conversions and multiple export tasks within a single job.
This is useful if you want to convert a file and create a thumbnail at the same time, for example.

### Import & Export Tasks

An **import task** is a task that imports one or more files into CloudConvert for use in other tasks.
Examples of import tasks are downloading files from a URL or an S3 bucket.
Imported files are only stored temporarily.

**Export tasks** are used to export one or more output files from CloudConvert, for example by generating public URLs or by storing them in your S3 bucket.
Typically, each job has at least one import and one export task.

### Engine & Engine Versions

For some tasks, there are multiple **engines** available.
For example, it is possible to convert DOCX files with the `office` engine or the `libreoffice` engine.
The available options differ based on the selected engine.
You can also set an **engine version** to use.
For example, you can set a fixed LibreOffice version, which ensures that this version is used even if we update the default version of LibreOffice.
An API is available for each task type that shows the available engines, versions and their options.

## Authentication

### API Keys

To authenticate requests, you need to [create an API key](https://cloudconvert.com/dashboard/api/v2/keys).
API keys do not expire unless you revoke them.
Requests are authenticated using the `Authorization: Bearer API_KEY` header.

When creating an API key, you can select scopes to limit access.

### Available Scopes

<table>
<thead>
  <tr>
    <th>
      Category
    </th>
    
    <th>
      Scope
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      User
    </td>
    
    <td>
      <code>
        user.read
      </code>
    </td>
    
    <td>
      Allows you to read your account data, remaining credits and usage charts.
    </td>
  </tr>
  
  <tr>
    <td>
      User
    </td>
    
    <td>
      <code>
        user.write
      </code>
    </td>
    
    <td>
      Allows you to update your account data.
    </td>
  </tr>
  
  <tr>
    <td>
      Tasks & Jobs
    </td>
    
    <td>
      <code>
        task.read
      </code>
    </td>
    
    <td>
      Allows you to read tasks and jobs.
    </td>
  </tr>
  
  <tr>
    <td>
      Tasks & Jobs
    </td>
    
    <td>
      <code>
        task.write
      </code>
    </td>
    
    <td>
      Allows you to create, update and delete tasks and jobs.
    </td>
  </tr>
  
  <tr>
    <td>
      Webhooks
    </td>
    
    <td>
      <code>
        webhook.read
      </code>
    </td>
    
    <td>
      Allows you to read the webhook settings.
    </td>
  </tr>
  
  <tr>
    <td>
      Webhooks
    </td>
    
    <td>
      <code>
        webhook.write
      </code>
    </td>
    
    <td>
      Allows you to update the webhook settings.
    </td>
  </tr>
</tbody>
</table>

### OAuth 2.0 Clients

CloudConvert supports OAuth 2.0's [authorization code grant flow](https://tools.ietf.org/html/rfc6749#section-4.1) and [implicit grant flow](https://tools.ietf.org/html/rfc6749#section-4.2) to issue access tokens on behalf of users.
You can create your OAuth 2.0 client [here](https://cloudconvert.com/dashboard/api/v2/clients).

Your web or mobile app should redirect users to the following URL:
`https://cloudconvert.com/oauth/authorize`. Access tokens can be obtained via: `https://cloudconvert.com/oauth/token`.

## Errors and Rate Limiting

The CloudConvert API responds with standard HTTP status codes, such as `422` (invalid data), `500` (internal server error), `503` (temporarily unavailable) or `429` (too many requests).
An example response body for a `422` error is given below:

```json
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "message": "The given data was invalid.",
  "code": "INVALID_DATA",
  "errors": {
    "tasks": [
      "The tasks field is required."
    ]
  }
}
```

### Rate Limiting

Some endpoints enforce dynamic rate limiting.
These endpoints return the `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers.
If the limit is reached, a `429` error is returned, and there is a `Retry-After` header with the time in seconds to wait before the next request.

These endpoints are currently rate limited:

- Creating tasks
- Creating jobs

```json
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
Retry-After: 60

{
  "message": "Too many attempts",
  "code": "TOO_MANY_REQUESTS"
}
```

### Failed Jobs and Tasks

Jobs and tasks that fail have their `status` set to `error`.
More information about the error can be obtained via the `message` and `code` attributes of the task resource.

Please do not automatically retry tasks.
CloudConvert internally already retries tasks if there are retryable errors (such as network errors).

<code-collapse name="Error Response">

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": "9a160154-58e2-437f-9b6b-19d63b1f59e3",
    "tag": "myjob-123",
    "status": "error",
    "created_at": "2026-05-08T07:45:49+00:00",
    "started_at": "2026-05-08T07:45:49+00:00",
    "ended_at": "2026-05-08T07:45:50+00:00",
    "tasks": [
      {
        "id": "1f34c1b5-9ee8-4c8c-890f-bf44cda1deb7",
        "operation": "convert",
        "status": "error",
        "credits": null,
        "message": "Failed to open the file",
        "code": "OPEN_FAILED",
        "created_at": "2026-05-08T07:45:49+00:00",
        "started_at": "2026-05-08T07:45:49+00:00",
        "ended_at": "2026-05-08T07:45:50+00:00",
      }
    ]
  }
}
```

</code-collapse>