# Теги и комментарии версии

Две операции над уже сохранённой версией без повторной загрузки архива: `PATCH` заменяет список тегов и комментарий целиком, а `tag` добавляет или снимает один тег. Теги `manual` и `published` защищают версию от автоматической очистки.

Обзор хранилища и справочник эндпоинтов — [Хранилище исходного кода](/docs/source-storage).

## Обновление метаданных версии

`PATCH /v1/apps/:id/sources/:versionId`

Обновляет теги и/или комментарий существующей версии без повторной загрузки архива. Применяется, когда нужно добавить тег или скорректировать комментарий задним числом.

### Параметры пути

| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` (path) | UUID | Идентификатор приложения. |
| `versionId` (path) | string | Идентификатор версии вида `v<N>`. |

### Поля тела

| Поле | Тип | Обязательное | Описание |
|------|-----|--------------|----------|
| `tags` | string[] | нет | Новый полный список тегов. **Заменяет** существующие теги целиком. Если поле отсутствует — теги не изменяются. |
| `note` | string \| null | нет | Комментарий. Строка — перезаписывает текущий. `null` — очищает комментарий. Если поле отсутствует — комментарий не изменяется. |

Можно передать только `tags`, только `note` или оба поля одновременно.

### Ответ

`HTTP 200`:

```json
{
  "success": true,
  "data": {
    "versionId": "v3",
    "tags": ["manual"],
    "note": "Финальная версия перед релизом"
  }
}
```

### Примеры

#### curl — добавить тег `manual`

```bash
curl -X PATCH https://vibecode.bitrix24.tech/v1/apps/<APP_ID>/sources/v3 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["manual"] }'
```

#### curl — очистить комментарий

```bash
curl -X PATCH https://vibecode.bitrix24.tech/v1/apps/<APP_ID>/sources/v3 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": null }'
```

#### JavaScript

```javascript
await fetch(
  `https://vibecode.bitrix24.tech/v1/apps/${appId}/sources/v3`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': process.env.VIBE_APP_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tags: ['manual'], note: 'Финальная версия' }),
  },
)
```

### Коды ошибок

| HTTP | Код | Когда возвращается |
|------|-----|---------------------|
| 400 | `INVALID_METADATA` | Тело не прошло валидацию (некорректные теги или типы полей). |
| 400 | `INVALID_VERSION_ID` | Формат `versionId` не соответствует `v<целое неотрицательное число>`. |
| 403 | `SOURCE_APP_ID_MISMATCH` | Вызов сделан ключом авторизации `vibe_app_…`, выписанным на другое приложение. Такой ключ обращается только к снапшотам своего приложения, даже если оба приложения создал один автор. |
| 403 | `NOT_AUTHORIZED` | Только автор приложения, OAuth-ключ приложения или администратор портала могут управлять снапшотами. |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Вызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — [Проектный ключ для деплоя](/docs/cowork/deploy-key). |
| 404 | `APP_NOT_FOUND` | Приложение не существует, удалено или принадлежит другому порталу. |
| 404 | `VERSION_NOT_FOUND` | Версия с таким `versionId` не существует или была удалена. |

## Постановка и снятие тега

`POST /v1/apps/:id/sources/:versionId/tag`

Распознаются два тега, оба защищают версию от автоматической очистки:

- `manual` — версия закреплена оператором вручную.
- `published` — версия зафиксирована как опубликованная (этот тег также проставляется автоматически после `POST /v1/apps/:id/publish`).

### Параметры пути

| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` (path) | UUID | Идентификатор приложения. |
| `versionId` (path) | string | Идентификатор версии вида `v<N>`. |

### Поля тела

| Поле | Тип | Обязательное | Описание |
|------|-----|--------------|----------|
| `tag` | string | да | `manual` или `published`. |
| `action` | string | да | `add` — добавить тег, `remove` — снять. |

### Ответ

`HTTP 200`:

```json
{
  "success": true,
  "data": {
    "versionId": "v3",
    "tags": ["manual"]
  }
}
```

### Примеры

#### curl

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/apps/<APP_ID>/sources/v3/tag \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": "manual", "action": "add" }'
```

#### JavaScript

```javascript
await fetch(
  `https://vibecode.bitrix24.tech/v1/apps/${appId}/sources/v3/tag`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.VIBE_APP_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tag: 'manual', action: 'add' }),
  },
)
```

### Коды ошибок

| HTTP | Код | Когда возвращается |
|------|-----|---------------------|
| 400 | `INVALID_TAG` | Тег не входит в набор `manual`, `published`. |
| 400 | `INVALID_ACTION` | Действие не равно `add` или `remove`. |
| 400 | `INVALID_VERSION_ID` | Формат `versionId` не соответствует `v<целое неотрицательное число>`. |
| 403 | `SOURCE_APP_ID_MISMATCH` | Вызов сделан ключом авторизации `vibe_app_…`, выписанным на другое приложение. Такой ключ обращается только к снапшотам своего приложения, даже если оба приложения создал один автор. |
| 403 | `NOT_AUTHORIZED` | Только автор приложения, OAuth-ключ приложения или администратор портала могут управлять снапшотами. |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Вызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — [Проектный ключ для деплоя](/docs/cowork/deploy-key). |
| 404 | `APP_NOT_FOUND` | Приложение не существует, удалено или принадлежит другому порталу. |
| 404 | `VERSION_NOT_FOUND` | Версия с таким `versionId` не существует или была удалена. |

Полный справочник кодов — [Коды ошибок](/docs/errors).

## Смотрите также

- [Хранилище исходного кода](/docs/source-storage)
- [Список версий и скачивание](/docs/source-storage/versions)
- [Удаление версий](/docs/source-storage/delete)
- [Срок жизни версий и очистка](/docs/source-storage/retention)
- [Сохранить снапшот](/docs/source-storage/save)