# api: API reference
URL: https://generaltranslation.com/en-US/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 |
| Organization | `gtx-org-` | Works across projects; must send `x-gt-project-id` on project-scoped routes |

<Callout type="info">
  **Organization 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. Organization keys configure these explicitly; project keys carry the project defaults.

| Permission | Used by |
|------------|---------|
| `project:files:read` | Download files, file info, translation status, branch info, orphaned files, project info, job info |
| `project:files:write` | Upload files and translations, diffs, publish, branch create, tag create, 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. When 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`. Organization 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