REST API overview
Call the transglot API from your own scripts and CI to push, pull, translate, check, publish and subscribe to events.
The transglot API covers everything the command line tool does, and more. It is scoped to a single project: the deploy token you send decides which one, so no URL carries a workspace or project identifier.
Base URL
https://api.transglot.ai/v1Every endpoint lives under /v1. The version is in the path and there is no version header to send. See Versioning for what can change inside /v1.
Authentication
Send a project deploy token as a bearer token on every request:
curl https://api.transglot.ai/v1/project \
-H "Authorization: Bearer $TRANSGLOT_TOKEN"{
"id": 12,
"name": "Acme Web",
"slug": "acme-web",
"source_locale": "en",
"locales": [
{
"locale": "de",
"name": "German",
"rtl": false,
"is_source": false,
"progress": { "total": 1204, "reviewed": 310, "human": 42, "ai": 820, "empty": 32, "translated": 1172, "humanBacked": 352, "percent": 97 }
},
{ "locale": "en", "name": "English", "rtl": false, "is_source": true, "progress": null }
],
"keys_count": 1204,
"message_syntax": "auto",
"icu_dialect": "icu4c",
"auto_translate": true,
"first_run_pending": false
}Each endpoint requires one ability on the token, such as pull or manage. Authentication lists them per endpoint.
Plan
API access needs the Starter plan or higher. A Free workspace cannot mint a deploy token, and a token stops working if the account moves to a plan without API access. It works again after an upgrade, with nothing to re-issue.
Content types
| Direction | Format |
|---|---|
| Request bodies | JSON with Content-Type: application/json, except POST /v1/push (multipart/form-data) and POST /v1/glossary/import (the raw CSV or TBX file as the body) |
| Responses | JSON, except GET /v1/pull and GET /v1/glossary/export, which return the file itself |
| Errors | application/problem+json, described in Errors |
A single resource comes back as a bare JSON object with no envelope, except the single-value reads and writes, which wrap theirs in row (or rows). Lists differ by endpoint: GET /v1/batches returns a bare array, while GET /v1/glossary, GET /v1/webhooks and GET /v1/webhooks/events wrap the list in data. Timestamps are ISO 8601 with an offset, for example 2026-10-12T09:41:00+00:00.
What the API covers
| Group | Endpoints | What it is for |
|---|---|---|
| Project | GET /v1/project | The project's languages, their progress and its settings that affect a push |
| Push and pull | POST /v1/push, GET /v1/pull | Upload a locale file, download a locale as a file |
| Translation | POST /v1/translate | Start a Glossa translation run |
| Batches | GET /v1/batches, GET /v1/batches/{batch}, POST .../retry-failed, POST .../cancel | Watch, retry and stop runs |
| Translations (single values) | GET /v1/translations, POST /v1/translations/batch, PUT /v1/translations | Read and write individual values by key name |
| Quality | POST /v1/qa/run | Start a quality check |
| CDN | POST /v1/cdn/publish, GET /v1/cdn/{project}/{locale}, GET /v1/cdn/{project}/{locale}/v{version} | Publish a locale, then read the bundle with a CDN key |
| Glossary | GET, POST /v1/glossary, PUT, DELETE /v1/glossary/{termId}, GET /v1/glossary/export, POST /v1/glossary/import, POST /v1/glossary/extract | Manage terms |
| Webhooks | GET, POST /v1/webhooks, DELETE /v1/webhooks/{webhook}, GET /v1/webhooks/events | Subscribe endpoints to project events |
Every endpoint, with its parameters, request bodies and response shapes, is in the API reference.
A typical CI flow
Push the source file
curl https://api.transglot.ai/v1/push \
-H "Authorization: Bearer $TRANSGLOT_TOKEN" \
-F file=@locales/en.json \
-F format=json_flat \
-F locale=enWith automatic translation on, a push that changes source strings starts a translation run and returns it as batch.
Wait for the run
curl https://api.transglot.ai/v1/batches/4822 \
-H "Authorization: Bearer $TRANSGLOT_TOKEN"Poll until status is completed, completed_with_errors, failed or cancelled, or subscribe to the batch.completed webhook instead of polling.
Pull each locale
curl "https://api.transglot.ai/v1/pull?format=json_flat&locale=fr" \
-H "Authorization: Bearer $TRANSGLOT_TOKEN" \
-D headers.txt -o locales/fr.jsonCheck X-Entry-Count in headers.txt before you commit the file: an untranslated locale comes back as a valid empty file.
The command line tool and the GitHub Action do all of this for you, with retries and rate-limit handling built in.