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

POST /v1/apps/:id/sources

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

При деплое снапшот создаётся автоматически.

Параметры

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

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

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

В curl длина проставляется автоматически при --data-binary @app.tar.gz и при чтении из стандартного ввода через --data-binary @-.

Примеры

Примеры JavaScript выполняются в Node.js: сохраните код в файл с расширением .mjs. Подставьте идентификатор приложения вместо <APP_ID> и положите архив app-sources.tar.gz рядом с файлом примера.

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

curl -X POST https://vibecode.bitrix24.tech/v1/apps/<APP_ID>/sources \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/gzip" \
  -H "X-Note: OAuth sign-in" \
  -H "X-Tags: manual" \
  --data-binary @app-sources.tar.gz

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

curl -X POST https://vibecode.bitrix24.tech/v1/apps/<APP_ID>/sources \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/gzip" \
  -H "X-Note: OAuth sign-in" \
  -H "X-Tags: manual" \
  --data-binary @app-sources.tar.gz

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

import { readFile } from 'node:fs/promises'

const appId = '<APP_ID>'
const archive = await readFile(new URL('./app-sources.tar.gz', import.meta.url))

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/apps/${appId}/sources`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/gzip',
      'X-Note': 'OAuth sign-in',
      'X-Tags': 'manual',
    },
    body: archive,
  },
)
const json = await res.json()
console.log(json.data.versionId, 'deduplicated:', json.data.deduplicated)

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

import { readFile } from 'node:fs/promises'

const appId = '<APP_ID>'
const archive = await readFile(new URL('./app-sources.tar.gz', import.meta.url))

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/apps/${appId}/sources`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/gzip',
      'X-Note': 'OAuth sign-in',
      'X-Tags': 'manual',
    },
    body: archive,
  },
)
const json = await res.json()
console.log(json.data.versionId, 'deduplicated:', json.data.deduplicated)

Для zip-архива в тех же примерах меняется одно значение: Content-Type: application/zip, тело — байты zip-файла.

Поля ответа

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

HTTP 201 — снапшот сохранён. При повторной отправке того же архива статус также 201, а data.deduplicated — true:

{
  "success": true,
  "data": {
    "versionId": "v3",
    "id": "cmuye5vkc0kd74bou8q1fnreo",
    "filename": "2026-10-07T17-38-38-988Z-v3-manual.tar.gz",
    "contentType": "application/gzip",
    "sha256": "4cd663d7b491eb3dcbe46f433a3822077410873e302737ce093c84c7a915af08",
    "size": 159,
    "timestamp": "2026-10-07T17:38:38.988Z",
    "tags": ["manual"],
    "note": "OAuth sign-in",
    "deduplicated": false
  }
}

HTTP 200 — сохранение отключено, снапшот не создан:

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

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

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

400 — Content-Type не входит в список допустимых форматов архива:

{
  "success": false,
  "error": {
    "code": "INVALID_CONTENT_TYPE",
    "message": "Content-Type \"text/plain\" not allowed. Allowed: application/gzip, application/x-tar, application/zip, application/octet-stream",
    "hint": {
      "method": "binary (not multipart)",
      "acceptedContentTypes": [
        "application/gzip",
        "application/x-tar",
        "application/zip",
        "application/octet-stream"
      ],
      "mcpToolName": "save_sources",
      "docsUrl": "/docs/source-storage"
    }
  }
}

Показаны основные поля hint. Полный ответ несёт ещё explanation с разбором формата, metadataHeaders со списком заголовков метаданных и exampleCurl с готовой командой.

Ошибки

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

Известные особенности

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

При повторном сохранении архив передаётся целиком. Платформа считает sha256 по мере получения данных и определяет совпадение только после приёма всего тела запроса.

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

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

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