Para agentes de IA: markdown desta página — /docs-content-en/source-storage/delete.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

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.

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

Terminal 
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.
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

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

The full code reference — Error codes.

See also