Conversion, as an endpoint you can curl.

What the API actually gives you

Eight things worth knowing before you write the first request. Every one of them is a behaviour of the running service, not a roadmap item.

• Synchronous when you want it, queued when you do not POST /jobs returns 201 straight away and runs the work after the response. Add ?wait=1 — or a Prefer: wait header — and the same call blocks and hands back the finished record instead.
• Jobs are task graphs, validated before anything runs Name your tasks, point each one at its input, and the server topologically sorts them. Missing inputs, cycles, unknown operations and jobs with no export are rejected with a 422 that names the offending task.
• Signed webhooks instead of polling job.created, job.finished and job.failed are delivered as HMAC-SHA256 signed POSTs, retried with backoff on 429 and 5xx, and at-least-once — so key your handler on data.id.
• The format matrix is queryable, not a marketing number GET /formats returns every route this build knows about, and GET /tools tells you which binaries are actually installed on the host answering you. Feature-detect instead of guessing.
• Four ways in, download links out Import from a multipart upload, a URL behind an SSRF guard, base64 or raw bytes. Export mints per-file download tokens that need no bearer key, plus HMAC-signed URLs with a TTL you choose.
• Limits you can read off the response Every response carries RateLimit-Limit, -Remaining and -Reset; a 429 carries Retry-After. Defaults are 600 requests a minute per key and 300 per client IP, both configurable.
• Run it yourself, on your own storage The API is a single PHP front controller over a filesystem job store. Bring it up with the bundled compose file, point FC_STORAGE at a volume, and no file ever leaves your infrastructure.
• Scoped keys, hashed at rest task.read, task.write and user.read are granted per key. Only the SHA-256 hash is stored, and verification walks every record so response timing never leaks which keys exist.

Scopes per key

Feature detection public

# Public routes. Ask the host what it can do instead of assuming.
curl -sS "$FC_API/formats?from=heic" | jq -r '.formats[0].to | join(" ")'
curl -sS "$FC_API/tools"

{
  "tools": {"ffmpeg": true, "libreoffice": true, "ghostscript": false},
  "installed": 2,
  "total": 3,
  "missing": ["ghostscript"]
}

Errors and rate limits

Success is the resource itself. Failure is always the same envelope, with a request_id that also appears in the server log line for that request.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
X-Request-Id: b6f0…

{
  "error": {
    "code": "invalid_task",
    "message": "task \"pdf\" names an unknown input: \"fetc\"",
    "details": ["fetch", "pdf"]
  },
  "request_id": "b6f0…"
}

Status codes 11 of them

A job whose tasks failed still returns 200. The status code describes the request; the status field describes the work. Check both.

Rate limits per minute

• 600 per API key Counted on the host, set by FC_RATE_LIMIT_*.
• 300 per client IP Applies before the key is even read.
• Per host, not per cluster N web containers give N times the limit unless they share the storage volume — which the bundled compose file does.

RateLimit-Limit: 600
RateLimit-Remaining: 594
RateLimit-Reset: 1785638460
Retry-After: 12