File conversion

The file-conversion API is a single async endpoint pair: submit a file with a target format, get back an ID, fetch the result when ready.

POST /convert, submit a conversion task

Uploads a file (or references one already in your destination) and queues it for conversion.

Request body (multipart/form-data)

Field	Required	Description
input	yes	The file to convert. One of: a multipart file upload, a public URL to fetch the file from, or a string path to an existing file in your destination’s storage. The extension must be one of the supported source formats.
output_format	yes	Target format extension (e.g. jpg, mp4, pdf). Must be a valid output for the given input. See the format matrix.
file_name	no	Custom name for the output file in storage. Defaults to {task_id}.{output_format}.
metadata	no	Up to 50 key-value pairs of your own data (4 KB max as JSON, string keys). Stored with the task and echoed back on GET /convert/{id} and in webhook payloads. Converterer never reads or interprets it: use it for order IDs, tenant IDs, or correlation keys.
options[…]	no	Conversion options. See the options reference. Use bracket syntax for nested keys (e.g. options[resize][width]=800).

Files up to 1 GB are accepted, for both uploads and URL inputs. Contact us if your workload needs a higher per-file limit.

URL input

Instead of uploading the file, pass a URL as the input value and Converterer fetches it server-side:

curl -u "$CONVERTERER_API_KEY:" \
  https://api.converterer.com/convert \
  -F "input=https://example.com/reports/q2.docx" \
  -F "output_format=pdf"

How the fetch behaves:

• The URL must be publicly reachable over HTTP(S). Private and internal addresses are refused.
• Up to 5 redirects are followed; the fetch times out after 300 seconds (10 seconds to connect).
• The file type is taken from the URL path or the response headers and validated like an upload.
• The fetch runs as ConvertererBot/1.0.

If the URL cannot be used, the submit request fails with 422 and the validation message tells you why: the URL is blocked, its file exceeds the size limit, or it is unreachable. Failures during the fetch itself surface on the task as an error_code of url_blocked, url_too_large, or url_unreachable.

Response: 201 Created

{
  "id": "9f1a8e7c-1b9b-4f0a-9d2c-1a2b3c4d5e6f",
  "status": "queued",
  "done": false,
  "object": "conversion-task"
}

Errors

• 401 Unauthorized, missing or invalid API key.
• 403 Forbidden, API key cannot create tasks (e.g. account suspended, over plan limits).
• 422 Unprocessable Entity, validation failure (unsupported format, bad option value, missing input).

GET /convert/{id}, fetch a conversion task

Returns the current status of a conversion task.

Response: 200 OK

{
  "id": "9f1a8e7c-1b9b-4f0a-9d2c-1a2b3c4d5e6f",
  "status": "delivered",
  "done": true,
  "object": "conversion-task",
  "file_name": "9f1a8e7c-1b9b-4f0a-9d2c-1a2b3c4d5e6f.pdf",
  "url": "https://cdn.example.com/converted/9f1a8e7c-1b9b-4f0a-9d2c-1a2b3c4d5e6f.pdf",
  "metadata": {
    "order_id": "ord_8817"
  }
}

• file_name is the object name in your destination’s storage.
• url appears only when the task is delivered and the destination can produce a public link (its public_base_url is set, or it uses public storage). See Storage destinations.
• metadata appears only if you set it on submission, echoed back verbatim.
• On a failed task, an error_code field identifies machine-readable failure reasons where available (currently the URL-input errors).

Errors

• 401, 403, 404, standard.

Polling responses

The public API returns a single shape as shown above; there’s no expanded vs. compact distinction. Poll the done boolean (status === "delivered") until the job finishes, or skip polling entirely and use webhooks for completion notifications.

Retrieving the converted file

When the task reaches delivered, the converted file is in your destination’s storage at the path you set with file_name, or {id}.{output_format} by default. You construct the URL or fetch the file directly from your bucket. See Storage destinations for the public-vs.-private bucket details.