Сохранить снапшот

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

Обзор хранилища и справочник эндпоинтов — Хранилище исходного кода.

Сохранение снапшота

POST /v1/apps/:id/sources

Принимает сырые байты архива исходного кода в теле запроса. Формат определяется заголовком Content-Type. Метаданные (теги, комментарий, имя файла) передаются через дополнительные заголовки.

Только бинарная загрузка (контракт v2). Эндпоинт принимает сырые байты архива в теле запроса (--data-binary). multipart/form-data больше не поддерживается — такой запрос возвращает 400 INVALID_CONTENT_TYPE. Ранние версии клиентов, которые слали multipart/form-data с полями формы (-F "tag=manual"), нужно обновить: тело — это сами байты архива, а теги, комментарий и имя файла передаются заголовками X-Tags / X-Note / X-Filename (не полями формы и не query-параметрами). MCP-клиенты используют инструмент save_sources, который сам упаковывает и отправляет архив в правильном формате.

Параметры пути

Заголовки запроса

Тело запроса

Сырые байты архива, не multipart/form-data. Максимальный размер — 500 МБ.

Тело принимается потоком, поэтому длину нужно объявить заранее: запрос обязан нести Content-Length. Загрузка чанками (Transfer-Encoding: chunked, без длины) отклоняется кодом 411 MISSING_CONTENT_LENGTH — платформа не станет копить архив в памяти, чтобы измерить его за клиента. Заявленная длина сверх потолка отбивается 413 ещё до чтения тела.

В curl длина проставляется сама, если тело берётся из файла (--data-binary @app.tar.gz). Ручной поток из пайпа (... | curl --data-binary @-) длины не даёт — сохраните архив во временный файл или задайте Content-Length явно.

Ответ при успешном сохранении

HTTP 201:

{
  "success": true,
  "data": {
    "versionId": "v3",
    "id": "cmszu9y12190j4bmj3hhsno39",
    "filename": "2026-05-21T10-15-30-000Z-v3.tar.gz",
    "contentType": "application/gzip",
    "sha256": "a3f5d8b2c1e9f4...",
    "size": 184320,
    "timestamp": "2026-05-21T10:15:30.000Z",
    "tags": [],
    "note": null,
    "deduplicated": false
  }
}

Поля ответа

Идемпотентность

Повторное сохранение архива с тем же содержимым даёт тот же sha256 и не создаёт новую версию. Эндпоинт возвращает HTTP 201 с deduplicated: true и versionId уже существующей версии. Если при повторном сохранении переданы новые теги или комментарий — они добавляются к существующей версии (теги объединяются, комментарий перезаписывается).

Область действия — один владелец. Совпадение ищется среди версий того же приложения для POST /v1/apps/:id/sources и того же сервера для POST /v1/infra/servers/:id/sources. Один и тот же архив, сохранённый на двух разных серверах или под двумя приложениями, даёт две версии и два объекта в хранилище — у каждого владельца своя история версий.

Совпадение определяется по содержимому, а значит — только после того, как тело целиком принято: платформа считает sha256 на лету поверх приходящего потока. Поэтому повторное сохранение того же архива идёт столько же времени и передаёт столько же байт, сколько первое. Результат при этом прежний: новая версия не создаётся, в ответе deduplicated: true.

Дедуплицированное сохранение проверка перед POST /v1/apps/:id/publish принимает наравне с настоящим: сохранение отмечает версию как заново предъявленную, и возраст снапшота отсчитывается от этой отметки. Поле data.timestamp при этом остаётся временем создания версии — оно не сдвигается, поэтому имя файла в депо и место версии в политике хранения не меняются. Если после 409 SNAPSHOT_REQUIRED вы сохранили те же самые исходники, повторный publish пройдёт — менять байты, чтобы обновить снапшот, не нужно.

Ответ при отключённом сохранении

HTTP 200 — снапшот не создан:

{
  "success": true,
  "data": {
    "skipped": true,
    "reason": "DISABLED_GLOBALLY"
  }
}

reason — "DISABLED_GLOBALLY" (платформа не включила функцию) или "DISABLED_FOR_PORTAL" (владелец портала отключил для своего портала). При любом из вариантов POST /v1/apps/:id/publish не проверяет наличие снапшота.

Примеры

curl — tar.gz

curl -X POST https://vibecode.bitrix24.tech/v1/apps/<APP_ID>/sources \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Content-Type: application/gzip" \
  -H "X-Note: Добавил OAuth-флоу" \
  -H "X-Tags: manual" \
  --data-binary @app-sources.tar.gz

curl — zip

curl -X POST https://vibecode.bitrix24.tech/v1/apps/<APP_ID>/sources \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @app-sources.zip

JavaScript

const archive = await fs.readFile('app-sources.tar.gz')

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/apps/${appId}/sources`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.VIBE_APP_KEY,
      'Content-Type': 'application/gzip',
      'X-Note': 'Добавил OAuth-флоу',
    },
    body: archive,
  },
)
const json = await res.json()
console.log(json.data.versionId, 'deduplicated:', json.data.deduplicated)

Коды ошибок

Полный справочник кодов — Коды ошибок.

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

• Хранилище исходного кода
• Список версий и скачивание
• Теги и комментарии версии
• Автоматическое сохранение при деплое
• Срок жизни версий и очистка