# General Translation Platform: Overview
URL: https://generaltranslation.com/en-US/docs/platform/openapi/overview.mdx
---

title: Overview
description: Learn how to use the public General Translation API endpoints and the OpenAPI spec.

related:
  title: Reference sections
  links:
    - /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/project-info
---

Use the General Translation API to build custom automation workflows.

The SDK and CLI handle most API calls for you. Call the API directly when you need to upload files, queue translation jobs, download translations, manage branches and tags, or inspect Project and job status from your own system. 

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

## API basics [#api-basics]

### Base URLs

- Use `https://api2.gtx.dev` for project and file endpoints.
- Use `https://runtime2.gtx.dev` for runtime translation, including `POST /v2/translate`.



### Authentication

Send your API key in the `x-gt-api-key` header.

```bash
curl https://api2.gtx.dev/v2/project/info/PROJECT_ID \
  -H "x-gt-api-key: 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. When using an Organization key on Project-scoped endpoints, must send `x-gt-project-id`.

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

### Permissions

Each endpoint requires a permission on the API key. Organization keys configure permissions explicitly. Project keys use the Project defaults.

Common permissions:

- `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 and translations, 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:read` for reading context generation status.
- `project:context:write` for generating context.
- `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`.

### 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, and orphaned files.
- **Light:** 300 requests/minute for file downloads.
- **Default:** 200 requests/minute for publish, 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

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.

```json
{
  "error": "API key is missing required permission: project:files:write"
}
```

Common status codes:

- `400` for invalid request body, query, or version.
- `401` for missing or invalid API key.
- `402` when an Organization token quota is exceeded (`POST /v2/translate`).
- `403` when the API key lacks permission or the action is not allowed on the current plan.
- `404` when the resource is not found.
- `429` when a rate limit is exceeded.

## OpenAPI spec [#openapi-spec]

A machine-readable OpenAPI 3.1 spec is available at [`/openapi.yaml`](/openapi.yaml). Import it into Postman, Insomnia, or an OpenAPI client to generate requests and types.
## Reference sections

- /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/project-info