# Deleting versions

Deleting a single version and clearing the history in bulk. Both operations spare versions tagged `manual` and `published`, and both are irreversible: a deleted version cannot be restored through the API.

Storage overview and the endpoint reference — [Source code storage](/docs/source-storage).

## Deleting a version

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

Marks the version as deleted. A version cannot be restored via the API. A version with the `published` or `manual` tag is protected from deletion — first remove the tag via `POST /v1/apps/:id/sources/:versionId/tag` with the body `{"tag": "manual", "action": "remove"}`. The refusal includes `hint.preservedTags` — the tag set without the retention tags, which you can pass to `PATCH` if lifting the protection in a single request is more convenient: `PATCH` replaces the tag list entirely, so an empty list also wipes your own labels.

### Path parameters

| Parameter | Type | Description |
|----------|-----|----------|
| `id` (path) | UUID | Application identifier. |
| `versionId` (path) | string | Version identifier of the form `v<N>`. |

### Response

`HTTP 200`:

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

### Error response example

`409` — the version is protected by a tag:

```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` lists the retention tags that protect the version, and `hint.preservedTags` lists the same version tags minus the retention ones: that is the list to send in `PATCH` to lift the protection without losing your own labels.

### Examples

#### curl

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

#### JavaScript

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

### Error codes

| HTTP | Code | When returned |
|------|-----|---------------------|
| 400 | `INVALID_VERSION_ID` | The `versionId` format does not match `v<non-negative integer>`. |
| 403 | `SOURCE_APP_ID_MISMATCH` | The call was made with an authorization key `vibe_app_…` issued for a different application. Such a key can access only its own application's snapshots, even when both applications were created by the same author. |
| 403 | `NOT_AUTHORIZED` | Only the application author, the application OAuth key, or a Bitrix24 account administrator can manage snapshots. |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | The call was made with a Cowork/Code key — such a key works with data only and cannot perform write operations. To issue a key that can, see [Project key for deploy](/docs/cowork/deploy-key). |
| 404 | `APP_NOT_FOUND` | The application does not exist, was deleted, or belongs to another portal. |
| 404 | `VERSION_NOT_FOUND` | A version with this `versionId` does not exist or was already deleted. |
| 409 | `PROTECTED_BY_TAG` | The version is marked with the `published` or `manual` tag. First remove the tag via `PATCH /v1/apps/:id/sources/:versionId`. |

## Bulk cleanup

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

Deletes old versions, keeping the `keepLatest` most recent ones (5 by default). Versions with the `manual` and `published` tags are excluded from cleanup regardless of `keepLatest`.

### Path parameters

| Parameter | Type | Description |
|----------|-----|----------|
| `id` (path) | UUID | Application identifier. |

### Body fields

| Field | Type | Required | Default | Description |
|------|-----|--------------|--------------|----------|
| `keepLatest` | number | no | `5` | How many of the most recent versions to keep. A non-negative integer. `0` keeps only versions with the `manual` and `published` tags. |

The body can be omitted — the default value applies.

### Response

`HTTP 200`:

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

### Examples

#### curl

```bash
curl -X POST https://vibecode.bitrix24.com/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.com/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('Deleted versions:', data.deletedVersions.length)
```

### Error codes

| HTTP | Code | When returned |
|------|-----|---------------------|
| 400 | `INVALID_KEEP_LATEST` | The `keepLatest` value is not a non-negative integer. |
| 403 | `SOURCE_APP_ID_MISMATCH` | The call was made with an authorization key `vibe_app_…` issued for a different application. Such a key can access only its own application's snapshots, even when both applications were created by the same author. |
| 403 | `NOT_AUTHORIZED` | Only the application author, the application OAuth key, or a Bitrix24 account administrator can manage snapshots. |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | The call was made with a Cowork/Code key — such a key works with data only and cannot perform write operations. To issue a key that can, see [Project key for deploy](/docs/cowork/deploy-key). |
| 404 | `APP_NOT_FOUND` | The application does not exist, was deleted, or belongs to another portal. |

The full code reference — [Error codes](/docs/errors).

## See also

- [Source code storage](/docs/source-storage)
- [Version lifetime and cleanup](/docs/source-storage/retention)
- [Version tags and notes](/docs/source-storage/metadata)
- [Version list and download](/docs/source-storage/versions)
- [Storage](/docs/storage)