# Удаление версий

Удаление одной версии и массовая очистка истории. Обе операции щадят версии с тегами `manual` и `published`, и обе необратимы: восстановить удалённую версию через API нельзя.

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

## Удаление версии

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

Помечает версию как удалённую. Восстановить версию через API нельзя. Версия с тегом `published` или `manual` защищена от удаления — сначала снимите тег через `POST /v1/apps/:id/sources/:versionId/tag` с телом `{"tag": "manual", "action": "remove"}`. Ответ на отказ включает `hint.preservedTags` — набор тегов без защитных меток, который можно передать в `PATCH`, если снимать защиту удобнее одним запросом: `PATCH` заменяет список тегов целиком, поэтому пустой список сотрёт и ваши собственные метки.

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

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

### Ответ

`HTTP 200`:

```json
{
  "success": true,
  "data": { "versionId": "v3" }
}
```

### Пример ответа при ошибке

`409` — версия защищена тегом:

```json
{
  "success": false,
  "error": {
    "code": "PROTECTED_BY_TAG",
    "message": "Cannot delete: version is tagged manual. Drop the retention tag(s) via PATCH first.",
    "hint": {
      "tags": ["manual"],
      "preservedTags": [],
      "action": "PATCH /v1/apps/<APP_ID>/sources/v3 with body {\"tags\":[]} to drop the retention tags (preserves any other tags), then re-issue DELETE.",
      "toolName": "patch-source-metadata"
    }
  }
}
```

`hint.tags` — защитные теги, которые держат версию, `hint.preservedTags` — те же теги версии без защитных: именно этот список передают в `PATCH`, чтобы снять защиту и не потерять свои метки.

### Примеры

#### curl

```bash
curl -X DELETE https://vibecode.bitrix24.tech/v1/apps/<APP_ID>/sources/v3 \
  -H "X-Api-Key: YOUR_APP_KEY"
```

#### JavaScript

```javascript
await fetch(
  `https://vibecode.bitrix24.tech/v1/apps/${appId}/sources/v3`,
  {
    method: 'DELETE',
    headers: { 'X-Api-Key': process.env.VIBE_APP_KEY },
  },
)
```

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

| HTTP | Код | Когда возвращается |
|------|-----|---------------------|
| 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` не существует или уже удалена. |
| 409 | `PROTECTED_BY_TAG` | Версия отмечена тегом `published` или `manual`. Сначала снимите тег через `PATCH /v1/apps/:id/sources/:versionId`. |

## Массовая очистка

`POST /v1/apps/:id/sources/cleanup`

Удаляет старые версии, оставляя `keepLatest` самых свежих (по умолчанию — 5). Версии с тегами `manual` и `published` исключаются из очистки независимо от `keepLatest`.

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

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

### Поля тела

| Поле | Тип | Обязательное | По умолчанию | Описание |
|------|-----|--------------|--------------|----------|
| `keepLatest` | number | нет | `5` | Сколько последних версий оставить. Целое неотрицательное число. `0` оставит только версии с тегами `manual` и `published`. |

Тело можно опустить — применяется значение по умолчанию.

### Ответ

`HTTP 200`:

```json
{
  "success": true,
  "data": {
    "deletedVersions": ["v2", "v1"]
  }
}
```

### Примеры

#### curl

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

#### JavaScript

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/apps/${appId}/sources/cleanup`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.VIBE_APP_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ keepLatest: 3 }),
  },
)
const { data } = await res.json()
console.log('Удалено версий:', data.deletedVersions.length)
```

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

| HTTP | Код | Когда возвращается |
|------|-----|---------------------|
| 400 | `INVALID_KEEP_LATEST` | Значение `keepLatest` не является целым неотрицательным числом. |
| 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` | Приложение не существует, удалено или принадлежит другому порталу. |

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

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

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