# api: API reference
URL: https://generaltranslation.com/en-GB/docs/api.mdx
---
title: API reference
description: Public General Translation API endpoints, authentication, and the OpenAPI spec
index: true
---

The General Translation API lets you upload source content and translated files, download translations, translate and queue content, manage branches and tags, and read project and job status. Most SDK and CLI workflows call these endpoints for you, but you can call them directly for custom automation.

Each endpoint has its own page in this section with parameters, schemas, and an interactive request playground. A machine-readable OpenAPI 3.1 spec ships alongside these pages as `openapi.yaml` — import it into Postman, Insomnia, or an OpenAPI client to generate requests and types.

## Base URLs

| API                                        | Base URL                  |
| ------------------------------------------ | ------------------------- |
| Project and file endpoints                 | `https://api.gtx.dev`     |
| Runtime translation (`POST /v2/translate`) | `https://runtime.gtx.dev` |

## Authentication

Authenticate every request with an API key in the `x-gt-api-key` header.

```bash
curl https://api.gtx.dev/v2/project/info/PROJECT_ID \
  -H "x-gt-api-key: gtx-api-..."
```

| Key type              | Prefix     | Notes                                                                       |
| --------------------- | ---------- | --------------------------------------------------------------------------- |
| Project (production)  | `gtx-api-` | Bound to one project                                                        |
| Project (development) | `gtx-dev-` | Local and preview use; rejected by production-only endpoints                |
| Organisation          | `gtx-org-` | Works across projects; must send `x-gt-project-id` on project-scoped routes |

<Callout type="info">
  **Organisation keys:** When you authenticate with an organization key, include the target project in the `x-gt-project-id` header for any project-scoped endpoint.
</Callout>

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

## Permissions

Each endpoint requires a permission on the API key. Organisation keys configure these explicitly; project keys inherit the project defaults.

| Permission                      | Used by                                                                                                                        |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `project:files:read`            | Download files, file information, translation status, branch information, orphaned files, project information, job information |
| `project:files:write`           | Upload files and translations, diffs, publish, branch creation, tag creation, moves                                            |
| `project:translations:enqueue`  | Queue files for translation                                                                                                    |
| `project:translations:generate` | Runtime translation                                                                                                            |
| `project:context:read`          | Read context generation status                                                                                                 |
| `project:context:write`         | Generate context                                                                                                               |
| `project:write`                 | Update project settings                                                                                                        |

## Versioning

Send the optional `gt-api-version` header to pin a response format. If omitted, the earliest supported version is used. The latest version is `2026-03-06.v1`.

```bash
-H "gt-api-version: 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:

| Tier    | Limit     | Endpoints                                                                                         |
| ------- | --------- | ------------------------------------------------------------------------------------------------- |
| Heavy   | 20 / min  | Queue translations                                                                                |
| Medium  | 60 / min  | Upload, diffs, context, moves, orphaned                                                           |
| Light   | 120 / min | Download files                                                                                    |
| Default | 200 / min | Publish, branches, tags, project info, job info, file info, translation status, runtime translate |

Exceeding a limit returns `429`. Organisation token quotas can also return `429` from `POST /v2/translate`.

## Errors

Errors return a JSON body with an `error` message:

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

| Status | Meaning                                                                                 |
| ------ | --------------------------------------------------------------------------------------- |
| `400`  | Invalid request body, query, or version                                                 |
| `401`  | Missing or invalid API key                                                              |
| `403`  | API key lacks the required permission, or the action is not allowed on the current plan |
| `404`  | Resource not found                                                                      |
| `429`  | Rate limit or token quota exceeded                                                      |

## Next steps

* [API keys](/docs/platform/api-keys) - Create and scope keys
* [Webhooks](/docs/platform/webhooks) - Receive translation events
* [Supported locales](/docs/platform/supported-locales) - Locale codes used in requests