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

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 Update version metadata, 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
Parameterid (path) TypeUUID Requiredyes DescriptionApplication identifier. Get it via GET /v1/apps.
ParameterversionId (path) Typestring Requiredyes DescriptionVersion identifier of the form v<N>. Get it via List versions.

Request fields (body)

Field Type Required Description
Fieldtag Typestring Requiredyes Descriptionmanual or published.
Fieldaction Typestring Requiredyes Descriptionadd — 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
Fieldsuccess Typeboolean DescriptionAlways true on success.
Fielddata.versionId Typestring DescriptionVersion identifier.
Fielddata.tags Typestring[] DescriptionVersion 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
HTTP400 CodeINVALID_TAG DescriptionThe tag is not one of manual, published.
HTTP400 CodeINVALID_ACTION DescriptionThe action is neither add nor remove.
HTTP400 CodeINVALID_VERSION_ID DescriptionThe versionId format does not match v<non-negative integer>.
HTTP403 CodeSOURCE_APP_ID_MISMATCH DescriptionThe 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.
HTTP403 CodeNOT_AUTHORIZED DescriptionOnly the application author, the application OAuth key, or a Bitrix24 account administrator can manage snapshots.
HTTP403 CodeINFRA_FORBIDDEN_FOR_COWORK_KEY DescriptionThe call was made with a Cowork key — such a key works with data only and cannot perform write operations. To issue a key that can, see Project key for deploy.
HTTP404 CodeAPP_NOT_FOUND DescriptionThe application does not exist, was deleted, or belongs to another portal.
HTTP404 CodeVERSION_NOT_FOUND DescriptionA version with this versionId does not exist or was deleted.

Full list of common API errors — Errors.

See also