feat(api): add a REST API with API keys and OpenAPI docs

FR
1d ago
+1582-59

Adds a REST API at /api/v1, so scripts and tools such as n8n can convert files without the web interface. Closes #363.

What it adds

  • Convert one file. POST /api/v1/convert takes a file and a target format and responds with the converted file.
  • Jobs for several files. POST /api/v1/jobs starts a job and returns 202 with a Location header. GET /api/v1/jobs/{id} reports each file's status and links its results, which download one by one (/files/{name}) or together as a tar (/archive). GET /api/v1/jobs lists jobs, newest first, and DELETE /api/v1/jobs/{id} removes a job with its files.
  • Formats. GET /api/v1/targets?from=docx lists what a format can become, and which converters can do it. GET /api/v1/converters lists every converter with what it reads and writes.
  • API keys. A new page at /account/api-keys creates and revokes keys. It's linked from the header and the account page. A key is shown once. Only its SHA-256 hash is stored, with a short prefix so people can tell keys apart, and the time it was last used. Requests send it as Authorization: Bearer <key> or X-API-Key: <key>.
  • Docs. An OpenAPI description at /api/v1/openapi.json, and Swagger UI at /api/v1/docs. Only the API is documented, not the web pages. The README gets an "API" section.

Errors are JSON: { "error": "<code>", "message": "<explanation>" }. For example, 422 unsupported_conversion names the converters that can do the conversion when the requested one can't.

Testing

  • 20 new tests in tests/api/api.test.ts, using the existing tests/preload.ts setup. They cover keys (including that only a hash is stored and revoking locks a key out), both ways of converting, jobs, downloads and archives, deletion, users not seeing each other's jobs, error responses, and the OpenAPI document.
  • bun run lint and bun run test pass (484 tests).
  • Built the Docker image and used every endpoint against it: created a key on the keys page, converted SVG to PNG, Markdown to Word and Word to PDF with curl, ran a two-file job, downloaded its files and archive, and deleted it.

Screenshots

Screenshot 2026-10-27 at 01 19 50 Screenshot 2026-10-27 at 01 20 51 Screenshot 2026-10-27 at 01 22 19