# General Translation Platform: Vue d’ensemble
URL: https://generaltranslation.com/fr/docs/platform/openapi/overview.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Appelez les endpoints publics de l’API General Translation et téléchargez la spécification OpenAPI.

Utilisez l’API General Translation pour créer des workflows d’automatisation personnalisés.

La CLI gère la plupart des appels à l’API pour vous. Utilisez le [client TypeScript `@generaltranslation/api`](/docs/platform/core/reference/api-client) pour disposer des types de requête et de réponse générés, ou appelez directement les endpoints lorsque vous avez besoin d’une automatisation personnalisée.

La spécification OpenAPI définit ces endpoints dans un format lisible par machine.

## Notions de base de l’API [#api-basics]

### URL de base

Tous les endpoints, y compris celui de la traduction à l’exécution (`POST /v2/projects/{projectId}/translate`), sont accessibles sous `https://api.gtx.dev`.

### Authentification

Authentifiez-vous avec une clé API dans l’en-tête standard `Authorization`.

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

Choisissez la portée de clé qui correspond à votre workflow :

* **Projet** avec le préfixe `gtx-api-` : liée à un seul projet et utilisable dans n’importe quel environnement, selon ses autorisations
* **Organisation** avec le préfixe `gtx-org-` : fonctionne sur tous les projets de l’Organisation à laquelle elle est liée, selon ses autorisations

Le chemin détermine la cible d’une requête : `/v2/projects/{projectId}/...` cible le projet, `/v2/orgs/{orgId}/...` l’Organisation, et `/v2/context-groups/{groupId}/...` l’Organisation à laquelle appartient le groupe. Les points de terminaison de découverte (`GET /v2/orgs` et `GET /v2/projects`) ne nécessitent aucun identifiant. La clé doit avoir accès au projet ou à l’Organisation sélectionné ; une clé de projet ne fonctionne donc que sur son propre projet et sur les groupes de contexte qui lui sont assignés.

N’incluez jamais de clés API dans les bundles déployés pour le navigateur ou les applications mobiles.

(Consultez [les clés API](/docs/platform/dashboard/reference/api-keys) pour savoir comment créer des clés API et définir leur portée).

### Autorisations

La plupart des points de terminaison nécessitent une autorisation sur l’identité de la requête. [List Organizations](/docs/platform/openapi/reference/organizations/list-orgs), [List Projects](/docs/platform/openapi/reference/projects/list-projects) et [Get a Project](/docs/platform/openapi/reference/projects/get-project) ne nécessitent aucune autorisation sur une ressource, au-delà de l’accès à l’organisation ou au projet renvoyé. Les clés d’organisation comme les clés de projet prennent en charge les autorisations **All** ou **Custom** dans le dashboard, dans la limite des autorisations que le créateur peut accorder. L’[point de terminaison de clé API de projet](/docs/platform/openapi/reference/api-keys/create-project-api-key) vous permet de sélectionner des autorisations, ou d’omettre la sélection pour accorder toutes les autorisations de projet que vous pouvez déléguer. Les autorisations Write n’incluent pas Read. Les clés de projet ne peuvent pas détenir d’autorisations d’organisation (`org:*`), ni `project:api_keys:read`, ni `project:api_keys:write` ; les points de terminaison qui les exigent nécessitent donc une clé d’organisation.

Autorisations courantes :

* `org:projects:create` pour créer des projets avec `POST /v2/orgs/{orgId}/projects`.
* `project:api_keys:read` pour lister et consulter les clés API de projet.
* `project:api_keys:write` pour créer des clés API de projet avec `POST /v2/projects/{projectId}/api-keys` et les supprimer.
* `org:assets:write` pour téléverser des polices avec `POST /v2/orgs/{orgId}/assets`.
* `project:files:read` pour télécharger des fichiers ; consulter les métadonnées et l’état des fichiers ; lister les branches et leurs fichiers ; et consulter les tâches.
* `project:files:write` pour téléverser des fichiers sources et des traductions ; écraser des traductions ; publier ; créer et mettre à jour des branches ; définir des tags ; et déplacer des fichiers.
* `project:translations:enqueue` pour traduire des fichiers avec `POST /v2/projects/{projectId}/files/translate`.
* `project:translations:generate` pour la traduction à l’exécution.
* `project:context:read` pour consulter les groupes de contexte attribués au projet, leur glossaire et leurs instructions personnalisées, ainsi que leurs exports.
* `project:context:write` pour générer le contexte, ainsi que pour modifier le glossaire et les instructions personnalisées des groupes de contexte attribués au projet, y importer du contenu et en modifier l’ordre.
* `org:context:read` pour consulter tous les groupes de contexte de l’organisation, leur glossaire et leurs instructions personnalisées, leurs attributions aux projets et leurs exports.
* `org:context:write` pour créer, modifier et supprimer des groupes de contexte et leur contenu, importer du contenu, ainsi qu’attribuer des groupes aux projets, les en retirer et en modifier l’ordre.
* `project:write` pour mettre à jour les paramètres du projet.

Les points de terminaison de gestion du contexte qui consultent ou modifient le contenu d’un groupe, ainsi que ceux qui listent, consultent ou réordonnent les groupes d’un projet, acceptent soit l’autorisation d’organisation, soit l’autorisation de projet sur un projet auquel le groupe est attribué. Lister les groupes d’une organisation, créer, modifier ou supprimer un groupe, ainsi que l’attribuer à un projet ou l’en retirer, nécessite l’autorisation d’organisation. Un groupe sur lequel l’identité de la requête ne peut pas agir renvoie la même erreur `403` qu’un groupe inexistant.

### Gestion des versions

Envoyez l&#39;en-tête `gt-api-version` dans chaque requête pour sélectionner le contrat d&#39;API.

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

* Les endpoints dont la page de référence indique que l&#39;en-tête est obligatoire renvoient une erreur `400` si celui-ci est absent ou spécifie une version plus ancienne.
* Les autres endpoints utilisent la plus ancienne version prise en charge lorsque l&#39;en-tête est absent, et renvoient leurs erreurs en texte brut plutôt qu&#39;en JSON.

Pour consulter les endpoints d&#39;une version plus ancienne, sélectionnez-la dans le menu de version de l&#39;API, en haut de n&#39;importe quelle page OpenAPI.

### Corps de requête

Envoyez du JSON avec l&#39;en-tête `Content-Type: application/json`. Vous pouvez compresser ce corps avec gzip et définir `Content-Encoding` sur `gzip` ou `x-gzip`. Les limites de taille s&#39;appliquent au corps décompressé. Un corps encodé dont la taille dépasse déjà la limite de la route est rejeté avant même d&#39;être décodé.

### Réponses des opérations d’écriture

Une opération d’écriture renvoie ce qu’elle a modifié, sous la même forme qu’une lecture de la même ressource.

* **La création** d’un projet, d’une branche, d’un groupe de contexte ou d’une clé API de projet avec `POST` renvoie `201` avec la nouvelle ressource. Une nouvelle clé API inclut également sa `key` secrète, qu’aucune réponse ultérieure ne renvoie.
* **La mise à jour** d’une ressource avec `PATCH` renvoie `200` avec la ressource mise à jour.
* **Les points de terminaison `PUT`** (définition d’un tag, attribution d’un groupe de contexte et définition de la traduction d’un terme du glossaire) renvoient la ressource avec `201` si la requête l’a créée, et `200` si elle existait déjà.
* **La suppression** renvoie `200` avec `{ "deleted": true }`.

<Callout type="info">
  **Modifié dans `2026-10-08.v1`** : les opérations d’écriture de Context Management renvoient la ressource, `counts` ou `deleted` au lieu de `committed: true`. La création d’un projet ou d’une clé API de projet renvoie la ressource sans l’enveloppe `project` ou `apiKey`. La traduction à l’exécution accepte `requests` sous forme de tableau et renvoie `summary` et `results` au lieu d’un objet indexé par requête. Les versions antérieures conservent leurs réponses ; sélectionnez-en une dans le menu des versions de l’API pour les consulter.
</Callout>

### Requêtes par lots

Les points de terminaison par lots ci-dessous renvoient un résultat par élément, dans l&#39;ordre de la requête.

* **Écritures** (téléversement de fichiers sources et de traductions, déplacement, publication et écrasement de fichiers, et téléversement de ressources de polices) : renvoient `200` avec `summary` (nombres `total`, `succeeded` et `failed`) et `results`, même lorsque tous les éléments échouent. Un élément en échec a `status: "failed"` et une `error` ; les autres éléments sont tout de même appliqués. Une requête dont la validation échoue renvoie `400` et n&#39;applique rien.
* **Traduction à l’exécution** (`POST /v2/projects/{projectId}/translate`) : accepte `requests` sous forme de tableau et renvoie `200` avec `summary` et `results`. Une entrée qui n&#39;a pas pu être traduite a `status: "failed"` avec une `error` et un `code` ; les autres entrées sont tout de même traduites. Un contenu répété est traduit autant de fois qu&#39;il apparaît : envoyez donc chaque chaîne de caractères une seule fois.
* **Lectures** (requêtes de fichiers, de contenu de fichiers et de tâches) : renvoient `200` avec `results`. Un élément absent du projet est `not_found`. Une traduction de fichier stockée mais pas encore terminée, par exemple pendant une passe de mise en page, est `pending` ; renvoyez la requête plus tard. Une traduction est `not_found` tant que sa tâche de traduction ne l&#39;a pas encore stockée : attendez donc la fin de la tâche avec `GET /v2/projects/{projectId}/jobs/{jobId}` ou `POST /v2/projects/{projectId}/jobs/query` avant de la lire. Sans `versionId`, une lecture renvoie la version terminée la plus récente sur la branche, et n&#39;est `pending` que tant qu&#39;aucune version n&#39;est terminée. Les requêtes de tâches renvoient l&#39;état de chaque tâche.

Les autres points de terminaison par lots ont leur propre format de réponse. La mise en file d&#39;attente d&#39;une traduction de fichiers renvoie `202` avec les `jobs` créées. Les upserts de glossaire et d&#39;instructions personnalisées de Context Management appliquent le lot entier ou rien du tout, et renvoient `counts` (`created`, `updated` et `unchanged`) avec `items` : un `id` et un `outcome` par élément, dans l&#39;ordre de la requête.

### Limites des métadonnées d&#39;exécution

Pour `POST /v2/projects/{projectId}/translate`, un entier positif `maxChars` ajoute une instruction de longueur aux invites de traduction prises en charge ; il ne constitue pas une limite garantie sur la longueur de la sortie. Les nombres négatifs, nuls ou fractionnaires sont ignorés. Les valeurs d&#39;un type incorrect font échouer la validation de la requête.

Chaque fichier `sourceCode` conserve au maximum cinq entrées de contexte. L&#39;API tronque les champs `before` et `after` de chaque entrée à 2 000 caractères, et son champ `target` à 500 caractères.

Définissez `fileFormat` sur `MD` ou `MDX` pour traduire un document entier fourni sous forme de chaîne de caractères. Les requêtes de document doivent utiliser `dataFormat: STRING` et ne peuvent pas inclure `maxChars` ni `sourceCode`. L&#39;API découpe le document en fragments, ajoute le contexte de la requête à chaque fragment et renvoie une seule chaîne de caractères de document validée. Un fragment en échec ou un document final invalide fait échouer cette entrée plutôt que de renvoyer une sortie partielle.

### Liste d’autorisation des locales

La traduction à l’exécution renvoie `403` avec le code `locale_not_allowed` lorsque la liste des locales du projet n’est pas vide et que `targetLocale` n’y figure pas. Une liste de locales vide n’impose aucune restriction sur les locales cibles. Un lot servi entièrement depuis le cache échappe à cette vérification : une locale retirée du projet peut donc continuer à renvoyer ses traductions en cache.

### Limites de débit

La limitation de débit s’applique sur des fenêtres de 60 secondes, à deux niveaux :

* **Avant l’authentification :** chaque identifiant d’authentification présenté peut effectuer 600 tentatives par minute, y compris les requêtes dont l’authentification échoue. Les requêtes sans identifiant d’authentification ne sont pas concernées par ce niveau. En cas de dépassement, l’API renvoie `429` avec `Retry-After: 60`, sans en-têtes `RateLimit-*`.
* **Après l’authentification :** chaque groupe de routes limite les requêtes par appelant authentifié, par exemple une clé API. Pour les routes limitées sans appelant authentifié, c’est l’adresse IP cliente qui est utilisée.

Les limites après authentification varient selon l’endpoint :

* **Élevé :** 30 requêtes/minute pour la traduction de fichiers.
* **Moyen :** 120 requêtes/minute pour le téléversement de fichiers sources, de traductions et de polices ; l’écrasement de traductions ; la génération de contexte ; le déplacement de fichiers ; le listage des fichiers d’une branche ; et la publication.
* **Faible :** 300 requêtes/minute pour les téléchargements de fichiers.
* **Par défaut :** 200 requêtes/minute pour la découverte de projets et d’organisations, la création de projet, les clés API de projet, les paramètres du projet, les branches, les tags, les tâches, les métadonnées et l’état des fichiers, la traduction à l’exécution et Context Management.

Le listage des projets, la création de projets ainsi que le listage, la lecture, la création et la suppression de clés API de projet partagent une même limite.

En cas de dépassement d’une limite après authentification, l’API renvoie `429` avec des en-têtes `RateLimit-*`.

### Pagination

Les endpoints de liste renvoient une seule page de résultats au format `{ "items": [...], "nextCursor": ... }`. Passez `limit` (de 1 à 100, valeur par défaut : 50) pour définir la taille de la page. Lorsque `nextCursor` est une chaîne de caractères, transmettez-la dans `cursor` pour récupérer la page suivante ; lorsqu&#39;il vaut `null`, il n&#39;y a plus de résultats. Un curseur n&#39;est valable que pour la liste et les filtres qui l&#39;ont généré. Les pages étant lues indépendamment les unes des autres, les éléments modifiés entre deux requêtes peuvent être omis ou apparaître en double.

### Erreurs

À partir de la version d&#39;API `2026-02-18.v1`, les erreurs renvoient un corps JSON contenant un message `error` et un `code` stable. C&#39;est notamment le cas pour un JSON mal formé (`400`), un corps trop volumineux (`413`) et un dépassement de la limite de débit (`429`). Les versions antérieures renvoient la plupart des erreurs en texte brut, sans `code`.

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

`code` indique la cause. Une route peut renvoyer un code plus spécifique que le code générique associé à son état ; la référence de chaque endpoint liste les codes qu&#39;il peut renvoyer. De nouveaux codes peuvent être ajoutés : traitez donc tout code non reconnu selon son état HTTP.

Codes d&#39;état courants et leur `code` générique :

* `400` `invalid_request` pour un corps de requête, des paramètres de requête ou une version invalides. Un corps gzip corrompu ou tronqué renvoie `invalid_content_encoding`.
* `401` `unauthenticated` pour un identifiant d’authentification bearer manquant ou invalide.
* `402` `payment_required` lorsque le compte de facturation de l&#39;Organisation est bloqué, ou que la limite d&#39;utilisation de son offre, sa limite de dépenses mensuelles ou son solde de crédits ne suffit pas à couvrir la requête (traduction de fichiers et traduction à l’exécution).
* `403` `permission_denied` lorsque l&#39;identité à l&#39;origine de la requête ne dispose pas de l&#39;Autorisation nécessaire ou que l&#39;action n&#39;est pas permise par l&#39;offre actuelle. Une Autorisation manquante renvoie `permission_missing` et précise l&#39;Autorisation concernée dans `error`.
* `404` `not_found` lorsque la ressource est introuvable.
* `409` `conflict` en cas de conflit, par exemple la création d&#39;un projet au-delà de la limite de projets de l&#39;Organisation, un nom de branche déjà utilisé, ou un renommage qui entre en conflit avec un terme de glossaire ou une instruction personnalisée existants.
* `410` `route_retired` lorsque la route a été retirée dans la version d&#39;API demandée. `error` indique la route à utiliser à la place.
* `413` `payload_too_large` lorsque le corps de la requête dépasse la limite de l&#39;endpoint, ou lorsqu&#39;une réponse de Context Management dépasserait 1 Mio (demandez une valeur de `limit` plus petite).
* `415` `unsupported_media_type` lorsque l&#39;en-tête `Content-Type` du corps de la requête est absent ou n&#39;est pas `application/json`. Un `Content-Encoding` non pris en charge renvoie `unsupported_content_encoding`. Envoyez le corps non compressé ou compressé en gzip.
* `423` `locked` lorsque la ressource est verrouillée par une opération en cours.
* `425` `not_ready` lorsque le résultat demandé n&#39;est pas encore prêt.
* `429` `rate_limited` lorsqu&#39;une limite de débit est dépassée.
* `500` `internal_error` pour une erreur interne du serveur.
* `502` `upstream_error` lorsqu&#39;un service en amont ne parvient pas à traiter la requête.
* `503` `unavailable` lorsque le service est temporairement indisponible.

En cas de réponse `429` ou `503`, réessayez après un certain délai. Pour `429`, attendez le nombre de secondes indiqué dans l&#39;en-tête `Retry-After`.

## Spécification OpenAPI [#openapi-spec]

Une spécification OpenAPI 3.1 lisible par machine de la dernière version est disponible à l’adresse [`/openapi.json`](/openapi.json), et celle de chaque version antérieure à l’adresse `/openapi/<version>.json`. Importez-la dans Postman, Insomnia ou un client OpenAPI pour générer des requêtes et des types.

Pour des utilitaires d’endpoint typés, utilisez le [client `@generaltranslation/api`](/docs/platform/core/reference/api-client).

## Sitemap

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