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.