# General Translation Platform: Обзор
URL: https://generaltranslation.com/ru/docs/platform/openapi/overview.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Обращайтесь к публичным конечным точкам API General Translation и скачивайте спецификацию OpenAPI.

Используйте API General Translation, чтобы создавать собственные рабочие процессы автоматизации.

CLI берёт на себя большинство вызовов API. Используйте [TypeScript-клиент `@generaltranslation/api`](/docs/platform/core/reference/api-client) для получения сгенерированных типов запросов и ответов или обращайтесь к конечным точкам напрямую, когда вам нужна собственная автоматизация.

Спецификация OpenAPI определяет эти конечные точки в машиночитаемом формате.

## Основы API [#api-basics]

### Базовый URL

Все конечные точки, включая конечную точку для перевода во время выполнения `POST /v2/projects/{projectId}/translate`, доступны по адресу `https://api.gtx.dev`.

### Аутентификация

Для аутентификации передавайте ключ API в стандартном заголовке `Authorization`.

```bash
curl https://api.gtx.dev/v2/projects/PROJECT_ID \
  -H "Authorization: Bearer gtx-api-..." \
  -H "gt-api-version: 2026-10-08.v1"
```

Выберите область ключа, соответствующую вашему рабочему процессу:

* **Проект** с префиксом `gtx-api-`: привязан к одному проекту и может использоваться в любом окружении с учётом его разрешений
* **Организация** с префиксом `gtx-org-`: работает во всех проектах той организации, к которой он привязан, с учётом его разрешений

Путь определяет, над чем выполняется запрос: `/v2/projects/{projectId}/...` — над проектом, `/v2/orgs/{orgId}/...` — над организацией, а `/v2/context-groups/{groupId}/...` — над организацией, которой принадлежит группа. Конечным точкам обнаружения (`GET /v2/orgs` и `GET /v2/projects`) ID не нужен. Ключ должен иметь доступ к выбранному проекту или организации, поэтому ключ проекта работает только со своим проектом и назначенными ему контекстными группами.

Не включайте ключи API в развёртываемые браузерные и мобильные бандлы.

(См. [Ключи API](/docs/platform/dashboard/reference/api-keys), чтобы узнать, как создавать ключи API и задавать для них область).

### Разрешения

Для большинства конечных точек требуется соответствующее разрешение у идентичности запроса. [List организаций](/docs/platform/openapi/reference/organizations/list-orgs), [List проектов](/docs/platform/openapi/reference/projects/list-projects) и [Получение проекта](/docs/platform/openapi/reference/projects/get-project) не требуют разрешений на ресурсы — достаточно доступа к возвращаемой организации или проекту. И ключи организации, и ключи проекта поддерживают разрешения **All** или **Custom** в Dashboard, ограниченные теми разрешениями, которые может выдать создатель. [Конечная точка ключей API проекта](/docs/platform/openapi/reference/api-keys/create-project-api-key) позволяет выбрать разрешения или не указывать их: в этом случае выдаются все разрешения проекта, которые вы можете делегировать. Разрешения Write не включают Read. Ключи проекта не могут иметь разрешения уровня организации (`org:*`), `project:api_keys:read` или `project:api_keys:write`, поэтому для конечных точек, которым они требуются, нужен ключ организации.

Распространённые разрешения:

* `org:projects:create` для создания проектов с помощью `POST /v2/orgs/{orgId}/projects`.
* `project:api_keys:read` для получения списка и чтения ключей API проекта.
* `project:api_keys:write` для создания ключей API проекта с помощью `POST /v2/projects/{projectId}/api-keys` и их удаления.
* `org:assets:write` для загрузки шрифтов с помощью `POST /v2/orgs/{orgId}/assets`.
* `project:files:read` для скачивания файлов; чтения метаданных и статуса файлов; получения списка веток и файлов веток; а также чтения заданий.
* `project:files:write` для загрузки исходных файлов и переводов; перезаписи переводов; публикации; создания и обновления веток; установки тегов; а также перемещения файлов.
* `project:translations:enqueue` для перевода файлов с помощью `POST /v2/projects/{projectId}/files/translate`.
* `project:translations:generate` для перевода во время выполнения.
* `project:context:read` для чтения контекстных групп, назначенных проекту, их Glossary и пользовательских промптов, а также экспортов.
* `project:context:write` для генерации контекста, а также для редактирования Glossary и пользовательских промптов контекстных групп, назначенных проекту, импорта в них содержимого и изменения их порядка.
* `org:context:read` для чтения всех контекстных групп организации, их Glossary и пользовательских промптов, назначений проектам и экспортов.
* `org:context:write` для создания, обновления и удаления контекстных групп и их содержимого, импорта содержимого, а также для назначения групп проектам, отмены назначения и изменения их порядка.
* `project:write` для обновления настроек проекта.

Конечные точки Context Management, которые читают или редактируют содержимое группы, а также те, что возвращают список групп проекта, читают их или меняют их порядок, принимают либо разрешение уровня организации, либо разрешение уровня проекта для любого проекта, которому назначена группа. Для получения списка групп организации, создания, обновления и удаления группы, а также для её назначения и отмены назначения требуется разрешение уровня организации. Для группы, с которой идентичность запроса не может работать, возвращается тот же `403`, что и для несуществующей группы.

### Управление версиями

Передавайте заголовок `gt-api-version` в каждом запросе, чтобы указать версию контракта API.

```bash
-H "gt-api-version: 2026-10-08.v1"
```

* Конечные точки, у которых на справочной странице этот заголовок отмечен как обязательный, возвращают `400`, если он отсутствует или указывает более старую версию.
* Остальные конечные точки при отсутствии заголовка используют самую старую из поддерживаемых версий и возвращают ошибки в виде обычного текста, а не JSON.

Чтобы просмотреть конечные точки более старой версии, выберите её в меню версий API в верхней части любой страницы OpenAPI.

### Тела запросов

Отправляйте JSON с заголовком `Content-Type: application/json`. Тело запроса можно сжать с помощью gzip, указав в `Content-Encoding` значение `gzip` или `x-gzip`. Ограничения на размер применяются к распакованному телу. Если закодированное тело уже превышает лимит маршрута, запрос отклоняется ещё до декодирования.

### Ответы на запросы записи

Запрос записи возвращает изменённые данные в том же формате, что и запрос чтения того же ресурса.

* **Создание** проекта, ветки, контекстной группы или ключа API проекта через `POST` возвращает `201` и новый ресурс. Новый ключ API также содержит секретное значение `key`, которое не возвращается ни в одном последующем ответе.
* **Обновление** ресурса через `PATCH` возвращает `200` и обновлённый ресурс.
* Конечные точки **`PUT`** (установка тега, назначение контекстной группы и задание перевода термина Glossary) возвращают ресурс с кодом `201`, если запрос его создал, и `200`, если ресурс уже существовал.
* **Удаление** возвращает `200` и `{ "deleted": true }`.

<Callout type="info">
  **Изменено в `2026-10-08.v1`:** запросы записи в Context Management возвращают ресурс, `counts` или `deleted` вместо `committed: true`. При создании проекта или ключа API проекта ресурс возвращается без обёртки `project` или `apiKey`. Перевод во время выполнения принимает `requests` в виде массива и возвращает `summary` и `results` вместо объекта с ключами по запросам. В более ранних версиях формат ответов не изменился; чтобы посмотреть его, выберите нужную версию в меню версий API.
</Callout>

### Пакетные запросы

Перечисленные ниже пакетные конечные точки возвращают по одному результату на каждый элемент в том же порядке, что и в запросе.

* **Операции записи** (загрузка исходных файлов и переводов, перемещение, публикация и перезапись файлов, а также загрузка шрифтов) возвращают `200` с `summary` (количество `total`, `succeeded` и `failed`) и `results`, даже если ни один элемент не обработан успешно. У элемента с ошибкой указаны `status: "failed"` и `error`; остальные элементы при этом всё равно применяются. Запрос, не прошедший валидацию, возвращает `400`, и ничего не применяется.
* **Перевод во время выполнения** (`POST /v2/projects/{projectId}/translate`) принимает `requests` в виде массива и возвращает `200` с `summary` и `results`. У записи, которую не удалось перевести, указаны `status: "failed"`, `error` и `code`; остальные записи при этом всё равно переводятся. Повторяющееся содержимое переводится отдельно для каждой записи, поэтому отправляйте каждую строку только один раз.
* **Операции чтения** (запросы файлов, содержимого файлов и заданий) возвращают `200` с `results`. Элемент, которого нет в проекте, получает статус `not_found`. Перевод файла, который уже сохранён, но ещё не завершён (например, во время обработки вёрстки), получает статус `pending` — повторите запрос позже. Пока задание на перевод не сохранило перевод, он имеет статус `not_found`, поэтому перед чтением дождитесь завершения задания с помощью `GET /v2/projects/{projectId}/jobs/{jobId}` или `POST /v2/projects/{projectId}/jobs/query`. Если `versionId` не указан, чтение возвращает последнюю завершённую версию в ветке; статус `pending` возвращается, только пока ни одна версия не завершена. Запросы заданий возвращают статус каждого задания.

Остальные пакетные конечные точки возвращают ответы в собственном формате. Постановка перевода файлов в очередь возвращает `202` с созданными `jobs`. Upsert для Glossary и пользовательских промптов в Context Management применяет пакет целиком либо не применяет ничего и возвращает `counts` (`created`, `updated` и `unchanged`) вместе с `items`: по одному `id` и `outcome` на каждый элемент в том же порядке, что и в запросе.

### Ограничения метаданных времени выполнения

Для `POST /v2/projects/{projectId}/translate` положительное целое значение `maxChars` добавляет в поддерживаемые промпты перевода указание о длине; это не гарантированное ограничение длины результата. Неположительные и дробные числа игнорируются. Значения неверного типа не проходят валидацию запроса.

Каждый файл `sourceCode` хранит не более пяти контекстных записей. API усекает поля `before` и `after` каждой записи до 2 000 символов, а поле `target` — до 500 символов.

Укажите для `fileFormat` значение `MD` или `MDX`, чтобы перевести целый документ, переданный в виде строки. Запросы на перевод документов должны использовать `dataFormat: STRING` и не могут содержать `maxChars` или `sourceCode`. API разбивает документ на фрагменты, добавляет контекст запроса к каждому фрагменту и возвращает одну проверенную строку документа. Если фрагмент не удалось перевести или итоговый документ оказался некорректным, ошибку получает соответствующая запись, а частичный результат не возвращается.

### Список разрешённых локалей

Перевод во время выполнения возвращает `403` с кодом `locale_not_allowed`, если в проекте задан непустой список локалей и `targetLocale` в него не входит. Пустой список локалей не ограничивает целевые локали. Для пакета, который целиком отдаётся из кеша, эта проверка не выполняется, поэтому для локали, удалённой из проекта, по-прежнему могут возвращаться закешированные переводы.

### Ограничения частоты запросов

Частота запросов ограничивается в 60-секундных окнах на двух уровнях:

* **До аутентификации:** для каждых предъявленных учётных данных допускается 600 попыток в минуту, включая запросы, не прошедшие аутентификацию. Запросы без учётных данных пропускают этот уровень. При превышении ограничения частоты запросов возвращается `429` с `Retry-After: 60` и без заголовков `RateLimit-*`.
* **После аутентификации:** каждая группа маршрутов ограничивает запросы для каждой аутентифицированной вызывающей стороны, например ключа API. Для ограниченных маршрутов без аутентифицированной вызывающей стороны используется IP-адрес клиента.

Ограничения частоты запросов после аутентификации зависят от конечной точки:

* **Тяжёлые:** 30 запросов в минуту для перевода файлов.
* **Средние:** 120 запросов в минуту для загрузки исходных файлов, переводов и шрифтов, перезаписи переводов, генерации контекста, перемещения файлов, получения списка файлов ветки и публикации.
* **Лёгкие:** 300 запросов в минуту для скачивания файлов.
* **По умолчанию:** 200 запросов в минуту для обнаружения проектов и организаций, создания проекта, работы с ключами API проекта, настроек проекта, веток, тегов, заданий, метаданных и статуса файлов, перевода во время выполнения и Context Management.

Получение списка проектов, создание проектов, а также получение списка, чтение, создание и удаление ключей API проекта подчиняются общему ограничению частоты запросов.

При превышении ограничения частоты запросов после аутентификации возвращается `429` с заголовками `RateLimit-*`.

### Пагинация

Эндпоинты списков возвращают одну страницу результатов в формате `{ "items": [...], "nextCursor": ... }`. Чтобы задать размер страницы, передайте `limit` (от 1 до 100, по умолчанию 50). Если `nextCursor` содержит строку, передайте её в параметре `cursor`, чтобы получить следующую страницу; если значение равно `null`, результатов больше нет. Курсор действителен только для того списка и тех фильтров, для которых он был выдан. Страницы запрашиваются независимо друг от друга, поэтому элементы, изменившиеся между запросами, могут быть пропущены или продублированы.

### Ошибки

Начиная с версии API `2026-02-18.v1`, при ошибках возвращается JSON-тело с сообщением `error` и стабильным кодом `code`. Это относится и к некорректному JSON (`400`), и к слишком большому телу запроса (`413`), и к превышению ограничения частоты запросов (`429`). В более ранних версиях большинство ошибок возвращается в виде обычного текста без `code`.

```json
{
  "error": "Missing required permission: project:files:write",
  "code": "permission_missing"
}
```

`code` указывает причину ошибки. Маршрут может вернуть более конкретный код, чем общий код для своего статуса; в справочнике каждого эндпоинта перечислены коды, которые он может вернуть. Со временем могут добавляться новые коды, поэтому обрабатывайте нераспознанный код так же, как соответствующий HTTP-статус.

Распространённые коды статуса и соответствующие им общие значения `code`:

* `400` `invalid_request` — недопустимое тело запроса, параметры запроса или версия. Если тело в формате gzip повреждено или обрезано, возвращается `invalid_content_encoding`.
* `401` `unauthenticated` — учётные данные bearer отсутствуют или недействительны.
* `402` `payment_required` — платёжный аккаунт Организации заблокирован либо лимит использования тарифного плана, месячный лимит расходов или баланс кредитов не покрывает запрос (перевод файлов и перевод во время выполнения).
* `403` `permission_denied` — у идентичности запроса нет нужного разрешения или действие недоступно на текущем тарифном плане. При отсутствии разрешения возвращается `permission_missing`, а название разрешения указывается в `error`.
* `404` `not_found` — ресурс не найден.
* `409` `conflict` — конфликт, например создание проекта сверх лимита проектов Организации, уже занятое имя ветки или переименование, при котором новое имя совпадает с существующим термином Glossary или пользовательским промптом.
* `410` `route_retired` — маршрут выведен из эксплуатации в запрошенной версии API. В `error` указан маршрут, который следует использовать вместо него.
* `413` `payload_too_large` — тело запроса превышает лимит эндпоинта или ответ Context Management превысил бы 1 MiB (запросите меньшее значение `limit`).
* `415` `unsupported_media_type` — заголовок `Content-Type` тела запроса отсутствует или не равен `application/json`. Если значение `Content-Encoding` не поддерживается, возвращается `unsupported_content_encoding`. Отправляйте тело без сжатия или в формате gzip.
* `423` `locked` — ресурс заблокирован выполняющейся операцией.
* `425` `not_ready` — запрошенный результат ещё не готов.
* `429` `rate_limited` — превышено ограничение частоты запросов.
* `500` `internal_error` — внутренняя ошибка сервера.
* `502` `upstream_error` — вышестоящему сервису не удалось выполнить запрос.
* `503` `unavailable` — сервис временно недоступен.

При получении ответов `429` и `503` повторите запрос после паузы. Для `429` подождите столько секунд, сколько указано в заголовке `Retry-After`.

## Спецификация OpenAPI [#openapi-spec]

Машиночитаемая спецификация OpenAPI 3.1 для последней версии доступна по адресу [`/openapi.json`](/openapi.json), а для каждой из предыдущих версий — по адресу `/openapi/<version>.json`. Импортируйте её в Postman, Insomnia или OpenAPI-клиент, чтобы генерировать запросы и типы.

Для типизированных вспомогательных функций конечных точек используйте [клиент `@generaltranslation/api`](/docs/platform/core/reference/api-client).

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.
