Для AI-агентов: markdown этой страницы — /docs-content/source-storage/metadata.md индекс документации — /llms.txt

Теги и комментарии версии

Две операции над уже сохранённой версией без повторной загрузки архива: замена списка тегов и комментария целиком либо постановка и снятие одного тега.

Обновить метаданные версии

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

Обновляет теги и комментарий уже сохранённой версии без повторной загрузки архива. Применяется, когда нужно добавить тег или скорректировать комментарий задним числом.

Теги manual и published защищают версию от автоматической очистки. Тело заменяет список тегов и комментарий целиком — точечная постановка одного тега делается операцией Поставить или снять тег.

Параметры

Параметр Тип Обяз. Описание
id (path) UUID да Идентификатор приложения. Получить — GET /v1/apps.
versionId (path) string да Идентификатор версии вида v<N>. Получить — Список версий.

Поля запроса (body)

Поле Тип Обяз. Описание
tags string[] нет Новый полный список тегов. Заменяет существующие теги целиком. Если поле отсутствует — теги не изменяются.
note string | null нет Комментарий. Строка перезаписывает текущий, null очищает комментарий. Если поле отсутствует — комментарий не изменяется.

Можно передать только tags, только note или оба поля одновременно.

Примеры

curl — личный ключ

Terminal 
curl -X PATCH https://vibecode.bitrix24.tech/v1/apps/<APP_ID>/sources/v3 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["manual"], "note": "Финальная версия перед релизом" }'

curl — OAuth-приложение

Terminal 
curl -X PATCH https://vibecode.bitrix24.tech/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": "Финальная версия перед релизом" }'

JavaScript — личный ключ

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/apps/${appId}/sources/v3`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tags: ['manual'], note: 'Финальная версия перед релизом' }),
  },
)
const { data } = await res.json()
console.log('Теги версии:', data.tags)

JavaScript — OAuth-приложение

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.tech/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: 'Финальная версия перед релизом' }),
  },
)
const { data } = await res.json()
console.log('Теги версии:', data.tags)

Чтобы очистить комментарий, передайте { "note": null } — остальные поля версии при этом не меняются.

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе.
data.versionId string Идентификатор версии.
data.tags string[] Теги версии после обновления.
data.note string | null Комментарий версии после обновления.

Пример ответа

HTTP 200:

JSON 
{
  "success": true,
  "data": {
    "versionId": "v3",
    "tags": ["manual"],
    "note": "Финальная версия перед релизом"
  }
}

Пример ответа при ошибке

404 — версии с таким идентификатором нет:

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

Ошибки

HTTP Код Описание
400 INVALID_METADATA Тело не прошло проверку — некорректные теги или типы полей.
400 INVALID_VERSION_ID Формат versionId не соответствует v<целое неотрицательное число>.
403 SOURCE_APP_ID_MISMATCH Вызов сделан ключом авторизации vibe_app_…, выписанным на другое приложение. Такой ключ обращается только к снапшотам своего приложения, даже если оба приложения создал один автор.
403 NOT_AUTHORIZED Только автор приложения, OAuth-ключ приложения или администратор портала могут управлять снапшотами.
403 INFRA_FORBIDDEN_FOR_COWORK_KEY Вызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — Проектный ключ для деплоя.
404 APP_NOT_FOUND Приложение не существует, удалено или принадлежит другому порталу.
404 VERSION_NOT_FOUND Версия с таким versionId не существует или была удалена.

Полный список общих ошибок API — Ошибки.

Поставить или снять тег

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

Добавляет или снимает один тег версии, не трогая остальные. В отличие от PATCH, который заменяет список целиком, эта операция меняет ровно один элемент.

Распознаются два тега, оба защищают версию от автоматической очистки:

  • manual — версия закреплена оператором вручную.
  • published — версия зафиксирована как опубликованная. Этот тег также проставляется автоматически после POST /v1/apps/:id/publish.

Параметры

Параметр Тип Обяз. Описание
id (path) UUID да Идентификатор приложения. Получить — GET /v1/apps.
versionId (path) string да Идентификатор версии вида v<N>. Получить — Список версий.

Поля запроса (body)

Поле Тип Обяз. Описание
tag string да manual или published.
action string да add — добавить тег, remove — снять.

Примеры

curl — личный ключ

Terminal 
curl -X POST https://vibecode.bitrix24.tech/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-приложение

Terminal 
curl -X POST https://vibecode.bitrix24.tech/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 — личный ключ

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.tech/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('Теги версии:', data.tags)

JavaScript — OAuth-приложение

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.tech/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('Теги версии:', data.tags)

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе.
data.versionId string Идентификатор версии.
data.tags string[] Теги версии после операции.

Пример ответа

HTTP 200:

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

Пример ответа при ошибке

404 — версии с таким идентификатором нет:

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

Ошибки

HTTP Код Описание
400 INVALID_TAG Тег не входит в набор manual, published.
400 INVALID_ACTION Действие не равно add или remove.
400 INVALID_VERSION_ID Формат versionId не соответствует v<целое неотрицательное число>.
403 SOURCE_APP_ID_MISMATCH Вызов сделан ключом авторизации vibe_app_…, выписанным на другое приложение. Такой ключ обращается только к снапшотам своего приложения, даже если оба приложения создал один автор.
403 NOT_AUTHORIZED Только автор приложения, OAuth-ключ приложения или администратор портала могут управлять снапшотами.
403 INFRA_FORBIDDEN_FOR_COWORK_KEY Вызов сделан ключом Cowork/Code — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — Проектный ключ для деплоя.
404 APP_NOT_FOUND Приложение не существует, удалено или принадлежит другому порталу.
404 VERSION_NOT_FOUND Версия с таким versionId не существует или была удалена.

Полный список общих ошибок API — Ошибки.

Смотрите также