API Documentation

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

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

A good start is trying out the Job Builder: It allows to generate and try out requests using a graphical interface. You can also have a look at the Quickstart Guide to get up and running quickly.

SDKs

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

Integrations

• Zapier
  There is a Zapier Integration of API v2 available. Zapier allows it to connect CloudConvert with 5,000+ apps and create automated workflows using a graphical interface.
• Microsoft Power Automate
  Build automated processes with flows in Microsoft Power Automate. Power Automate allows to automate repetitive, mundane tasks with ease. You can build even complex workflows involving multiple apps using "drag & drop" in a graphical interface.
• Make (formerly Integromat)
  Make 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
  n8n is an open source workflow automation tool. We have built a CloudConvert integration as 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 nearby you 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:

Sandbox API

Besides the Live API, CloudConvert has a Sandbox API. The sandbox API allows 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 be importing the file from a S3 bucket. The second task could be converting this file to a different format and the final task of the job could be exporting the file again to a 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 multiple files into CloudConvert for using them in other tasks. Examples for import tasks are downloading files from a URL or a S3 bucket. Imported files are only stored temporary.

Export tasks are used to export one or multiple output files from CloudConvert, for example by generating public URLs or by storing them on 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 used engine. Also, you can set a engine version to use. For example, you can set a fixed LibreOffice version to use which makes sure that this version is used, even if we update the default version of LibreOffice. There is an API for each task type available that shows the available engines, versions and their options.

Authentication

API Keys

To authenticate requests, you need to create an API key. 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 the access.

Available Scopes

OAuth 2.0 Clients

CloudConvert supports OAuth 2.0's authorization code grant flow and implicit grant flow to issue access tokens on behalf of users. You can create your OAuth 2.0 client here.

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

Errors and Rate Limiting

The CloudConvert API responses with standard HTTP status codes, such as 422 (invalid data), 500 (internal server error), 503 (temporary unavailable) or 429 (too many requests). An example response body of an 422 is given in the error section of this documentation.

Rate Limiting

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

These endpoints are currently rate limited:

• Creating tasks
• Creating jobs

Failed Jobs and Tasks

Jobs and tasks that completed with an error, do have status set to error. Further 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).