# General Translation Platform: Создать или обновить тег
URL: https://generaltranslation.com/ru/docs/platform/openapi/reference/project/upsert-tag.mdx
---

title: Создать или обновить тег
description: Создание или обновление тега для версий файлов в General Translation для отслеживания релизов. Справка по API для операции «Создать или обновить тег».

method: POST
---

Создаёт тег для набора версий файлов или перезаписывает существующий тег с тем же идентификатором. Используйте теги, чтобы помечать версии файлов, относящиеся к релизу.

## Обзор [#overview]

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

**Разрешение** `project:files:write` · **Лимит запросов** По умолчанию (200/мин)

Закрепите именованный тег за определёнными версиями файлов. Чтобы сначала разрешить ссылки на файлы, используйте [Получить информацию о файле](/docs/platform/openapi/reference/files/file-info).

## Как это работает [#how-it-works]

* Каждая ссылка на файл (`fileId` + `versionId` + `branchId`) сопоставляется с внутренним исходным файлом. Существующий тег с тем же `tagId` перезаписывается.
* Если ни одна из ссылок не сопоставляется с исходным файлом, запрос возвращает `400`. Если некоторые ссылки сопоставляются, а другие — нет, запрос возвращает `400` и перечисляет неразрешённые идентификаторы файлов.
* В ответе возвращается сохранённый тег, включая его временные метки.

## Запрос [#request]

### Заголовки

| Заголовок         | Описание                                                     | Обязателен |
| ----------------- | ------------------------------------------------------------ | ---------- |
| `x-gt-api-key`    | API-ключ проекта или Organization.                           | Да         |
| `x-gt-project-id` | ID проекта. Обязателен при использовании ключа Organization. | Нет        |

### Тело

**Тип содержимого** `application/json`

| Поле              | Описание                                                                | Тип        | Необязательно | По умолчанию |
| ----------------- | ----------------------------------------------------------------------- | ---------- | ------------- | ------------ |
| `tagId`           | Идентификатор тега (1–255 символов).                                    | `string`   | Нет           | —            |
| [`files`](#files) | Версии файлов, которым нужно присвоить тег; требуется как минимум одна. | `object[]` | Нет           | —            |
| `message`         | Необязательное сообщение для тега (макс. 255 символов).                 | `string`   | Да            | —            |

#### `files` [#files]

**Тип** `object[]` · **Обязательно**

Каждый элемент соответствует одной версии файла. Ни одно из значений не может быть пустым:

| Поле        | Описание                        | Тип      | Необязательное | По умолчанию |
| ----------- | ------------------------------- | -------- | -------------- | ------------ |
| `fileId`    | Постоянный идентификатор файла. | `string` | Нет            | —            |
| `versionId` | Идентификатор версии.           | `string` | Нет            | —            |
| `branchId`  | Ветка, к которой привязан файл. | `string` | Нет            | —            |

## Ответ [#response]

**Статус** `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"
  }
}
```

## Ошибки [#errors]

| Статус | Причина                                                                                                               |
| ------ | --------------------------------------------------------------------------------------------------------------------- |
| `400`  | Недопустимое тело запроса, отсутствуют совпадающие исходные файлы или не удалось разрешить некоторые ссылки на файлы. |
| `401`  | Отсутствует или недействителен API-ключ.                                                                              |
| `403`  | У API-ключа нет `project:files:write`.                                                                                |
| `429`  | Превышен лимит запросов.                                                                                              |

## Пример [#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_..."
      }
    ]
  }'
```