# General Translation Platform: Crear o actualizar etiqueta
URL: https://generaltranslation.com/es/docs/platform/openapi/reference/project/upsert-tag.mdx
---

title: Crear o actualizar etiqueta
description: Crea o actualiza una etiqueta en las versiones de archivo de General Translation para el seguimiento de releases. Referencia de la API de Crear o actualizar etiqueta.

method: POST
---

Crea una etiqueta en un conjunto de versiones de archivo o sobrescribe una etiqueta existente con el mismo ID. Usa etiquetas para marcar las versiones de archivo que pertenecen a un release.

## Resumen [#overview]

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

**Permiso** `project:files:write` · **Límite de solicitudes** Predeterminado (200/min)

Asocia una etiqueta con nombre a versiones específicas de archivos. Para resolver antes las referencias de archivos, usa [Obtener información del archivo](/docs/platform/openapi/reference/files/file-info).

## Cómo funciona [#how-it-works]

* Cada referencia de archivo (`fileId` + `versionId` + `branchId`) se resuelve como un archivo de origen interno. Si ya existe una etiqueta con el mismo `tagId`, se sobrescribe.
* Si ninguna de las referencias se resuelve como un archivo de origen, la solicitud devuelve `400`. Si algunas referencias se resuelven y otras no, la solicitud devuelve `400` y enumera los ID de archivo que no se pudieron resolver.
* La respuesta devuelve la etiqueta almacenada, incluidas sus marcas de tiempo.

## Solicitud [#request]

### Cabeceras

| Cabecera          | Descripción                                                          | obligatorio |
| ----------------- | -------------------------------------------------------------------- | ----------- |
| `x-gt-api-key`    | Clave de API de Project o Organization.                              | Sí          |
| `x-gt-project-id` | ID del Project. Obligatorio cuando se usa una clave de Organization. | No          |

### Cuerpo

**Tipo de contenido** `application/json`

| Campo             | Descripción                                                             | Tipo       | Opcional | Predeterminado |
| ----------------- | ----------------------------------------------------------------------- | ---------- | -------- | -------------- |
| `tagId`           | Identificador de la etiqueta (1–255 caracteres).                        | `string`   | No       | —              |
| [`files`](#files) | Versiones de archivos que se van a etiquetar; se requiere al menos una. | `object[]` | No       | —              |
| `message`         | Mensaje opcional para la etiqueta (máx. 255 caracteres).                | `string`   | Sí       | —              |

#### `files` [#files]

**Type** `object[]` · **obligatorio**

Cada elemento hace referencia a una versión de archivo. Ningún valor puede estar vacío:

| Field       | Description                             | Type     | Optional | Default |
| ----------- | --------------------------------------- | -------- | -------- | ------- |
| `fileId`    | Identificador estable del archivo.      | `string` | No       | —       |
| `versionId` | Identificador de la versión.            | `string` | No       | —       |
| `branchId`  | Rama a la que está asociado el archivo. | `string` | No       | —       |

## Respuesta [#response]

**Estado** `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"
  }
}
```

## Errores [#errors]

| Estado | Causa                                                                                                                           |
| ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Cuerpo de la solicitud no válido, no hay archivos fuente coincidentes o no se pudieron resolver algunas referencias de archivo. |
| `401`  | Falta la clave de API o no es válida.                                                                                           |
| `403`  | La clave de API no tiene `project:files:write`.                                                                                 |
| `429`  | Se excedió el límite de tasa.                                                                                                   |

## Ejemplo [#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_..."
      }
    ]
  }'
```