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 /convert | synchronous conversion — document in, document out (falls back to 202 + job id when it outlasts the server-side wait) |
POST /jobs | submit 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}/result | the converted document |
GET /jobs/{id}/source · /log | the original upload · the conversion log |
DELETE /jobs/{id} | cancel a queued/running job |
GET /me · GET /me/usage | your app's identity, quotas, restrictions, webhook secret · daily usage |
GET /formats · GET /health · GET /ready | supported 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 / 403 | bad key · admin-only endpoint or app restrictions |
404 / 410 | unknown job (or another app's) · artifacts expired |
409 | conflicting state (e.g. job not cancelable) |
413 / 422 | upload too large · validation or conversion failure (body carries error_code) |
429 | quota exhausted (jobs/day, jobs/minute, concurrency) |
503 / 507 | queue 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).