# 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 Every endpoint requires a bearer credential in the standard `Authorization` header. The endpoint reference shows whether an operation accepts an API key, an OAuth 2.1 user access token, or both. ```bash curl https://api.gtx.dev/v2/project/info/PROJECT_ID \ -H "Authorization: Bearer gtx-api-..." ``` Use the correct key type: - **Project (development)** with prefix `gtx-dev-`: for local and preview use, rejected by production-only endpoints - **Project (production)** with prefix `gtx-api-`: bound to one project - **Organization** with prefix `gtx-org-`: works across projects. Most project-scoped endpoints require `gt-project-id`. `GET /v2/project/info/{projectId}` still requires that header and checks that the two IDs match. `POST /v2/projects/{projectId}/api-keys` uses its path parameter instead. Organization-scoped endpoints such as `POST /v2/orgs/{orgId}/projects` use the Organization in the path and require the credential to have access to it. (See [API keys](/docs/platform/dashboard/reference/api-keys) for how to create and scope API keys). OAuth applications use the Authorization Code flow with Proof Key for Code Exchange (PKCE). Discover the authorization server at `https://dash.generaltranslation.com/.well-known/oauth-authorization-server/api/auth`, request only the scopes your application needs, and send the resulting user access token in the same bearer header. The token is limited by both its granted scopes and the user's current access to the target Organization or project. ### Permissions Each endpoint requires a permission on the request identity. Organization keys configure permissions explicitly. Project keys created in the Dashboard use the defaults for their key type; keys created through the Organization API can have fewer permissions because they are limited to those the request identity can delegate. OAuth user access tokens must include the matching scope, and the signed-in user must still hold that permission. 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, reading file info, translation status, branch info, orphaned files, project info, 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. - `project:write` for updating project settings and enabling CDN delivery during project creation. ### 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. ### Rate limits Requests are rate limited per API key or client IP over a 60-second window. Limits vary by endpoint: - **Heavy:** 30 requests/minute for queueing translations. - **Medium:** 120 requests/minute for uploads, diffs, context, moves, orphaned files, and publishing. - **Light:** 300 requests/minute for file downloads. - **Default:** 200 requests/minute for project and project API-key creation, branches, tags, project info, job info, file info, translation status, and runtime translation. Exceeding a limit returns `429`. Organization token quotas return `402` from `POST /v2/translate`. ### Errors Authenticated application 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. Parsing, payload-limit, and rate-limit failures can return plain text before authentication runs. ```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. - `413` when the request body exceeds the endpoint 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. The JavaScript tools also ship the OpenAPI snapshot used to generate their installed SDK version. That bundled snapshot can differ from the current hosted contract: - Run [`npx gt api --spec`](/docs/cli/reference/commands/api) with `gt` 2.20.0 or later. - Import `generaltranslation/api/openapi.json` from `generaltranslation` 9.2.0 or later. - Import `@generaltranslation/api/spec/openapi.json` from the standalone generated SDK. 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/translation/translate-runtime - /docs/platform/openapi/reference/project/create-project ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.