# General Translation Platform: Crea o aggiorna un'etichetta
URL: https://generaltranslation.com/it/docs/platform/openapi/reference/project/upsert-tag.mdx
---

title: Crea o aggiorna un'etichetta
description: Crea o aggiorna un'etichetta nelle versioni dei file di General Translation per monitorare i rilasci. Riferimento API per Crea o aggiorna un'etichetta.

method: POST
---

Crea un'etichetta per un insieme di versioni di file oppure sovrascrive un'etichetta esistente con lo stesso ID. Usa le etichette per contrassegnare le versioni di file che appartengono a un rilascio.

## Panoramica [#overview]

```http
POST https://api2.gtx.dev/v2/project/tags/create
```

**Permesso** `project:files:write` · **Rate limit** Predefinito (200/min)

Fissa un'etichetta denominata a versioni specifiche dei file. Per risolvere prima i riferimenti ai file, usa [Ottieni informazioni sul file](/docs/platform/openapi/reference/files/file-info).

## Come funziona [#how-it-works]

* Ogni riferimento a file (`fileId` + `versionId` + `branchId`) viene risolto come file sorgente interno. Un'etichetta esistente con lo stesso `tagId` viene sovrascritto.
* Se nessuno dei riferimenti viene risolto come file sorgente, la richiesta restituisce `400`. Se alcuni riferimenti vengono risolti e altri no, la richiesta restituisce `400` ed elenca gli ID dei file non risolti.
* La risposta restituisce l'etichetta memorizzato, inclusi i relativi timestamp.

## Richiesta [#request]

### Header

| Header            | Descrizione                                                                      | Obbligatorio |
| ----------------- | -------------------------------------------------------------------------------- | ------------ |
| `x-gt-api-key`    | Chiave API del progetto o dell'organizzazione.                               | Sì           |
| `x-gt-project-id` | ID progetto. Obbligatorio quando si utilizza una chiave dell'organizzazione. | No           |

### Body

**Tipo di contenuto** `application/json`

| Campo             | Descrizione                                                  | Tipo       | Facoltativo | Predefinito |
| ----------------- | ------------------------------------------------------------ | ---------- | ----------- | ----------- |
| `tagId`           | Identificatore dell'etichetta (1–255 caratteri).                    | `string`   | No          | —           |
| [`files`](#files) | Versioni dei file da etichettare; almeno una è obbligatoria. | `object[]` | No          | —           |
| `message`         | Messaggio facoltativo per l'etichetta (massimo 255 caratteri).    | `string`   | Sì          | —           |

#### `files` [#files]

**Tipo** `object[]` · **Obbligatorio**

Ogni elemento fa riferimento a una versione di un file. Tutti i valori devono essere non vuoti:

| Campo       | Descrizione                       | Tipo     | Facoltativo | Predefinito |
| ----------- | --------------------------------- | -------- | ----------- | ----------- |
| `fileId`    | Identificatore stabile del file.  | `string` | No          | —           |
| `versionId` | Identificatore della versione.    | `string` | No          | —           |
| `branchId`  | Branch a cui è associato il file. | `string` | No          | —           |

## Risposta [#response]

**Stato** `200 OK`

```json title="Response"
{
  "tag": {
    "id": "tag_...",
    "tagId": "v1.2.0",
    "message": "Release 1.2.0",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}
```

## Errori [#errors]

| Stato | Causa                                                                                                                          |
| ----- | ------------------------------------------------------------------------------------------------------------------------------ |
| `400` | Corpo della richiesta non valido, nessun file sorgente corrispondente oppure impossibile risolvere alcuni riferimenti ai file. |
| `401` | Chiave API mancante o non valida.                                                                                              |
| `403` | La chiave API non dispone di `project:files:write`.                                                                            |
| `429` | Limite di richieste superato.                                                                                                  |

## Esempio [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/tags/create \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "tagId": "v1.2.0",
    "message": "Release 1.2.0",
    "files": [
      {
        "fileId": "file_...",
        "versionId": "ver_...",
        "branchId": "br_..."
      }
    ]
  }'
```