This is the API v2 documentation. API v2 is currently in preview state and not recommended for production use! Endpoints might change without prior notice. Read more about API v2 in our blog post.

API Documentation

Welcome to the CloudConvert API Documentation! This is the documentation for Version 2 of the API (/v2 prefix). For the documentation of /v1 endpoints please head over to the API v1 documentation.

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.

Formatting Requests

The CloudConvert API follows the basic standards for REST APIs. Requests and responses are JSON encoded.

You can find an example curl command for a POST request on the right.

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://api.sandbox.cloudconvert.com.

SDKs

At this point only the PHP SDK and node.js SDK is available for API v2. We will add SDKs for other programming languages in future. If you have created a SDK on your own, please let us know and we will list it here.

PHP cloudconvert-php/v3
PHP / Laravel cloudconvert-laravel
node.js cloudconvert-node/v2

CLI

The CloudConvert CLI uses API v2 and allows to perform basic conversions from the command line. It can be used to quickly test different options and their results.

API Endpoint

https://api.cloudconvert.com/v2

Example Request

$ curl -X POST "https://api.cloudconvert.com/v2/jobs" \
       -H "Authorization: Bearer API_KEY" \
       -H "Content-type: application/json" \
       -d '{
  ...
}'

Example Response

{
  "data": {
    ...
  }
}

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

User
user.read Allows to read your account data, remaining credits and usage charts.
user.write Allows to update your account data.
Tasks & Jobs
task.read Allows to read tasks and jobs.
task.write Allows to create, update and delete tasks and jobs.
Webhooks
webhook.read Allows to read the webhook settings.
webhook.write Allows to update the webhook settings.

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.

Changelog

21.8.2019 Upgraded the poppler engine to version 0.71.0.
13.8.2019 Upgraded the mupdf engine to version 1.16.1.
7.8.2019 Added optimize PNG and JPG feature.
6.8.2019 Added new optimize task endpoint with PDF compressing feature.
31.7.2019 Added versions 76 and 77 of the chrome engine.
The office default version was updated to 2019.
15.7.2019 The calibre default version was updated to 3.45.
11.7.2019 Added support for pot and potx files.
Jobs do now have an optional tag parameter. You can use it to link CloudConvert jobs with IDs withing your application scope.
28.6.2019 The ghostsript default version was updated to 9.27. The old version was marked as deprecated.
We now automatically sent deprecation warning mails if you are using an engine that was marked as deprecated.
23.6.2019 By default we hide now all credentials in API responses (such as GET /v2/task/ID).
19.6.2019 We have added a ignore_error option when creating jobs. This allows to continue jobs even if specific tasks are failing.
27.5.2019 Preview release of API v2.