CloudConvertdocs
API Reference

Jobs

Create, list, show, wait for and delete jobs.

Create job Async

Create a job with one ore more tasks.

POSThttps://api.cloudconvert.com/v2/jobs

This endpoint is asynchronous and immediately responds after job creation with a job in status processing. There is also a synchronous version of this endpoint available.

Authentication

Authorization
header required
The Authorization header expects a Bearer token with the task.write scope.

Body

tasks
object required
The tasks of the job, which are typically an import task, a conversion task and an export task. The keys of the object are the names of the tasks. You can name these tasks however you want, but only alphanumeric characters, - and _ are allowed in the task names.
tag
string
An arbitrary string to identify the job. Does not have any effect and can be used to associate the job with an ID in your application.
webhook_url
string
A webhook that is used for this single job only. The url will receive a job.finished or job.failed event. We do recommend using account wide webhooks which can be created via the dashboard.
You can use the Job Builder to generate and try out job payloads.

Example Body

{
  "tasks": {
    "import-my-file": {
      "operation": "import/s3"
    },
    "convert-my-file": {
      "operation": "convert",
      "input": "import-my-file",
      "input_format": "docx",
      "output_format": "pdf",
      "pages": "1-2",
      "optimize_print": true
    },
    "export-my-file": {
      "operation": "export/s3",
      "input": "convert-my-file"
    }
  },
  "tag": "myjob-123"
}

Response

The endpoint returns the created job in processing status. You can find details about the job model response in the documentation about the show jobs endpoint.

Create job and wait Sync

Create a job and block until the job is completed. This is the synchronous version of the create job endpoint.

POSThttps://sync.api.cloudconvert.com/v2/jobs
We do not recommend using this for long running jobs (e.g. video encodings). Your network stack might automatically time out requests if there is not data transferred for a longer time. As a good practice, please avoid to block your application until a CloudConvert job completes. There might be cases in which we need to queue your job which results in longer processing times than usual. Using an asynchronous approach with webhooks is beneficial in such cases.

Authentication

Authorization
header required
The Authorization header expects a Bearer token with the task.write scope.

Body

tasks
object required
The tasks of the job, which are typically an import task, a conversion task and an export task. The keys of the object are the names of the tasks. You can name these tasks however you want, but only alphanumeric characters, - and _ are allowed in the task names.
tag
string
An arbitrary string to identify the job. Does not have any effect and can be used to associate the job with an ID in your application.
redirect
boolean
When set to true the response will a be a redirect to the export URL of the job. Using this parameter requires that the job has an export/url task.
You can use the Job Builder to generate and try out job payloads.

Example Body

{
  "tasks": {
    "import-my-file": {
      "operation": "import/url",
      "url": "https://..."
    },
    "convert-my-file": {
      "operation": "convert",
      "input": "import-my-file",
      "input_format": "docx",
      "output_format": "pdf",
      "pages": "1-2",
      "optimize_print": true
    },
    "export-my-file": {
      "operation": "export/url",
      "input": "convert-my-file"
    }
  },
  "tag": "myjob-123",
  "redirect": true
}

Response

The endpoint returns the completed job in finsihed or error status. You can find details about the job model response in the documentation about the show jobs endpoint.

If redirect was set to true, it redirects to the output file of the job (a 302 redirect with the Location header pointing to the output file).

Show job Async

Show a job status.

GEThttps://api.cloudconvert.com/v2/jobs/{ID}

This endpoint is asynchronous and immediately responds the job status, even if the job has not completed yet. There is also a synchronous version of this endpoint available.

Authentication

Authorization
header required
The Authorization header expects a Bearer token with the task.read scope.

Query Parameters

redirect
boolean
When set to true the response will a be a redirect to the export URL of the job. Using this parameter requires that the job has an export/url task.

Response

The job status, including tasks:

id
string
The ID of the job.
tag
string
Your given tag of the job.
status
string
The status of the job. Is one of waiting, processing, finished or error.
created_at
string
ISO8601 timestamp of the creation of the job.
started_at
string
ISO8601 timestamp when the job started processing.
ended_at
string
ISO8601 timestamp when the job finished or failed.
tasks
array
List of tasks that are part of the job. You can find details about the task model response in the documentation about the show tasks endpoint.

If redirect was set to true, it redirects to the output file of the job (a 302 redirect with the Location header pointing to the output file).

Example Response

{
"data": {
  "id": "9a160154-58e2-437f-9b6b-19d63b1f59e3",
  "tag": "myjob-123",
  "status": "processing",
  "created_at": "2018-09-19T14:42:58+00:00",
  "started_at": "2018-09-19T14:42:58+00:00",
  "tasks": [
    {
      "id": "1f34c1b5-9ee8-4c8c-890f-bf44cda1deb7",
      "operation": "convert",
      "status": "finished",
      "credits": null,
      "message": null,
      "code": null,
      "created_at": "2018-09-19T14:42:58+00:00",
      "started_at": "2018-09-19T14:42:58+00:00",
      "ended_at": null,
      "result": {
        "files": [
          {
            "filename": "output.pdf"
          }
        ]
      },
      "links": {
        "self": "https://api.cloudconvert.com/v2/tasks/h451E6HMhG"
      }
    },
    {
      "id": "48c6e72b-cb8e-4ecc-bf3d-ead5477b4741",
      "operation": "export/url",
      "status": "finished",
      "credits": null,
      "message": null,
      "code": null,
      "created_at": "2018-09-19T14:42:58+00:00",
      "started_at": null,
      "ended_at": null,
      "result": {
        "files": [
          {
            "filename": "output.pdf",
            "url": "https://storage.cloudconvert.com/48c6e72b-cb8e-4ecc-bf3d-ead5477b4741/output.pdf"
          }
        ]
      },
      "links": {
        "self": "https://api.cloudconvert.com/v2/tasks/Xhrek8bGGq"
      }
    }
  ],
  "links": {
    "self": "https://api.cloudconvert.com/v2/jobs/Xh56hvvMhG"
  }
}
}

Wait for job Sync

Wait until the job status is completed and return the job status. This is the synchronous version of the show job endpoint.

GEThttps://sync.api.cloudconvert.com/v2/jobs/{ID}
We do not recommend using this for long running jobs (e.g. video encodings). Your network stack might automatically time out requests if there is not data transferred for a longer time. As a good practice, please avoid to block your application until a CloudConvert job completes. There might be cases in which we need to queue your job which results in longer processing times than usual. Using an asynchronous approach with webhooks is beneficial in such cases.

Authentication

Authorization
header required
The Authorization header expects a Bearer token with the task.read scope.

Query Parameters

redirect
boolean
When set to true the response will a be a redirect to the export URL of the job. Using this parameter requires that the job has an export/url task.

Response

The finished or failed job, including tasks. You can find details about the job model response in the documentation about the show job endpoint.

If redirect was set to true, it redirects to the output file of the job (a 302 redirect with the Location header pointing to the output file).

HTTP/1.1 302 FOUND
Location: https://storage.cloudconvert.com/48c6e72b-cb8e-4ecc-bf3d-ead5477b4741/output.pdf

List jobs

List all your jobs.

GEThttps://api.cloudconvert.com/v2/jobs

Authentication

Authorization
header required
The Authorization header expects a Bearer token with the task.read scope.

Query Parameters

filter[status]
string
The result will be filtered to include only jobs with a specific status (processing, finished or error).
filter[tag]
string
The result will be filtered to include only jobs with a tag.
include
array
Include tasks in the result.
per_page
number
Number of tasks per page, defaults to 100.
page
number
The result page to show.

Response

The list of jobs. You can find details about the job model response in the documentation about the show jobs endpoint.

Example Response

{
  "data": [
    {
      "id": "9a160154-58e2-437f-9b6b-19d63b1f59e3",
      "tag": "myjob-123",
      "status": "processing",
      "created_at": "2018-09-19T14:42:58+00:00",
      "started_at": "2018-09-19T14:42:58+00:00",
      "links": {
        "self": "https://api.cloudconvert.com/v2/tasks/Xh56hvvMhG"
      }
    },
    {
      "id": "e8d19289-f8f0-4e83-928a-4705606b086b",
      "status": "processing",
      "created_at": "2018-09-19T14:42:58+00:00",
      "started_at": "2018-09-19T14:42:58+00:00",
      "links": {
        "self": "https://api.cloudconvert.com/v2/tasks/2h56hvvMhG"
      }
    }
  ],
  "links": {
    "first": "https://api.cloudconvert.com/v2/jobs?page=1",
    "last": null,
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "path": "https://api.cloudconvert.com/v2/jobs",
    "per_page": 100,
    "to": 2
  }
}

Delete job

Delete a job, including all tasks and data. Requires the task.write scope.

DELETEhttps://api.cloudconvert.com/v2/jobs/{ID}

Jobs are deleted automatically 24 hours after they have ended.

Authentication

Authorization
header required
The Authorization header expects a Bearer token with the task.write scope.

Response

An empty response with HTTP Code 204.

Quickstart Guide

Typical implementation flow of the CloudConvert API

Tasks

Create, list, show, wait for, cancel, retry and delete tasks.