REST API
Coming soonAPI reference
The full API reference will be auto-generated from our OpenAPI 3.1 spec the moment the surface is stable. We'd rather ship a placeholder than fake-doc endpoints that might still move. In the meantime, here's the shape, what it'll cover, and what to do today.
Shape (subject to change)
REST over HTTPS. JSON in, JSON out. Authorization: ApiKey <prefix>.<secret> header on every request. Versioned at the path: /v1/.... Rate-limited per token; the response carries the usual X-RateLimit-* headers.
curl 1# every endpoint takes an API key in the Authorization header2curl https://api.verbumia.ca/v1/projects \3 -H "Authorization: ApiKey vrb_live_<prefix>.<secret>" 5{ "data": [{ "id": "proj_xxx", "name": "Checkout", … }] }API keys come from Org Settings → API Keys in the dashboard. The same key works for the CLI, the MCP server, and direct REST calls — the API just consumes the bearer.
Resources you'll see at launch
These are the resources the V1 API will expose. The exact shape — fields, error codes, pagination — lands when we publish the OpenAPI spec.
| Resource | What it represents | V1 ops |
|---|---|---|
| Projects | Workspaces. Create, list, archive, transfer ownership. | GET · POST · PATCH · DELETE |
| Locales | Project-scoped locale set. Add a locale, mark it default, enable/disable for clients. | GET · POST · PATCH · DELETE |
| Namespaces | Logical buckets of keys per project (e.g. "checkout", "common"). | GET · POST · PATCH · DELETE |
| Keys | Translation keys with their description, screenshot URLs, max-length, plural rules. | GET · POST · PATCH · DELETE |
| Translations | Per-locale value of a key. Draft, in-review, approved states; revision history. | GET · POST · PATCH · DELETE |
| Missing keys | The runtime SDK queue. List, group by frequency, mark as triaged. | GET · PATCH |
| Webhooks | Subscribe to translation events. V2. | V2 |
What to do today
Almost everything you'd reach for the API for is already exposed through the CLI, the MCP server, or the runtime SDK. Use them — when the API ships, your code can swap to direct HTTP calls without changing what it actually does.
Live OpenAPI for early devs
If you're running the Verbumia backend locally, the live OpenAPI 3.1 spec is exposed at:
local backend Point Stoplight, Swagger UI, Insomnia, Postman, or any OpenAPI-aware tool at that URL. The shape is moving — that's why this page is a placeholder — but it's the source of truth right now if you want to explore endpoints early.
When does the public reference land?
The public OpenAPI spec will be served at https://api.verbumia.ca/openapi.json as soon as the V1 surface is frozen. From there, this page will switch from a placeholder to a fully-rendered reference (Stoplight or a similar viewer over the spec) — no marketing copy, just every endpoint, every payload, every error code, generated from source.