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

Documentation articles are currently available in English.

Version tags and notes

Two operations on an already saved version without re-uploading the archive: replacing the tag list and the note wholesale, or setting and removing a single tag.

Update version metadata

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

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

The manual and published tags protect a version from automatic cleanup. The body replaces the tag list and the note wholesale — to set a single tag on its own, use Set or remove a tag.

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.

Request fields (body)

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, and 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.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/apps/<APP_ID>/sources/v3 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["manual"], "note": "Final version before the release" }'

JavaScript — personal key

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/apps/${appId}/sources/v3`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tags: ['manual'], note: 'Final version before the release' }),
  },
)
const { data } = await res.json()
console.log('Version tags:', data.tags)

JavaScript — OAuth application

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/apps/${appId}/sources/v3`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tags: ['manual'], note: 'Final version before the release' }),
  },
)
const { data } = await res.json()
console.log('Version tags:', data.tags)

To clear the note, send { "note": null } — the other fields of the version stay untouched.

Response fields

Field Type Description
success boolean Always true on success.
data.versionId string Version identifier.
data.tags string[] Version tags after the update.
data.note string | null Version note after the update.

Response example

HTTP 200:

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

Error response example

404 — there is no version with that identifier:

JSON 
{
  "success": false,
  "error": {
    "code": "VERSION_NOT_FOUND",
    "message": "Version v3 not found for app <APP_ID>"
  }
}

Errors

HTTP Code Description
400 INVALID_METADATA The body did not pass 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.

Full list of common API errors — Errors.

Set or remove a tag

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

Adds or removes a single tag on a version without touching the others. Unlike PATCH, which replaces the whole list, this operation changes exactly one element.

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 marked as published. This tag is also set automatically after POST /v1/apps/:id/publish.

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.

Request fields (body)

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

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/apps/${appId}/sources/v3/tag`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tag: 'manual', action: 'add' }),
  },
)
const { data } = await res.json()
console.log('Version tags:', data.tags)

JavaScript — OAuth application

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/apps/${appId}/sources/v3/tag`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tag: 'manual', action: 'add' }),
  },
)
const { data } = await res.json()
console.log('Version tags:', data.tags)

Response fields

Field Type Description
success boolean Always true on success.
data.versionId string Version identifier.
data.tags string[] Version tags after the operation.

Response example

HTTP 200:

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

Error response example

404 — there is no version with that identifier:

JSON 
{
  "success": false,
  "error": {
    "code": "VERSION_NOT_FOUND",
    "message": "Version v3 not found"
  }
}

Errors

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

Full list of common API errors — Errors.

See also