API
Everything under /api/v1, header authentication, no session and no cookies. The machine
contract is openapi.yaml — response shapes, error codes and required scopes
live in the spec, because a contract test compares it with the router in both directions.
Two credentials
Authorization: Bearer <keyId>.<secret> application key (machine)
Authorization: Bearer pat_<id>.<secret> personal token (human, CLI)
The prefix decides (pat_), not the order of database lookups.
| Application key | Personal token | |
|---|---|---|
| Belongs to | an application and its organization | an account and organization |
| Sees | only its own application | every project of the organization |
/me type |
application |
user |
An application key used on another application's route returns 403 application_mismatch, not
404 — otherwise "no access" and "no such project" would look the same.
Scopes
| Operation | Scope |
|---|---|
GET /me, GET /projects, GET /projects/{project} |
none — a valid credential is enough |
POST /cli/device, POST /cli/token, POST /trial |
none — public: these endpoints are how a credential is obtained |
GET …/manifest |
translations:read |
GET …/translations/{locale}, GET …/translations/{locale}/suggestions, GET …/keys/diff, GET …/export/{locale}.{format}, GET …/status |
translations:read |
POST …/translations/{locale}, POST …/translation-keys, POST …/sync |
translations:write |
POST …/qa |
qa:read |
GET …/content, GET …/content/{key}, GET …/content/{key}/preview |
translations:read |
POST …/content |
translations:write |
POST /events |
translations:read |
POST …/translations/{locale}/ai |
ai:write |
GET /ai/jobs/{id} |
ai:read |
GET …/releases, GET …/releases/{id}, GET …/releases/{id}/artifacts/{locale}.json |
releases:read |
POST …/releases, POST …/releases/{id}/check |
releases:write |
POST …/releases/{id}/publish |
releases:publish |
GET /comments, GET /comments/{id} |
comments:read |
POST /comments, PUT /comments/{id}, POST /comments/{id}/replies |
comments:write |
GET /assignments, GET /assignments/{id} |
assignments:read |
POST /assignments, PUT /assignments/{id} |
assignments:write |
GET /glossary, GET /glossary/{id} |
glossary:read — personal token only |
POST /glossary, PUT /glossary/{id} |
glossary:write — personal token only |
GET /translation-memory, GET /translation-memory/{id} |
memory:read — personal token only |
POST /translation-memory, PUT /translation-memory/{id} |
memory:write — personal token only |
The table is checked against openapi.yaml by a test: every scope the API
uses must be listed here, and every operation here must exist in the spec. A publish with
force_reason additionally requires releases:force — that one is conditional, so it is not in
the table and not in x-required-scope.
Example
# Keep the token in an environment variable, not in the shell history.
export BABELHUB_TOKEN='pat_...'
curl -s https://your-panel-host/api/v1/me -H "Authorization: Bearer $BABELHUB_TOKEN"
{ "authenticated_as": "user", "organization": { "slug": "your-company" } }
The CLI push goes to POST /api/v1/projects/{project}/sync — the same endpoint babelhub push
uses, so a custom script needs no second path.
Errors and limits
| Status | When |
|---|---|
401 |
missing or invalid credential, inactive key, expired token |
403 |
missing scope, another application's key |
404 |
unknown application, language, key, project outside the organization, unknown route |
405 |
wrong method + Allow header |
422 |
validation: missing key/keys, bad body shape, batch > 500, language_not_assigned |
429 |
limiter: 120 requests / 60 s per credential, with Retry-After |
500 |
service failure — no details, stack only in the log |
The error body is always {"error":"…","message":"…"}. Every error is safe to retry — the
write is idempotent and a failed request changes nothing.
message is English and does not follow the account language: the same request must return
the same answer to every client. Branch on error, not on message.
Every /api/v1 response is JSON — including routing errors. An unknown route never returns HTML
with a stack trace.