# General Translation Platform: Panoramica
URL: https://generaltranslation.com/it/docs/platform/openapi/overview.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Chiama gli endpoint pubblici dell'API di General Translation e scarica la specifica OpenAPI.

Usa l&#39;API di General Translation per creare workflow di automazione personalizzati.

La CLI gestisce per te la maggior parte delle chiamate API. Usa il [client TypeScript `@generaltranslation/api`](/docs/platform/core/reference/api-client) per i tipi generati di richiesta e risposta, oppure chiama direttamente gli endpoint quando ti serve un&#39;automazione personalizzata.

La specifica OpenAPI definisce questi endpoint in un formato leggibile dalle macchine.

## Concetti di base dell&#39;API [#api-basics]

### URL di base

Tutti gli endpoint, inclusa la traduzione in fase di esecuzione con `POST /v2/projects/{projectId}/translate`, sono disponibili all&#39;indirizzo `https://api.gtx.dev`.

### Autenticazione

Esegui l&#39;autenticazione con una chiave API nell&#39;intestazione 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"
```

Scegli l&#39;ambito della chiave adatto al tuo workflow:

* **progetto** con prefisso `gtx-api-`: associata a un progetto e utilizzabile in qualsiasi ambiente, in base alle sue autorizzazioni
* **Organizzazione** con prefisso `gtx-org-`: funziona in tutti i progetti dell&#39;Organizzazione a cui è associata, in base alle sue autorizzazioni

Il percorso determina su cosa agisce una richiesta: `/v2/projects/{projectId}/...` sul progetto, `/v2/orgs/{orgId}/...` sull&#39;Organizzazione e `/v2/context-groups/{groupId}/...` sull&#39;Organizzazione proprietaria del gruppo. Gli endpoint di individuazione (`GET /v2/orgs` e `GET /v2/projects`) non richiedono alcun ID. La chiave deve avere accesso al progetto o all&#39;Organizzazione selezionati, quindi una chiave di progetto funziona solo sul proprio progetto e sui gruppi di contesto a esso assegnati.

Non includere le chiavi API nei bundle distribuiti per browser e dispositivi mobili.

(Vedi [chiavi API](/docs/platform/dashboard/reference/api-keys) per sapere come creare e definire l&#39;ambito delle chiavi API).

### Autorizzazioni

La maggior parte degli endpoint richiede un&#39;autorizzazione sull&#39;identità della richiesta. [List Organizations](/docs/platform/openapi/reference/organizations/list-orgs), [List Projects](/docs/platform/openapi/reference/projects/list-projects) e [Get a Project](/docs/platform/openapi/reference/projects/get-project) non richiedono alcuna autorizzazione sulle risorse, oltre all&#39;accesso all&#39;Organizzazione o al progetto restituiti. Sia le chiavi di Organizzazione sia quelle di progetto supportano autorizzazioni **All** o **Custom** nella Dashboard, limitate alle autorizzazioni che il creatore può concedere. L&#39;[endpoint delle chiavi API di progetto](/docs/platform/openapi/reference/api-keys/create-project-api-key) consente di selezionare le autorizzazioni oppure di omettere la selezione per concedere tutte le autorizzazioni di progetto che puoi delegare. Le autorizzazioni Write non includono Read. Le chiavi di progetto non possono avere autorizzazioni a livello di Organizzazione (`org:*`), `project:api_keys:read` né `project:api_keys:write`, quindi gli endpoint che le richiedono necessitano di una chiave di Organizzazione.

Autorizzazioni comuni:

* `org:projects:create` per creare progetti con `POST /v2/orgs/{orgId}/projects`.
* `project:api_keys:read` per elencare e leggere le chiavi API di progetto.
* `project:api_keys:write` per creare chiavi API di progetto con `POST /v2/projects/{projectId}/api-keys` ed eliminarle.
* `org:assets:write` per caricare font con `POST /v2/orgs/{orgId}/assets`.
* `project:files:read` per scaricare file; leggere i metadati e lo stato dei file; elencare i branch e i relativi file; e leggere i job.
* `project:files:write` per caricare file sorgente e traduzioni; sovrascrivere traduzioni; pubblicare; creare e aggiornare branch; impostare tag; e spostare file.
* `project:translations:enqueue` per tradurre file con `POST /v2/projects/{projectId}/files/translate`.
* `project:translations:generate` per la traduzione in fase di esecuzione.
* `project:context:read` per leggere i gruppi di contesto assegnati al progetto, il relativo Glossario e i prompt personalizzati, nonché le esportazioni.
* `project:context:write` per generare il contesto, nonché per modificare il Glossario e i prompt personalizzati dei gruppi di contesto assegnati al progetto, importarvi contenuti e riordinarli.
* `org:context:read` per leggere tutti i gruppi di contesto dell&#39;Organizzazione, il relativo Glossario e i prompt personalizzati, le assegnazioni ai progetti e le esportazioni.
* `org:context:write` per creare, aggiornare ed eliminare i gruppi di contesto e il relativo contenuto, importare contenuti, nonché assegnare i gruppi ai progetti, revocarne l&#39;assegnazione e riordinarli.
* `project:write` per aggiornare le impostazioni del progetto.

Gli endpoint di Context Management che leggono o modificano il contenuto di un gruppo, così come quelli che elencano, leggono o riordinano i gruppi di un progetto, accettano sia l&#39;autorizzazione di Organizzazione sia l&#39;autorizzazione di progetto relativa a un progetto a cui il gruppo è assegnato. Per elencare i gruppi di un&#39;Organizzazione, creare, aggiornare ed eliminare un gruppo, nonché assegnarlo o revocarne l&#39;assegnazione, è necessaria l&#39;autorizzazione di Organizzazione. Un gruppo su cui l&#39;identità della richiesta non può operare restituisce lo stesso `403` di un gruppo inesistente.

### Versionamento

Invia l&#39;intestazione `gt-api-version` con ogni richiesta per selezionare il contratto dell&#39;API.

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

* Gli endpoint la cui pagina di riferimento indica l&#39;intestazione come obbligatoria restituiscono `400` se l&#39;intestazione è assente o specifica una versione precedente.
* Gli altri endpoint, se l&#39;intestazione è assente, usano la versione supportata meno recente e restituiscono gli errori in testo semplice anziché in JSON.

Per consultare gli endpoint di una versione precedente, selezionala nel menu della versione dell&#39;API in cima a qualsiasi pagina OpenAPI.

### Corpo delle richieste

Invia i dati in formato JSON con `Content-Type: application/json`. Puoi comprimere il corpo con gzip e impostare `Content-Encoding` su `gzip` o `x-gzip`. I limiti di dimensione si applicano al corpo decompresso. Un corpo codificato che supera già il limite della route viene rifiutato prima ancora di essere decodificato.

### Risposte delle operazioni di scrittura

Un&#39;operazione di scrittura restituisce ciò che ha modificato, nella stessa forma in cui la restituirebbe una lettura della stessa risorsa.

* La **creazione** di un progetto, di un branch, di un Context Group o di una chiave API di progetto con `POST` restituisce `201` con la nuova risorsa. Una nuova chiave API include anche la relativa `key` segreta, che non viene restituita in nessuna risposta successiva.
* L&#39;**aggiornamento** di una risorsa con `PATCH` restituisce `200` con la risorsa aggiornata.
* Gli endpoint **`PUT`** (impostazione di un tag, assegnazione di un Context Group e impostazione della traduzione di un termine del Glossario) restituiscono la risorsa con `201` se la richiesta l&#39;ha creata e con `200` se esisteva già.
* L&#39;**eliminazione** restituisce `200` con `{ "deleted": true }`.

<Callout type="info">
  **Modificato in `2026-10-08.v1`:** le operazioni di scrittura di Context Management restituiscono la risorsa, `counts` o `deleted` anziché `committed: true`. La creazione di un progetto o di una chiave API di progetto restituisce la risorsa senza il wrapper `project` o `apiKey`. La traduzione in fase di esecuzione accetta `requests` come array e restituisce `summary` e `results` anziché un oggetto con una chiave per ogni richiesta. Le versioni precedenti mantengono le proprie risposte: per consultarle, selezionane una nel menu della versione API.
</Callout>

### Richieste batch

Gli endpoint batch elencati di seguito restituiscono un risultato per ogni elemento, nello stesso ordine della richiesta.

* **Scritture** (caricamento di file sorgente e traduzioni, spostamento, pubblicazione e sovrascrittura di file, caricamento di asset dei font): restituiscono `200` con `summary` (conteggi `total`, `succeeded` e `failed`) e `results`, anche quando tutti gli elementi non vanno a buon fine. Un elemento non riuscito ha `status: "failed"` e un `error`; gli altri elementi vengono comunque applicati. Una richiesta che non supera la validazione restituisce `400` e non applica alcuna modifica.
* **Traduzione in fase di esecuzione** (`POST /v2/projects/{projectId}/translate`): accetta `requests` come array e restituisce `200` con `summary` e `results`. Una voce che non è stato possibile tradurre ha `status: "failed"` con un `error` e un `code`; le altre voci vengono comunque tradotte. Il contenuto ripetuto viene tradotto una volta per ciascuna voce, quindi invia ogni stringa una sola volta.
* **Letture** (query su file, contenuto dei file e job): restituiscono `200` con `results`. Un elemento non presente nel progetto risulta `not_found`. Una traduzione di file già memorizzata ma non ancora completata, ad esempio durante un passaggio di layout, risulta `pending`: richiedila di nuovo più tardi. Una traduzione risulta `not_found` finché la relativa attività di traduzione non l&#39;ha memorizzata, quindi prima di leggerla attendi il completamento del job con `GET /v2/projects/{projectId}/jobs/{jobId}` o `POST /v2/projects/{projectId}/jobs/query`. Senza `versionId`, una lettura restituisce la versione completata più recente sul branch e risulta `pending` solo finché nessuna versione è stata completata. Le query sui job restituiscono lo stato di ciascun job.

Gli altri endpoint batch prevedono una risposta specifica. L&#39;accodamento della traduzione di file restituisce `202` con i `jobs` creati. Gli upsert del Glossario e dei Prompt Personalizzati di Context Management applicano l&#39;intero batch oppure nulla e restituiscono `counts` (`created`, `updated` e `unchanged`) con `items`: un `id` e un `outcome` per ogni elemento, nello stesso ordine della richiesta.

### Limiti dei metadati a runtime

Per `POST /v2/projects/{projectId}/translate`, un valore intero positivo di `maxChars` aggiunge un&#39;istruzione sulla lunghezza ai prompt di traduzione supportati; non è un limite garantito sulla lunghezza dell&#39;output. I numeri non positivi o frazionari vengono ignorati. I valori di tipo errato fanno fallire la validazione della richiesta.

Ogni file `sourceCode` conserva al massimo cinque entry di contesto. L&#39;API tronca i campi `before` e `after` di ogni entry a 2.000 caratteri e il campo `target` a 500 caratteri.

Imposta `fileFormat` su `MD` o `MDX` per tradurre un intero documento fornito come stringa. Le richieste di documenti devono usare `dataFormat: STRING` e non possono includere `maxChars` o `sourceCode`. L&#39;API analizza il documento suddividendolo in blocchi, aggiunge il contesto della richiesta a ciascun blocco e restituisce una singola stringa di documento validata. Un blocco non riuscito o un documento finale non valido fa fallire quella entry anziché restituire un output parziale.

### Allowlist delle impostazioni regionali

La traduzione in fase di esecuzione restituisce `403` con codice `locale_not_allowed` quando il progetto ha un elenco di impostazioni regionali non vuoto e `targetLocale` non è incluso in tale elenco. Un elenco di impostazioni regionali vuoto non pone limiti alle impostazioni locali di destinazione. Un batch servito interamente dalla cache salta questo controllo: un&#39;impostazione regionale rimossa dal progetto può quindi continuare a restituire le traduzioni presenti nella cache.

### Limiti di frequenza

I limiti di frequenza si applicano su finestre di 60 secondi, a due livelli:

* **Prima dell&#39;autenticazione:** ogni credenziale presentata può effettuare 600 tentativi al minuto, comprese le richieste che non superano l&#39;autenticazione. Le richieste prive di credenziale non sono soggette a questo livello. Il superamento del limite restituisce `429` con `Retry-After: 60` e senza intestazioni `RateLimit-*`.
* **Dopo l&#39;autenticazione:** ogni gruppo di route limita le richieste per chiamante autenticato, ad esempio una chiave API. Per le route soggette a limiti prive di un chiamante autenticato viene utilizzato l&#39;IP del client.

I limiti successivi all&#39;autenticazione variano in base all&#39;endpoint:

* **Heavy:** 30 richieste/minuto per la traduzione di file.
* **Medium:** 120 richieste/minuto per il caricamento di file sorgente, traduzioni e font; la sovrascrittura delle traduzioni; la generazione del contesto; lo spostamento di file; l&#39;elenco dei file del branch e la pubblicazione.
* **Light:** 300 richieste/minuto per il download di file.
* **Default:** 200 richieste/minuto per l&#39;individuazione di progetti e Organizzazioni, la creazione di progetti, le chiavi API di progetto, le impostazioni del progetto, branch, tag, job, metadati e stato dei file, traduzione in fase di esecuzione e Context Management.

L&#39;elenco dei progetti, la creazione di progetti e l&#39;elenco, la lettura, la creazione e l&#39;eliminazione di chiavi API di progetto condividono un unico limite.

Il superamento di un limite successivo all&#39;autenticazione restituisce `429` con intestazioni `RateLimit-*`.

### Paginazione

Gli endpoint di elenco restituiscono una pagina di risultati nel formato `{ "items": [...], "nextCursor": ... }`. Passa `limit` (da 1 a 100, valore predefinito 50) per impostare la dimensione della pagina. Quando `nextCursor` è una string, invialo come `cursor` per recuperare la pagina successiva; quando è `null`, non ci sono altri risultati. Un cursore è valido solo per l&#39;elenco e i filtri che lo hanno generato. Le pagine vengono lette in modo indipendente, quindi gli elementi modificati tra una richiesta e l&#39;altra potrebbero essere saltati o comparire più volte.

### Errori

A partire dalla versione dell&#39;API `2026-02-18.v1`, gli errori restituiscono un corpo JSON con un messaggio `error` e un `code` stabile. Questo vale anche per JSON non valido (`400`), corpi di dimensioni eccessive (`413`) e limiti di frequenza (`429`). Le versioni precedenti restituiscono la maggior parte degli errori come testo semplice, senza `code`.

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

`code` indica la causa. Una route può restituire un codice più specifico rispetto al codice generico associato al suo stato; il riferimento di ciascun endpoint elenca i codici che può restituire. Potrebbero essere aggiunti nuovi codici, quindi gestisci un codice non riconosciuto come il relativo stato HTTP.

Codici di stato comuni e relativo `code` generico:

* `400` `invalid_request` per un corpo, una query o una versione della richiesta non validi. Un corpo gzip danneggiato o troncato restituisce `invalid_content_encoding`.
* `401` `unauthenticated` per una credenziale bearer mancante o non valida.
* `402` `payment_required` quando l&#39;account di fatturazione dell&#39;Organizzazione è bloccato, oppure quando il limite di utilizzo del piano, il limite di spesa mensile o il saldo dei crediti non sono sufficienti a coprire la richiesta (traduzione di file e traduzione in fase di esecuzione).
* `403` `permission_denied` quando l&#39;identità della richiesta non dispone del permesso necessario o l&#39;azione non è consentita dal piano attuale. Un permesso mancante restituisce `permission_missing` e ne indica il nome in `error`.
* `404` `not_found` quando la risorsa non viene trovata.
* `409` `conflict` in caso di conflitto, ad esempio la creazione di un progetto oltre il limite di progetti dell&#39;Organizzazione, un nome di branch già in uso o una ridenominazione in conflitto con un termine del Glossario o un Prompt Personalizzato esistente.
* `410` `route_retired` quando la route è stata ritirata nella versione dell&#39;API richiesta. `error` indica la route da usare al suo posto.
* `413` `payload_too_large` quando il corpo della richiesta supera il limite dell&#39;endpoint o quando una risposta di Context Management supererebbe 1 MiB (richiedi un `limit` più piccolo).
* `415` `unsupported_media_type` quando il `Content-Type` del corpo della richiesta è assente o diverso da `application/json`. Un `Content-Encoding` non supportato restituisce `unsupported_content_encoding`. Invia il corpo non compresso o con codifica gzip.
* `423` `locked` quando la risorsa è bloccata da un&#39;operazione in corso.
* `425` `not_ready` quando il risultato richiesto non è ancora pronto.
* `429` `rate_limited` quando viene superato un limite di frequenza.
* `500` `internal_error` per un errore interno del server.
* `502` `upstream_error` quando un servizio upstream non riesce a completare la richiesta.
* `503` `unavailable` quando il servizio è temporaneamente non disponibile.

In caso di risposte `429` e `503`, riprova dopo un intervallo di attesa. Per `429`, attendi il numero di secondi indicato nell&#39;intestazione `Retry-After`.

## Specifica OpenAPI [#openapi-spec]

Una specifica OpenAPI 3.1 dell&#39;ultima versione, in formato leggibile dalle macchine, è disponibile all&#39;indirizzo [`/openapi.json`](/openapi.json), mentre quella di ciascuna versione precedente si trova in `/openapi/<version>.json`. Importala in Postman, Insomnia o in un client OpenAPI per generare richieste e tipi.

Per gli helper tipizzati degli endpoint, usa il [client `@generaltranslation/api`](/docs/platform/core/reference/api-client).

## Sitemap

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