# General Translation Platform: Overview URL: https://generaltranslation.com/en-US/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/translate`, live under `https://api.gtx.dev`. ### Authentication Authenticate with an API key in the standard `Authorization` header. ```bash curl https://api.gtx.dev/v2/project/info/PROJECT_ID \ -H "Authorization: Bearer gtx-api-..." ``` 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 - **Organization** with prefix `gtx-org-`: works across projects in its bound Organization, subject to its permissions For project-scoped endpoints with a project ID in the path, that ID selects the project. An optional `gt-project-id` must match or the request fails with `403`. Without a path target, project keys use their bound project; Organization keys must send `gt-project-id`. Project and Organization discovery need no project target. Organization-scoped routes with a path target use that Organization, and Context Group routes (`/v2/context-groups/{groupId}`) use the Organization that owns the group. Legacy API-key headers remain supported and take precedence over the bearer header. 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 Organizations](/docs/platform/openapi/reference/project/list-orgs), [List Projects](/docs/platform/openapi/reference/project/list-projects), and [Get Project information](/docs/platform/openapi/reference/project/project-info) need no resource permission beyond access to the returned Organization or project. Both Organization 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/project/create-api-key) lets you select permissions or omit the selection to grant all delegable project permissions. Explicit HTTP Write grants do not implicitly include Read. Context Management endpoints require Organization permissions, so they need an Organization key; project keys cannot call them. Common permissions: - `org:projects:create` for creating projects with `POST /v2/orgs/{orgId}/projects`. - `project:api_keys:write` for creating project API keys with `POST /v2/projects/{projectId}/api-keys`. - `project:files:read` for downloading files and reading file info, translation status, branch info, orphaned files, and job info. - `project:files:write` for uploading files, translations, and assets; submitting diffs; publishing; creating branches and tags; and moving files. - `project:translations:enqueue` for queuing files for translation. - `project:translations:generate` for runtime translation. - `project:context:write` for generating context. - `org:context:read` for reading Context Groups, 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. ### Versioning Send the optional `gt-api-version` header to pin a response format. ```bash -H "gt-api-version: 2026-03-06.v1" ``` If you omit the header, the earliest supported version is used. The latest version is `2026-03-06.v1`. ### Runtime metadata limits For `POST /v2/translate`, a positive integer `maxChars` adds a length instruction to supported translation prompts; it is not a guaranteed output-length limit. Nonpositive 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'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. ### 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 queueing translations. - **Medium:** 120 requests/minute for uploads, diffs, context generation, moves, orphaned files, and publishing. - **Light:** 300 requests/minute for file downloads. - **Default:** 200 requests/minute for project and Organization discovery, project and project API-key creation, branches, tags, project info, job info, file info, translation status, runtime translation, and Context Management. Project and Organization discovery and project/key creation share a request limit. Exceeding a post-authentication limit returns `429` with `RateLimit-*` headers. Organization token quotas return `402` from `POST /v2/translate`. ### 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 Errors return an `error` message. For API version `2026-02-18.v1` and later, the body is JSON; earlier versions, including the default used when no `gt-api-version` header is sent, return the message as plain text. This applies to every error, including malformed JSON (`400`), oversized bodies (`413`), and rate limits (`429`). ```json { "error": "API key is missing required permission: project:files:write" } ``` Common status codes: - `400` for invalid request body, query, or version. - `401` for a missing or invalid bearer credential. - `402` when an Organization token quota is exceeded (`POST /v2/translate`). - `403` when the request identity lacks permission or the action is not allowed on the current plan. - `404` when the resource is not found. - `409` for a conflict, such as project creation over the Organization's project limit or a rename that collides with an existing Glossary term or Custom Prompt. - `413` when the request body exceeds the endpoint limit, or when a Context Management response would exceed 1 MiB (request a smaller `limit`). - `425` when a requested translated file is still processing. - `429` when a rate limit is exceeded. - `500` for an internal server error. - `503` when the service is temporarily unavailable. ## OpenAPI spec [#openapi-spec] A machine-readable OpenAPI 3.1 spec is available at [`/openapi.json`](/openapi.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). ## Reference sections - /docs/platform/core/reference/api-client - /docs/platform/openapi/reference/files/upload-source - /docs/platform/openapi/reference/context/generate-context - /docs/platform/openapi/reference/context-management/list-groups - /docs/platform/openapi/reference/translation/translate-runtime - /docs/platform/openapi/reference/project/create-project ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.