# General Translation Platform: Descripción general
URL: https://generaltranslation.com/es/docs/platform/openapi/overview.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Llama a los endpoints públicos de la API de General Translation y descarga la especificación OpenAPI.

Usa la API de General Translation para crear flujos de trabajo de automatización personalizados.

La CLI gestiona la mayoría de las llamadas a la API por ti. Usa el [cliente de TypeScript `@generaltranslation/api`](/docs/platform/core/reference/api-client) para obtener tipos generados de solicitud y respuesta, o llama a los endpoints directamente cuando necesites una automatización personalizada.

La especificación OpenAPI define estos endpoints en un formato legible por máquinas.

## Conceptos básicos de la API [#api-basics]

### URL base

Todos los endpoints, incluida la traducción en tiempo de ejecución mediante `POST /v2/projects/{projectId}/translate`, están disponibles en `https://api.gtx.dev`.

### Autenticación

Autentícate con una Clave de API en la cabecera estándar `Authorization`.

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

Elige el alcance de clave que se ajuste a tu flujo de trabajo:

* **Project** con el prefijo `gtx-api-`: vinculada a un solo Project y utilizable en cualquier entorno, según sus permisos
* **Organization** con el prefijo `gtx-org-`: funciona en todos los Projects de la Organization a la que está vinculada, según sus permisos

El path determina sobre qué actúa una solicitud: `/v2/projects/{projectId}/...`, sobre el Project; `/v2/orgs/{orgId}/...`, sobre la Organization, y `/v2/context-groups/{groupId}/...`, sobre la Organization propietaria del grupo. Los endpoints de descubrimiento (`GET /v2/orgs` y `GET /v2/projects`) no requieren ningún ID. La clave debe tener acceso al Project o a la Organization seleccionados, por lo que una clave de Project solo funciona en su propio Project y en los grupos de contexto que tiene asignados.

No incluyas Claves de API en los bundles que se despliegan en navegadores ni en dispositivos móviles.

(Consulta [Claves de API](/docs/platform/dashboard/reference/api-keys) para saber cómo crear Claves de API y definir su alcance).

### Permisos

La mayoría de los endpoints requieren un permiso en la identidad de la solicitud. [List Organizations](/docs/platform/openapi/reference/organizations/list-orgs), [List Projects](/docs/platform/openapi/reference/projects/list-projects) y [Get a Project](/docs/platform/openapi/reference/projects/get-project) no necesitan ningún permiso de recurso más allá del acceso a la Organization o al Project devueltos. Tanto las claves de Organization como las de Project admiten permisos **All** o **Custom** en el Dashboard, limitados a los permisos que el creador puede conceder. El [endpoint de Clave de API de Project](/docs/platform/openapi/reference/api-keys/create-project-api-key) te permite seleccionar permisos u omitir la selección para conceder todos los permisos de Project que puedas delegar. Los permisos de Escritura no incluyen Lectura. Las claves de Project no pueden tener permisos de Organization (`org:*`), `project:api_keys:read` ni `project:api_keys:write`, por lo que los endpoints que los requieren necesitan una Organization key.

Permisos comunes:

* `org:projects:create` para crear Projects con `POST /v2/orgs/{orgId}/projects`.
* `project:api_keys:read` para listar y leer Claves de API de Project.
* `project:api_keys:write` para crear Claves de API de Project con `POST /v2/projects/{projectId}/api-keys` y eliminarlas.
* `org:assets:write` para subir fuentes con `POST /v2/orgs/{orgId}/assets`.
* `project:files:read` para descargar archivos; leer los metadatos y el estado de los archivos; listar ramas y sus archivos; y leer trabajos.
* `project:files:write` para subir archivos de origen y traducciones; sobrescribir traducciones; publicar; crear y actualizar ramas; establecer etiquetas; y mover archivos.
* `project:translations:enqueue` para traducir archivos con `POST /v2/projects/{projectId}/files/translate`.
* `project:translations:generate` para traducción en tiempo de ejecución.
* `project:context:read` para leer los grupos de contexto asignados al Project, su glosario y prompts personalizados, y las exportaciones.
* `project:context:write` para generar contexto, y para editar el glosario y los prompts personalizados de los grupos de contexto asignados al Project, importar contenido en ellos y reordenarlos.
* `org:context:read` para leer todos los grupos de contexto de la Organization, su glosario y prompts personalizados, las asignaciones a Projects y las exportaciones.
* `org:context:write` para crear, actualizar y eliminar grupos de contexto y su contenido, importar contenido, y asignar, desasignar y reordenar grupos en los Projects.
* `project:write` para actualizar la configuración del Project.

Los endpoints de Context Management que leen o editan el contenido de un grupo, así como los que listan, leen o reordenan los grupos de un Project, aceptan tanto el permiso de Organization como el permiso de Project en cualquier Project al que esté asignado el grupo. Para listar los grupos de una Organization, crear, actualizar o eliminar un grupo, y asignarlo o desasignarlo, se requiere el permiso de Organization. Si la identidad de la solicitud no puede actuar sobre un grupo, se devuelve el mismo `403` que para un grupo que no existe.

### Control de versiones

Envía la cabecera `gt-api-version` en cada solicitud para elegir la versión del contrato de la API.

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

* Los endpoints cuya página de referencia indica que la cabecera es obligatoria devuelven `400` si no se incluye o si especifica una versión anterior.
* Los demás endpoints usan la versión compatible más antigua cuando falta la cabecera y devuelven los errores como texto sin formato en lugar de JSON.

Para consultar los endpoints de una versión anterior, selecciónala en el menú de versión de la API, en la parte superior de cualquier página de OpenAPI.

### Cuerpos de las solicitudes

Envía JSON con `Content-Type: application/json`. Puedes comprimir el cuerpo con gzip y establecer `Content-Encoding` en `gzip` o `x-gzip`. Los límites de tamaño se aplican al cuerpo descomprimido. Si un cuerpo codificado ya supera el límite de la ruta, se rechaza antes de decodificarse.

### Respuestas de escritura

Una operación de escritura devuelve lo que modificó, con la misma estructura que devuelve una lectura del mismo recurso.

* **Crear** un Project, una rama, un Context Group o una clave de API de Project con `POST` devuelve `201` con el nuevo recurso. Una nueva clave de API incluye además su `key` secreta, que ninguna respuesta posterior vuelve a devolver.
* **Actualizar** un recurso con `PATCH` devuelve `200` con el recurso actualizado.
* Los endpoints **`PUT`** (establecer una etiqueta, asignar un Context Group y establecer la traducción de un término del glosario) devuelven el recurso con `201` si la solicitud lo creó y con `200` si ya existía.
* **Eliminar** devuelve `200` con `{ "deleted": true }`.

<Callout type="info">
  **Cambios en `2026-10-08.v1`:** las operaciones de escritura de Context Management devuelven el recurso, `counts` o `deleted` en lugar de `committed: true`. Crear un Project o una clave de API de Project devuelve el recurso sin el envoltorio `project` o `apiKey`. La traducción en tiempo de ejecución recibe `requests` como array y devuelve `summary` y `results` en lugar de un objeto indexado por solicitud. Las versiones anteriores mantienen sus respuestas; selecciona una en el menú de versiones de la API para consultarlas.
</Callout>

### Solicitudes por lotes

Los endpoints por lotes que se indican a continuación devuelven un resultado por elemento, en el mismo orden de la solicitud.

* **Escrituras** (subir archivos de origen y traducciones; mover, publicar y sobrescribir archivos; y subir recursos de fuentes) devuelven `200` con `summary` (recuentos de `total`, `succeeded` y `failed`) y `results`, incluso cuando fallan todos los elementos. Un elemento fallido tiene `status: "failed"` y un `error`; los demás elementos se aplican de todos modos. Una solicitud que no supera la validación devuelve `400` y no aplica nada.
* **Traducción en tiempo de ejecución** (`POST /v2/projects/{projectId}/translate`) recibe `requests` como array y devuelve `200` con `summary` y `results`. Una entrada que no se ha podido traducir tiene `status: "failed"` con un `error` y un `code`; las demás entradas se traducen de todos modos. El contenido repetido se traduce una vez por cada entrada, así que envía cada cadena una sola vez.
* **Lecturas** (consultas de archivos, de contenido de archivos y de trabajos) devuelven `200` con `results`. Un elemento que no existe en el Project se marca como `not_found`. Una traducción de archivo que está almacenada pero aún no se ha completado (por ejemplo, durante una pasada de maquetación) se marca como `pending`; vuelve a solicitarla más tarde. Una traducción figura como `not_found` mientras su tarea de traducción no la haya almacenado, así que espera a que termine el trabajo con `GET /v2/projects/{projectId}/jobs/{jobId}` o `POST /v2/projects/{projectId}/jobs/query` antes de leerla. Sin `versionId`, una lectura devuelve la versión completada más reciente de la rama, y solo figura como `pending` mientras no haya ninguna completada. Las consultas de trabajos devuelven el estado de cada trabajo.

Otros endpoints por lotes tienen su propia respuesta. Poner en cola la traducción de archivos devuelve `202` con los `jobs` creados. Las operaciones de actualizar o insertar del glosario y del prompt personalizado de Context Management aplican el lote completo o nada, y devuelven `counts` (`created`, `updated` y `unchanged`) junto con `items`: un `id` y un `outcome` por elemento, en el mismo orden de la solicitud.

### Límites de metadatos en tiempo de ejecución

Para `POST /v2/projects/{projectId}/translate`, un entero positivo en `maxChars` añade una instrucción de longitud a los prompts de traducción compatibles; no es un límite garantizado de la longitud de la salida. Los números no positivos o fraccionarios se ignoran. Los valores de tipo incorrecto hacen que falle la validación de la solicitud.

Cada archivo `sourceCode` conserva como máximo cinco entradas de contexto. La API trunca los campos `before` y `after` de cada entrada a 2000 caracteres y su campo `target` a 500 caracteres.

Establece `fileFormat` en `MD` o `MDX` para traducir un documento completo proporcionado como una cadena. Las solicitudes de documentos deben usar `dataFormat: STRING` y no pueden incluir `maxChars` ni `sourceCode`. La API divide el documento en fragmentos, añade el contexto de la solicitud a cada fragmento y devuelve una única cadena de documento validada. Si un fragmento falla o el documento final no es válido, falla esa entrada en lugar de devolver una salida parcial.

### Lista de configuraciones regionales permitidas

La traducción en tiempo de ejecución devuelve `403` con el código `locale_not_allowed` cuando el Project tiene una lista de configuraciones regionales que no está vacía y `targetLocale` no figura en ella. Si la lista de configuraciones regionales está vacía, no se restringen las configuraciones regionales de destino. Los lotes que se sirven íntegramente desde la caché omiten esta comprobación, por lo que una configuración regional eliminada del Project puede seguir devolviendo sus traducciones almacenadas en caché.

### Límites de solicitudes

La limitación de solicitudes usa ventanas de 60 segundos en dos capas:

* **Antes de la autenticación:** cada credencial presentada puede realizar 600 intentos por minuto, incluidas las solicitudes que fallan en la autenticación. Las solicitudes sin credencial omiten esta capa. Al superar el límite se devuelve `429` con `Retry-After: 60` y sin cabeceras `RateLimit-*`.
* **Después de la autenticación:** cada grupo de rutas limita las solicitudes por autor de la llamada autenticado, como una Clave de API. Las rutas limitadas sin un autor de la llamada autenticado usan la IP del cliente.

Los límites posteriores a la autenticación varían según el endpoint:

* **Heavy:** 30 solicitudes/minuto para traducir archivos.
* **Medium:** 120 solicitudes/minuto para subir archivos de origen, traducciones y fuentes; sobrescribir traducciones; generar contexto; mover archivos; listar archivos de rama, y publicar.
* **Light:** 300 solicitudes/minuto para descargas de archivos.
* **Default:** 200 solicitudes/minuto para descubrimiento de Projects y de Organization, creación de Projects, Claves de API de Project, configuración del Project, ramas, etiquetas, trabajos, metadatos y estado de archivos, traducción en tiempo de ejecución y Context Management.

Listar Projects y crear Projects, así como listar, leer, crear y eliminar Claves de API de Project, comparten un mismo límite.

Al superar un límite posterior a la autenticación se devuelve `429` con cabeceras `RateLimit-*`.

### Paginación

Los endpoints de listado devuelven una página de resultados con el formato `{ "items": [...], "nextCursor": ... }`. Pasa `limit` (de 1 a 100; 50 por defecto) para definir el tamaño de página. Si `nextCursor` es una cadena, envíalo como `cursor` para obtener la página siguiente; si es `null`, no hay más resultados. Un cursor solo es válido para el listado y los filtros que lo generaron. Cada página se lee de forma independiente, por lo que los elementos que cambien entre solicitudes pueden omitirse o aparecer repetidos.

### Errores

A partir de la versión de la API `2026-02-18.v1`, los errores devuelven un cuerpo JSON con un mensaje en `error` y un `code` estable. Esto incluye JSON mal formado (`400`), cuerpos demasiado grandes (`413`) y límites de solicitudes superados (`429`). Las versiones anteriores devuelven la mayoría de los errores como texto sin formato, sin `code`.

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

`code` indica la causa. Una ruta puede devolver un código más específico que el código genérico correspondiente a su estado; la referencia de cada endpoint enumera los códigos que puede devolver. Es posible que se añadan códigos nuevos, así que trata cualquier código desconocido según su estado HTTP.

Códigos de estado habituales y su `code` genérico:

* `400` `invalid_request` para un cuerpo de solicitud, una consulta o una versión no válidos. Un cuerpo gzip dañado o truncado devuelve `invalid_content_encoding`.
* `401` `unauthenticated` si falta la credencial bearer o no es válida.
* `402` `payment_required` cuando la cuenta de facturación de la Organization está bloqueada, o cuando el límite de uso de su plan, el límite de gasto mensual o el saldo de créditos no cubren la solicitud (traducción de archivos y traducción en tiempo de ejecución).
* `403` `permission_denied` cuando la identidad de la solicitud no tiene permiso o la acción no está permitida en el plan actual. Si falta un permiso, se devuelve `permission_missing` y el permiso se indica en `error`.
* `404` `not_found` cuando no se encuentra el recurso.
* `409` `conflict` cuando hay un conflicto, por ejemplo, al crear un Project que supera el límite de Projects de la Organization, al usar un nombre de rama que ya existe o al cambiar un nombre que coincide con un término del glosario o un prompt personalizado existente.
* `410` `route_retired` cuando la ruta se ha retirado en la versión de la API solicitada. `error` indica la ruta que debe usarse en su lugar.
* `413` `payload_too_large` cuando el cuerpo de la solicitud supera el límite del endpoint, o cuando una respuesta de Context Management superaría 1 MiB (solicita un `limit` menor).
* `415` `unsupported_media_type` cuando falta el `Content-Type` del cuerpo de la solicitud o no es `application/json`. Un `Content-Encoding` no admitido devuelve `unsupported_content_encoding`. Envía el cuerpo sin comprimir o codificado con gzip.
* `423` `locked` cuando el recurso está bloqueado por una operación en curso.
* `425` `not_ready` cuando el resultado solicitado aún no está listo.
* `429` `rate_limited` cuando se supera un límite de solicitudes.
* `500` `internal_error` para un error interno del servidor.
* `502` `upstream_error` cuando un servicio upstream no consigue completar la solicitud.
* `503` `unavailable` cuando el servicio no está disponible temporalmente.

Reintenta las respuestas `429` y `503` pasado un tiempo. En el caso de `429`, espera los segundos indicados en la cabecera `Retry-After`.

## Especificación OpenAPI [#openapi-spec]

Hay una especificación OpenAPI 3.1 legible por máquinas de la versión más reciente disponible en [`/openapi.json`](/openapi.json), y la de cada versión anterior está en `/openapi/<version>.json`. Impórtala en Postman, Insomnia o en un cliente OpenAPI para generar solicitudes y tipos.

Para helpers de endpoint tipados, usa el [cliente `@generaltranslation/api`](/docs/platform/core/reference/api-client).

## Sitemap

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