## Clear old versions

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

Deletes old versions, keeping the `keepLatest` most recent ones. Versions with the `manual` or `published` tag are excluded from cleanup regardless of `keepLatest`. The operation is irreversible — deleted versions cannot be restored through the API.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|----------|
| `id` (path) | UUID | yes | Application identifier. Get it via [`GET /v1/apps`](/docs/apps/list). |

## Request fields (body)

| 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` or `published` tag. |

The body can be omitted — the default value applies.

## Examples

### curl — personal key

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

### curl — OAuth application

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

### JavaScript — personal key

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/apps/${appId}/sources/cleanup`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ keepLatest: 3 }),
  },
)
const { data } = await res.json()
console.log('Deleted versions:', data.deletedVersions.length)
```

### JavaScript — OAuth application

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/apps/${appId}/sources/cleanup`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ keepLatest: 3 }),
  },
)
const { data } = await res.json()
console.log('Deleted versions:', data.deletedVersions.length)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success. |
| `data.deletedVersions` | string[] | Identifiers of the deleted versions. An empty array means the cleanup removed no versions. |

## Response example

`HTTP 200`:

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

## Error response example

400 — `keepLatest` is not a non-negative integer:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_KEEP_LATEST",
    "message": "keepLatest must be a non-negative integer"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 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. |

Full list of common API errors — [Errors](/docs/errors).

## See also

- [Delete a version](/docs/source-storage/delete)
- [Source code storage](/docs/source-storage)
- [Version lifetime and cleanup](/docs/source-storage/retention)
- [Version tags and notes](/docs/source-storage/metadata)
- [List versions](/docs/source-storage/versions)
- [Storage](/docs/storage)