API

A small, predictable REST surface under /api/v1. Authenticate with an API key in the Authorization header (Bearer lsv_...); keys are issued per app by an admin.

Endpoints

POST /convertsynchronous conversion — document in, document out (falls back to 202 + job id when it outlasts the server-side wait)
POST /jobssubmit a job (optional webhook_url), 202 with the job id
GET /jobs · GET /jobs/{id}list / inspect jobs: status, timings, engine, event timeline
GET /jobs/{id}/resultthe converted document
GET /jobs/{id}/source · /logthe original upload · the conversion log
DELETE /jobs/{id}cancel a queued/running job
GET /me · GET /me/usageyour app's identity, quotas, restrictions, webhook secret · daily usage
GET /formats · GET /health · GET /readysupported targets · liveness (+ version) · readiness incl. pool state

Admin-keyed apps additionally get /api/v1/admin/*: app and key management, all-app job views, usage reports, pool status/restart/ping.

Example: submit, poll, download

curl -H "Authorization: Bearer $KEY" \
     -F file=@report.docx -F target_format=pdf \
     https://convert.example.com/api/v1/jobs
# -> {"job_id": "77a704ed-...", "status": "queued"}

curl -H "Authorization: Bearer $KEY" https://convert.example.com/api/v1/jobs/$ID
# -> {"status": "succeeded", "engine": "pool", "duration_ms": 146, ...}

curl -H "Authorization: Bearer $KEY" -o report.pdf \
     https://convert.example.com/api/v1/jobs/$ID/result

Webhook callback

When a job with a webhook_url finishes, the server POSTs a JSON body signed with the app's secret:

X-Libreserv-Event: job.finished
X-Libreserv-Signature: sha256=<hex hmac of the raw body>

{"job_id": "...", "status": "succeeded", "src_filename": "report.docx",
 "target_format": "pdf", "engine": "pool", "out_bytes": 15099,
 "duration_ms": 3003, "created_at": "...", "finished_at": "..."}

Errors

401 / 403bad key · admin-only endpoint or app restrictions
404 / 410unknown job (or another app's) · artifacts expired
409conflicting state (e.g. job not cancelable)
413 / 422upload too large · validation or conversion failure (body carries error_code)
429quota exhausted (jobs/day, jobs/minute, concurrency)
503 / 507queue unreachable · spool disk below the free-space floor

Machine-readable docs

Generated from the code and kept in sync by the test suite: OpenAPI spec · Postman collection. Your own server also serves them live (Swagger UI at /docs, the rendered reference in the admin UI's Docs section).