Authentication
Send your key in the X-API-Key header. Keys are scoped: each key sees only its own jobs — foreign job ids 404 — and job creation is limited by the key's daily and monthly quota (exceeding returns 429). Open deployments with no key configured skip auth entirely.
$ curl https://host/api/me -H "X-API-Key: tb_…"
{"role":"customer","daily_remaining":18,"monthly_remaining":184}
Endpoints
MethodPathPurpose
GET/api/healthdependency + capacity report
GET/api/convertersavailable conversions and input specs
POST/api/convertmultipart: converter, options (JSON), files → job
GET/api/jobsrecent jobs (scoped to the caller's key)
GET/api/jobs/{id}job state, includes live log tail
GET/api/jobs/{id}/files/{name}download one output
GET/api/jobs/{id}/archivedownload all outputs as a zip
DELETE/api/jobs/{id}delete a job and its files
GET/api/mecaller's role + remaining quota
POST/api/admin/keysissue a customer key (admin only)
GET/api/admin/keyslist keys with usage (admin only)
DELETE/api/admin/keys/{id}revoke a key (admin only)
Convert, poll, download
$ curl -X POST https://host/api/convert \
-H "X-API-Key: tb_…" \
-F converter=tex2docx \
-F 'options={"dpi":300,"eq_numbers":true}' \
-F tex=@paper.tex -F pdf=@paper.pdf -F assets=@figures.zip
{"id":"3f2a…","status":"queued"}
$ curl https://host/api/jobs/3f2a… -H "X-API-Key: tb_…" # poll until succeeded
$ curl -O https://host/api/jobs/3f2a…/files/paper.docx -H "X-API-Key: tb_…"
For the merge direction, upload tex + edited, and ideally the base .docx you originally sent out. Without a base, the compiled pdf is required so the base can be regenerated.
Issuing keys (self-hosted)
The admin key — set via MANUSCRIPTA_API_KEY — sees every job and manages customer keys. Customer keys are stored hashed; usage rows survive job cleanup, which is the metering a billing layer reads.
# 20 jobs/day, 200/month · 0 = unlimited
$ curl -X POST https://host/api/admin/keys -H "X-API-Key: $ADMIN" \
-d '{"label":"Nano Lab","daily_limit":20,"monthly_limit":200}'
{"id":"…","key":"tb_…","note":"Store the key now — it is never shown again."}
Configuration
Everything is an environment variable.
VariableDefaultMeaning
MANUSCRIPTA_MAX_UPLOAD_MB100upload size cap
MANUSCRIPTA_JOB_TIMEOUT_S600hard kill for any conversion
MANUSCRIPTA_WORKERS2parallel conversion slots
MANUSCRIPTA_JOB_TTL_H24janitor deletes jobs older than this
MANUSCRIPTA_API_KEYunsetunset = open; set = the admin key
MANUSCRIPTA_CORS01 allows cross-origin API consumers
Deploying for a lab or publisher?
talk to us about self-hosting →