# General Translation Platform: Overview
URL: https://generaltranslation.com/en-GB/docs/platform/openapi/overview.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Call the public General Translation API endpoints and download the OpenAPI spec.

Use the General Translation API to build custom automation workflows.

The CLI handles most API calls for you. Use the [`@generaltranslation/api` TypeScript client](/docs/platform/core/reference/api-client) for generated request and response types, or call endpoints directly when you need custom automation.

The OpenAPI spec defines these endpoints in machine-readable format.

## API basics [#api-basics]

### Base URL

All endpoints, including runtime translation with `POST /v2/projects/{projectId}/translate`, are available under `https://api.gtx.dev`.

### Authentication

Authenticate with an API key in the standard `Authorization` header.

```bash
curl https://api.gtx.dev/v2/projects/PROJECT_ID \
  -H "Authorization: Bearer gtx-api-..." \
  -H "gt-api-version: 2026-10-08.v1"
```

Choose the key scope that matches your workflow:

* **Project** with prefix `gtx-api-`: bound to one project and usable in any environment, subject to its permissions
* **Organisation** with prefix `gtx-org-`: works across projects in its bound Organisation, subject to its permissions

The path selects what a request acts on: `/v2/projects/{projectId}/...` the project, `/v2/orgs/{orgId}/...` the Organisation, and `/v2/context-groups/{groupId}/...` the Organisation that owns the group. Discovery endpoints (`GET /v2/orgs` and `GET /v2/projects`) do not need an ID. The key must have access to the selected project or Organisation, so a project key works only on its own project and on the Context Groups assigned to it.

Keep API keys out of deployed browser and mobile bundles.

(See [API keys](/docs/platform/dashboard/reference/api-keys) for how to create and scope API keys).

### Permissions

Most endpoints require a permission on the request identity. [List Organisations](/docs/platform/openapi/reference/organizations/list-orgs), [List Projects](/docs/platform/openapi/reference/projects/list-projects), and [Get a Project](/docs/platform/openapi/reference/projects/get-project) need no resource permission beyond access to the returned Organisation or project. Both Organisation and project keys support **All** or **Custom** permissions in the Dashboard, limited to permissions the creator can grant. The [project API-key endpoint](/docs/platform/openapi/reference/api-keys/create-project-api-key) lets you select permissions or omit the selection to grant all project permissions you can delegate. Write permissions do not include Read. Project keys cannot hold Organisation permissions (`org:*`), `project:api_keys:read`, or `project:api_keys:write`, so the endpoints that require them need an Organisation key.

Common permissions:

* `org:projects:create` for creating projects with `POST /v2/orgs/{orgId}/projects`.
* `project:api_keys:read` for listing and reading project API keys.
* `project:api_keys:write` for creating project API keys with `POST /v2/projects/{projectId}/api-keys` and deleting them.
* `org:assets:write` for uploading fonts with `POST /v2/orgs/{orgId}/assets`.
* `project:files:read` for downloading files; reading file metadata and status; listing branches and branch files; and reading jobs.
* `project:files:write` for uploading source files and translations; overwriting translations; publishing; creating and updating branches; setting tags; and moving files.
* `project:translations:enqueue` for translating files with `POST /v2/projects/{projectId}/files/translate`.
* `project:translations:generate` for runtime translation.
* `project:context:read` for reading the Context Groups assigned to the project, their Glossary and Custom Prompts, and exports.
* `project:context:write` for generating context, and for editing the Glossary and Custom Prompts of the Context Groups assigned to the project, importing content into them, and reordering them.
* `org:context:read` for reading every Context Group in the Organisation, their Glossary and Custom Prompts, project assignments, and exports.
* `org:context:write` for creating, updating, and deleting Context Groups and their content, importing content, and assigning, unassigning, and reordering groups on projects.
* `project:write` for updating project settings.

The Context Management endpoints that read or edit a group&#39;s content, and those that list, read, or reorder a project&#39;s groups, accept either the Organisation permission or the project permission on a project the group is assigned to. Listing an Organisation&#39;s groups, creating, updating, and deleting a group, and assigning and unassigning it require the Organisation permission. A group the request identity cannot act on returns the same `403` as a group that does not exist.

### Versioning

Send the `gt-api-version` header with every request to choose the API contract.

```bash
-H "gt-api-version: 2026-10-08.v1"
```

* Endpoints whose reference page marks the header as required return `400` without it or with an older version.
* The other endpoints use the oldest supported version when the header is missing, and return their errors as plain text rather than JSON.

To read an older version&#39;s endpoints, select it in the API version menu at the top of any OpenAPI page.

### Request bodies

Send JSON with `Content-Type: application/json`. You can gzip that body and set `Content-Encoding` to `gzip` or `x-gzip`. Size limits apply to the decompressed body. An encoded body that already exceeds the route&#39;s limit is rejected before it is decoded.

### Write responses

A write returns what it changed, in the shape a read of the same resource returns.

* **Creating** a project, branch, Context Group, or project API key with `POST` returns `201` with the new resource. A new API key also carries its secret `key`, which no later response returns.
* **Updating** one resource with `PATCH` returns `200` with the updated resource.
* **`PUT`** endpoints (setting a tag, assigning a Context Group, and setting a Glossary term translation) return the resource with `201` when the request created it and `200` when it already existed.
* **Deleting** returns `200` with `{ "deleted": true }`.

<Callout type="info">
  **Changed in `2026-10-08.v1`:** Context Management writes return the resource, `counts`, or `deleted` instead of `committed: true`. Creating a project or a project API key returns the resource without the `project` or `apiKey` wrapper. Runtime translation takes `requests` as an array and returns `summary` and `results` instead of an object keyed by request. Earlier versions keep their responses; pick one in the API version menu to read them.
</Callout>

### Batch requests

The batch endpoints below return one result per item, in request order.

* **Writes** (uploading source files and translations, moving, publishing and overwriting files, and uploading font assets) return `200` with `summary` (`total`, `succeeded` and `failed` counts) and `results`, even when every item fails. A failed item has `status: "failed"` and an `error`; the other items are still applied. A request that fails validation returns `400` and applies nothing.
* **Runtime translation** (`POST /v2/projects/{projectId}/translate`) takes `requests` as an array and returns `200` with `summary` and `results`. An entry that could not be translated has `status: "failed"` with an `error` and a `code`; the other entries are still translated. Repeated content is translated once per entry, so send each string once.
* **Reads** (file, file content and job queries) return `200` with `results`. An item that the project does not have is `not_found`. A file translation that is stored but not yet completed, for example during a layout pass, is `pending`; request it again later. A translation is `not_found` until its translation job has stored it, so wait for the job with `GET /v2/projects/{projectId}/jobs/{jobId}` or `POST /v2/projects/{projectId}/jobs/query` before reading it. Without `versionId`, a read returns the newest completed version on the branch, and is `pending` only while no version has been completed. Job queries return each job&#39;s status.

Other batch endpoints have their own response. Queueing file translation returns `202` with the created `jobs`. The Context Management Glossary and Custom Prompt upserts apply either the whole batch or nothing, and return `counts` (`created`, `updated` and `unchanged`) with `items`: one `id` and `outcome` per item, in request order.

### Runtime metadata limits

For `POST /v2/projects/{projectId}/translate`, a positive integer `maxChars` adds a length instruction to supported translation prompts; it is not a guaranteed output-length limit. Non-positive or fractional numbers are ignored. Values of the wrong type fail request validation.

Each `sourceCode` file keeps at most five context entries. The API truncates each entry&#39;s `before` and `after` fields to 2,000 characters and its `target` field to 500 characters.

Set `fileFormat` to `MD` or `MDX` to translate a whole document supplied as a string. Document requests must use `dataFormat: STRING` and cannot include `maxChars` or `sourceCode`. The API parses the document into chunks, adds the request context to each chunk, and returns one validated document string. A failed chunk or invalid final document fails that entry rather than returning partial output.

### Locale allowlist

Runtime translation returns `403` with code `locale_not_allowed` when the project has a non-empty locale list and `targetLocale` is not on it. An empty locale list does not restrict target locales. A batch served entirely from cache skips this check, so a locale removed from the project can still return its cached translations.

### Rate limits

Rate limiting uses 60-second windows at two layers:

* **Before authentication:** each presented credential can make 600 attempts per minute, including requests that fail authentication. Requests without a credential skip this layer. Exceeding the limit returns `429` with `Retry-After: 60` and no `RateLimit-*` headers.
* **After authentication:** each route group limits requests per authenticated caller, such as an API key. Limited routes without an authenticated caller use the client IP.

Post-authentication limits vary by endpoint:

* **Heavy:** 30 requests/minute for translating files.
* **Medium:** 120 requests/minute for uploading source files, translations, and fonts; overwriting translations; generating context; moving files; listing branch files; and publishing.
* **Light:** 300 requests/minute for file downloads.
* **Default:** 200 requests/minute for project and Organisation discovery, project creation, project API keys, project settings, branches, tags, jobs, file metadata and status, runtime translation, and Context Management.

Listing projects, creating projects, and listing, reading, creating, and deleting project API keys share one limit.

Exceeding a post-authentication limit returns `429` with `RateLimit-*` headers.

### Pagination

List endpoints return one page of results as `{ "items": [...], "nextCursor": ... }`. Pass `limit` (1 to 100, default 50) to set the page size. When `nextCursor` is a string, send it as `cursor` to fetch the next page; when it is `null`, there are no more results. A cursor works only for the list and filters that issued it. Pages are read independently, so items that change between requests may be missed or repeated.

### Errors

From API version `2026-02-18.v1`, errors return a JSON body with an `error` message and a stable `code`. This includes malformed JSON (`400`), oversized bodies (`413`), and rate limits (`429`). Earlier versions return most errors as plain text without `code`.

```json
{
  "error": "Missing required permission: project:files:write",
  "code": "permission_missing"
}
```

`code` names the cause. A route can return a more specific code than the generic code for its status; each endpoint&#39;s reference lists the codes it can return. New codes may be added, so treat an unrecognised code like its HTTP status.

Common status codes and their generic `code`:

* `400` `invalid_request` for an invalid request body, query, or version. A corrupt or truncated gzip body returns `invalid_content_encoding`.
* `401` `unauthenticated` for a missing or invalid bearer credential.
* `402` `payment_required` when the Organisation&#39;s billing account is blocked, or its plan usage limit, monthly spend limit, or credit balance does not cover the request (translating files and runtime translation).
* `403` `permission_denied` when the request identity lacks permission or the action is not allowed on the current plan. A missing permission returns `permission_missing` and names the permission in `error`.
* `404` `not_found` when the resource is not found.
* `409` `conflict` for a conflict, such as project creation over the Organisation&#39;s project limit, a branch name already in use, or a rename that collides with an existing Glossary term or Custom Prompt.
* `410` `route_retired` when the route is retired in the requested API version. `error` names the route to use instead.
* `413` `payload_too_large` when the request body exceeds the endpoint limit, or when a Context Management response would exceed 1 MiB (request a smaller `limit`).
* `415` `unsupported_media_type` when the request body&#39;s `Content-Type` is missing or not `application/json`. An unsupported `Content-Encoding` returns `unsupported_content_encoding`. Send the body uncompressed or gzip-encoded.
* `423` `locked` when the resource is locked by an operation in progress.
* `425` `not_ready` when the requested result is not ready yet.
* `429` `rate_limited` when a rate limit is exceeded.
* `500` `internal_error` for an internal server error.
* `502` `upstream_error` when an upstream service fails to complete the request.
* `503` `unavailable` when the service is temporarily unavailable.

Retry `429` and `503` responses after a delay. For `429`, wait the number of seconds in the `Retry-After` header.

## OpenAPI spec [#openapi-spec]

A machine-readable OpenAPI 3.1 spec of the latest version is available at [`/openapi.json`](/openapi.json), and each older version&#39;s at `/openapi/<version>.json`. Import it into Postman, Insomnia or an OpenAPI client to generate requests and types.

For typed endpoint helpers, use the [`@generaltranslation/api` client](/docs/platform/core/reference/api-client).

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.
