API
Authentication
The API is HTTP and JSON at https://api.convert.dev/v1. Every request sends an API key as a bearer token, except the ones that read the catalog.
Send the key
Put the key in the Authorization header. Each key belongs to one project, and a request sees only that project's files and jobs. See API keys to make one.
A key can be made with fewer scopes: files:read, files:write, jobs:read and jobs:write. Reading needs the read scope of its resource, and anything else the write one. A request outside the key's scopes fails with forbidden, and the message names the scope it needs.
GET /v1/catalog and GET /v1/targets need no key. Without a key, any other request fails with unauthorized and the message missing API key. A key that is wrong or revoked gives invalid API key.
$ export CV_API_KEY=cv_sk_…Set your key once. Every cv command reads it.
$ curl https://api.convert.dev/v1/jobs?limit=1 \ -H "Authorization: Bearer $CV_API_KEY"response5 lines
{ "object": "list", "data": [{"object": "job", "id": "job_01JC9W…", "status": "done", …}], "next_cursor": "…"}Errors
Every error has the same shape: an error with its code, a message for people, retryable, and param when one field of the request is at fault. suggestions and edits come when they apply.
The code says what to do next, and Error codes lists them all. The HTTP status follows the code.
| Status | Codes |
|---|---|
| 400 | invalid_request, invalid_options, invalid_edits |
| 401 | unauthorized |
| 402 | insufficient_balance |
| 403 | forbidden, storage_limit |
| 404 | not_found |
| 405 | invalid_request, when the path does not take the method. Allow lists the methods it takes. |
| 409 | conflict, not_ready |
| 413 | too_large |
| 422 | unsupported_conversion, unsupported_elements, input_corrupted, input_encrypted, ocr_required, unrecognized_format |
| 429 | rate_limited, concurrency_limit |
| 500 | resource_limit, engine_failed, internal |
| 504 | timeout |
A job that fails after it started is not an HTTP error. Its status is failed and the job carries the same error.
Every answer has a request-id header, such as req_01JC9W5K2T7M4Q8V1N6R3H9XBF. Send it with a report, and support can find the request.
$ curl -X POST https://api.convert.dev/v1/jobs \ -H "Authorization: Bearer $CV_API_KEY" \ -H "Content-Type: application/json" \ -d '{"inputs": ["file_01JC9W…"], "to": "mp3"}'response9 lines
{ "error": { "code": "unsupported_conversion", "message": "there is no conversion from docx to mp3", "param": "to", "retryable": false, "suggestions": ["pdf", "docx", "odt", "rtf", "docm"] }}Versions
/v1 only grows. New fields and new values can appear in responses, so ignore the ones you do not know. A request with a field the API does not know fails with invalid_request and the message unknown field, so typos do not pass unseen.
Ids start with what they name, such as file_ and job_. Times are RFC 3339 in UTC.
Updated 3 November 2026