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.

Quickstart Guide Job Builder

SDKs

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

PHP Laravel node.js Ruby Python Java .NET CLI

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 Make (formerly Integromat) 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.

Region Endpoints

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.

Endpoint Region
https://api.cloudconvert.com Automatically selects nearest processing region, unless overriden by account region settings.
https://eu-central.api.cloudconvert.com eu-central
https://us-east.api.cloudconvert.com us-east

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.

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

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

{
  "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.

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 on the right.

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

Error Response

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 Limited Response

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"
}

Changelog

18.09.2024 Added option page_format for capture-website tasks to set a paper format like A4, A3, Letter etc.
Added gifsicle engine for resizing animated GIF files.
02.09.2024 Added export/upload tasks to upload output files to any URL via HTTP PUT.
24.08.2024 Added ffmpeg_nvidia engine for GPU based video encoding.
05.08.2024 Updated chrome and calibre default versions.
12.07.2024 New engine pdfium for PDF to image conversions, which enables faster and more accurate conversions.
05.07.2024 Updated pdftron and archivetool default versions.
13.06.2024 Updated pdf2htmlex default version.
27.05.2024 Updated chrome and mupdf default versions.
08.05.2024 Updated chrome default version.
25.01.2024 Updated chrome, mupdf, libreoffice default versions.
08.01.2024 Updated ffmpeg and pdftron default versions.
19.10.2023 Updated chrome and pdftron default versions.
24.04.2023 Updated chrome, imagemagick and mupdf default versions.
09.03.2023 Updated pdftron default version.
01.03.2023 Added a sheet option to Excel conversions which allows converting only a specific worksheet by name.
23.02.2023 Added experimental support for creating WebVTT files for thumbnail tasks.
14.02.2023 Updated calibre, mupdf, ffmpeg, exiftool and poppler default versions.
09.02.2023 Updated libreoffice, inkscape and pandoc default versions.
07.02.2023 Added new tagging parameter to the export/s3 operation which allows setting custom S3 tags.
Updated chrome default version.
11.11.2022 Added new timestamp parameter to the thumbnail operation: Instead of automatically selecting meaningful frames you can set a fixed timestamp for creating the thumbnail.
Updated pdftron default version.
23.08.2022 Added new parameters to the watermark operation: font_width_percent and image_width_percent allow it to set the watermark size based on a percentage of the available space.
17.08.2022 Support WEBP output format for thumbnail operations.
Updated ffmpeg default version to 5.1.0.
Updated libreoffice default version.
04.08.2022 Added include_markup setting to Office to PDF conversions.
Updated calibre default version.
22.07.2022 Updated inkscape default version.
Updated mupdf default version.
28.06.2022 Updated office default version.
Updated pdftron default version.
07.06.2022 Added a new endpoint for synchronous job creation.
Added a redirect query parameter to the job status endpoint which makes the response redirect to the export URL.
19.05.2022 Add the new watermark operation to create watermarks for PDF, image and video files. Several convert operations have new watermark parameters.
Added fit parameter to video conversions. It allows adjusting the method of resizing videos.
Updated poppler default version.
11.05.2022 Deprecation of the bcl engine. It has been replaced by the superior pdftron-pdf2word engine.
21.04.2022 Updated default versions of libreoffice, inkscape, ffmpeg and qpdf.
13.04.2022 Changed the default engine for PDF to Office conversions to pdftron-pdf2word, pdftron-pdf2excel and pdftron-pdf2powerpoint. Read more about this in our blog post.
30.03.2022 Release of the Signed URL feature. Signed URLs allow converting files on demand only using URL query parameters. Read the full documentation about this feature for details.
28.03.2022 Changed the base URL for the synchronous API endpoints to https://sync.api.cloudconvert.com (endpoints to wait for job/task completion). The old endpoints will continue to work until further notice. We will notify affected customers when this changes.
24.02.2022 Added channels and sample_rate options for audio conversions.
21.02.2022 Added flatten_signatures option for optimize PDF operation.
Updated fontforge default version.
Added woff2 converter for TTF -> WOFF2.
03.01.2022 API v1 shutoff as announced by the deprecation timeline.
Updated default version of chrome to version 97.
27.12.2021 Updated default version of poppler.
02.12.2021 Add possibility to encrypt PDFs via PDF -> PDF conversions.
30.11.2021 Updated default versions of calibre, exiftool, mozjpeg, pandoc and pngquant.
19.11.2021 Updated ffmpeg default version to 4.4.1.
Updated mupdf default version to 1.19.0.
Updated imagemagick default version to 7.1.0.
Added inkscape version to 1.1.1.
17.11.2021 Added the bookmarks option to DOC/DOCX -> PDF conversions to automatically create bookmarks from headings.
04.11.2021 Add dynamic webhooks when creating jobs.
29.04.2021 Add the raw import method.
08.03.2021 Updated graphicsmagick default version to 1.3.36.
Updated pdf2htmlex default version to 0.18.8.
05.03.2021 Updated imagemagick default version to 7.0.11.
Updated 3heights default version to 6.12.
Updated poppler default version to 20.09.
Updated ffmpeg default version to 4.3.2.
Updated chrome default version to 90. Starting from Chrome version 90, the device_scale_factor defaults to 2 which creates HDPI / retina screenshots. For the old behavior, set device_scale_factor to 1.
Updated inkscape default version to 1.0.2.
Updated libreoffice default version to 7.0.4.
03.03.2021 Added the new metadata/write operation to write metadata.
Release of the .NET SDK.
05.02.2021 Added the use_print_areas setting for Excel conversions. When enabling this setting, it only converts the selected print area of a worksheet.
29.01.2021 Added a new device_scale_factor setting for HTML -> PNG/JPG conversions. It allows to create "retina" / hDPI screenshots by increasing the value to 2.
18.01.2021 Added a new transparent_background setting for HTML -> PNG conversions to use transparent instead of white background.
17.11.2020 New chrome default version 88.
30.10.2020 Updated the default chrome version to 87. Deprecated versions 80 and older.
Updated the default libreoffice version to 7.0.2.
Updated the default inkscape version to 1.0.1.
13.10.2020 Add the base64 import method.
8.10.2020 Add Metadata operation to extract file metadata such as page numbers or image/video resolution.
16.9.2020 There is a new timeout parameter for tasks. It allows to set a timeout in seconds after the task will be automatically cancelled.
20.6.2020 We have added the new Thumbnail API which allows to create thumbnails of nearly any video, documents or image format.
We have upgraded the libreoffice and imagemagick engine to versions.
5.6.2020 The chrome engine was updated. Additionally, we have added header_template and footer_template options to enable custom headers/footers.
8.3.2020 We have added the option to assign webhook endpoints to specific API keys. This makes it easier to separate production, staging and testing environments. You can assign API keys to webhooks in your webhook settings.
7.1.2020 Updated the default engine versions of imagemagick, libreoffice, calibre and 3heights.
Release of API v2.
21.12.2019 Upload requests from import/upload tasks do now require to follow redirects using the Location header. Most HTTP clients should do this by default. We have updated the documentation regarding this.
16.11.2019 Added /tasks/{ID}/wait and /jobs/{ID}/wait endpoints. These endpoints can be used to wait until a task/job completes.
5.11.2019 New chrome version 78. Chrome versions below 77 got deprecated.
1.10.2019 New option archive_multiple_files for export/url tasks allow it to automatically ZIP multiple output files.
12.9.2019 Add operation to create archives.
9.9.2019 The default engine for svg to png/jpg was changed to chrome.
The default engine for pdf to jpg/tiff was changed to poppler.
3.9.2019 The payload attribute is not included in task responses any more by default. It can be shown manually using the ?include=payload query parameter.
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.