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

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
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
Fieldtags Typestring[] Requiredno DescriptionThe new full list of tags. Replaces the existing tags entirely. If the field is omitted, the tags are left unchanged.
Fieldnote Typestring | null Requiredno DescriptionNote. 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
Fieldsuccess Typeboolean DescriptionAlways true on success.
Fielddata.versionId Typestring DescriptionVersion identifier.
Fielddata.tags Typestring[] DescriptionVersion tags after the update.
Fielddata.note Typestring | null DescriptionVersion 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
HTTP400 CodeINVALID_METADATA DescriptionThe body did not pass validation — invalid tags or field types.
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