Skip to content

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

Open
Fredobumma wants to merge 4 commits into
C4illin:mainfrom
Fredobumma:feat/rest-api
Open

Fredobumma wants to merge 4 commits into
C4illin:mainfrom
Fredobumma:feat/rest-api

Conversation

@Fredobumma

Copy link
Copy Markdown

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

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 13 files

Reply to a comment to ask cubic a question or push back. It learns from your replies.

View guided diff | Re-trigger cubic

Comment thread src/converters/main.ts Resolved
Comment thread src/index.tsx Resolved
Comment thread src/pages/apiKeys.tsx Resolved
Comment thread src/pages/apiKeys.tsx Resolved
Comment thread src/api/jobs.ts Resolved
Comment thread README.md Resolved
Comment thread src/pages/apiKeys.tsx Resolved
Comment thread src/index.tsx Resolved
Comment thread tests/api/api.test.ts Resolved
Comment thread tests/api/api.test.ts Resolved

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 12 files (changes from recent commits).

Requires human review: Auto-approval blocked because this review re-detected 2 unresolved issues already reported by Cubic.

View guided diff | Re-trigger cubic

Comment thread src/api/jobs.ts Resolved
@C4illin

C4illin commented Nov 15, 2026

Copy link
Copy Markdown
Owner

What do you think about having api keys under account tab instead?

@Fredobumma

Copy link
Copy Markdown
Author

What do you think about having api keys under account tab instead?

So I'll move the keys into the account page, under the email and password form, and remove the separate page and the header link.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature Request] Is an REST API Available for this project?

2 participants