For AI agents: markdown of this page — /docs-content-en/source-storage/delete.md documentation index — /llms.txt

Documentation articles are currently available in English.

Deleting versions

Deleting a single version and clearing the history in bulk. Both operations spare versions carrying retention tags, and both are irreversible: a deleted version cannot be restored through the API.

Delete a version

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

Marks the version as deleted. The version cannot be restored via the API — save the sources again if you need them back.

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 rejection response 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.

Parameters

Parameter Type Required Description
id (path) UUID yes Application identifier. Get it via GET /v1/apps.
versionId (path) string yes Version identifier of the form v<N>. Get it via List versions.

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/apps/${appId}/sources/v3`,
  {
    method: 'DELETE',
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  },
)
const { data } = await res.json()
console.log('Deleted version:', data.versionId)

JavaScript — OAuth application

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/apps/${appId}/sources/v3`,
  {
    method: 'DELETE',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  },
)
const { data } = await res.json()
console.log('Deleted version:', data.versionId)

Response fields

Field Type Description
success boolean Always true on success.
data.versionId string Identifier of the deleted version.

Response example

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.

Errors

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

Full list of common API errors — Errors.

Clear old versions

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

Deletes old versions, keeping the keepLatest most recent ones. Versions with the manual and published tags 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.

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 and published tags.

The body can be omitted — the default value applies.

Examples

curl — personal key

Terminal 
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

Terminal 
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.
404 APP_NOT_FOUND The application does not exist, was deleted, or belongs to another portal.

Full list of common API errors — Errors.

See also