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

Version tags and notes

Two operations on an already saved version, with no re-upload of the archive: PATCH replaces the tag list and the note wholesale, while tag adds or removes a single tag. The manual and published tags protect a version from automatic cleanup.

Storage overview and the endpoint reference — Source code storage.

Updating version metadata

PATCH /v1/apps/:id/sources/:versionId

Updates the tags and/or note of an existing version without re-uploading the archive. Use it when you need to add a tag or adjust a note after the fact.

Path parameters

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

Body fields

Field Type Required Description
tags string[] no The new full list of tags. Replaces the existing tags entirely. If the field is omitted, the tags are left unchanged.
note string | null no Note. A string — overwrites the current one. null — clears the note. If the field is omitted, the note is left unchanged.

You can pass only tags, only note, or both fields at once.

Response

HTTP 200:

JSON 
{
  "success": true,
  "data": {
    "versionId": "v3",
    "tags": ["manual"],
    "note": "Final version before release"
  }
}

Examples

curl — add the `manual` tag

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/apps/<APP_ID>/sources/v3 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["manual"] }'

curl — clear the note

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/apps/<APP_ID>/sources/v3 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": null }'

JavaScript

javascript 
await fetch(
  `https://vibecode.bitrix24.com/v1/apps/${appId}/sources/v3`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': process.env.VIBE_APP_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tags: ['manual'], note: 'Final version' }),
  },
)

Error codes

HTTP Code When returned
400 INVALID_METADATA The body failed validation (invalid tags or field types).
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 deleted.

Setting and removing a tag

POST /v1/apps/:id/sources/:versionId/tag

Two tags are recognized, and both protect the version from automatic cleanup:

  • manual — the version is pinned manually by an operator.
  • published — the version is recorded as published (this tag is also set automatically after POST /v1/apps/:id/publish).

Path parameters

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

Body fields

Field Type Required Description
tag string yes manual or published.
action string yes add — add the tag, remove — remove it.

Response

HTTP 200:

JSON 
{
  "success": true,
  "data": {
    "versionId": "v3",
    "tags": ["manual"]
  }
}

Examples

curl

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/apps/<APP_ID>/sources/v3/tag \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": "manual", "action": "add" }'

JavaScript

javascript 
await fetch(
  `https://vibecode.bitrix24.com/v1/apps/${appId}/sources/v3/tag`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.VIBE_APP_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tag: 'manual', action: 'add' }),
  },
)

Error codes

HTTP Code When returned
400 INVALID_TAG The tag is not one of manual, published.
400 INVALID_ACTION The action is neither add nor remove.
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 deleted.

The full code reference — Error codes.

See also