Home/API
Developers

Convert files
over HTTP.

Same engine as the web app · 30+ formats One keyed POST, JSON responses, 1-hour retention, no account. Built for scripts, SaaS backends, and automation tools.

Overview

The Convert API is a thin HTTP layer over the same conversion engine that powers the Formatly web app — the same 30+ format pairs, the same privacy model. You POST a file and a target format, poll a job status, and download the result. No SDK, no webpage, no account: just curl (or any HTTP client) and a key.

All endpoints live under /api/v1/. Responses are JSON with explicit HTTP status codes. A future breaking change would ship as /api/v2/, so integrations stay stable.

Authentication

Every request carries your key as a bearer token:

Authorization: Bearer YOUR_API_KEY

Keys are issued on request — see Contact. There is no self-serve signup, which keeps the accountless model intact. A missing or invalid key returns 401.

POST /api/v1/convert

Submit one file for conversion as multipart/form-data.

fileThe file to convert (required, up to 20 MB).
target_formatThe output format, e.g. pdf, png, docx, json (required).
conversion_optionsOptional JSON string of per-conversion options (same options the web converter accepts).
curl -X POST https://formatly.app/api/v1/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@report.docx" \
  -F "target_format=pdf"

Returns 202 Accepted — the job is queued:

{
  "job_id": "b1c2…",
  "token": "9f8e…",
  "status": "PENDING",
  "target_format": "pdf",
  "original_filename": "report.docx",
  "status_url": "/api/v1/status/b1c2…",
  "expires_at": "2026-07-18T12:00:00Z",
  "retention_seconds": 3600
}

One file per request. For many files, submit them in parallel within your concurrency cap.

GET /api/v1/status/<job_id>

Poll the job. The lifecycle is PENDING → PROCESSING → SUCCESS (or FAILURE). Authenticate with the same key that created the job — another key gets 404 (jobs are never leaked across keys).

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://formatly.app/api/v1/status/b1c2…

On success the response includes a download_url:

{
  "job_id": "b1c2…",
  "status": "SUCCESS",
  "target_format": "pdf",
  "original_filename": "report.docx",
  "download_url": "/api/v1/download/b1c2…/9f8e…",
  "expires_in_seconds": 3400,
  "retention_seconds": 3600
}

Downloading

Fetch the finished file from the token-scoped URL returned by the status call:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -o result.pdf \
  https://formatly.app/api/v1/download/b1c2…/9f8e…

The file and its source are deleted 1 hour after conversion, so download within the window.

Rate limits & errors

Each key has a daily request cap and a concurrent-job cap (defaults 100/day and 3 concurrent; per-key overrides available). Errors are JSON with a standard status code:

400Bad request — missing file/target_format, or an unsupported conversion pair.
401Missing or invalid API key.
404Job not found, or it belongs to another key.
413File exceeds the 20 MB limit.
429Daily or concurrent limit reached — retry shortly.
503Service temporarily unavailable.

Privacy

The API inherits the web app's privacy model exactly: files auto-delete after 1 hour, are never used to train any AI model, and no analytics are run on file contents. Job status is scoped to the key that created it.

Full walkthrough

# 1. Submit
JOB=$(curl -s -X POST https://formatly.app/api/v1/convert \
  -H "Authorization: Bearer $KEY" \
  -F "file=@report.docx" -F "target_format=pdf" | jq -r .job_id)

# 2. Poll until SUCCESS
curl -s -H "Authorization: Bearer $KEY" \
  https://formatly.app/api/v1/status/$JOB

# 3. Download
curl -s -H "Authorization: Bearer $KEY" -o result.pdf \
  https://formatly.app/api/v1/download/$JOB/TOKEN

FAQ

How do I get an API key? Keys are issued on request — there's no self-serve signup, matching Formatly's accountless model. Contact us and we'll mint an opaque bearer token for you. A key can be disabled instantly on our side without affecting your integration's code.

What formats are supported? The same 30+ conversion pairs as the web app — documents, images, spreadsheets, ebooks, data formats, audio/video, and more. The API runs the identical engine, so any pair listed on the Formats page works with the same target_format value used in the converter.

What are the rate limits? Each key has a daily request cap and a concurrent-job cap (defaults are 100 requests/day and 3 concurrent jobs; per-key overrides are available). Files are capped at 20 MB each. Over-limit requests return HTTP 429. The limits are approximate under bursts and are for abuse-prevention, not billing.

How long are files kept? The same one hour as the web app. Both the uploaded file and the converted output are automatically deleted after 1 hour. Download the result within that window; after it, the download URL returns an expired state.

Is the API free? The API is available at no charge within the per-key rate limits during the current phase. It uses the same privacy model as the web app: files are never used to train any AI model, and no analytics are run on file contents.

Get started