Save a snapshot

POST /v1/apps/:id/sources

Explicitly saves a source archive. Use it when you need to tag a version, record an intermediate result without deploying, or prepare a rollback.

When you deploy, a snapshot is created automatically.

Parameters

Request fields (body)

The body is raw archive bytes, not multipart/form-data. The maximum size is 500 MB.

The body is accepted as a stream, so its length has to be declared up front: the request must carry Content-Length. A chunked upload (Transfer-Encoding: chunked, no length) is rejected with 411 MISSING_CONTENT_LENGTH — the platform will not buffer the archive in memory to measure it for the client. A declared length above the cap is rejected with 413 before the body is read.

curl sets the length automatically with --data-binary @app.tar.gz and when reading from standard input with --data-binary @-.

Examples

The JavaScript examples run in Node.js: save the code in an .mjs file. Replace <APP_ID> with your application ID and place app-sources.tar.gz in the same directory as the example file.

curl — personal key

curl -X POST https://vibecode.bitrix24.com/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 application

curl -X POST https://vibecode.bitrix24.com/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 — personal key

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.com/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 application

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.com/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)

For a zip archive, only one value changes in the same examples: Content-Type: application/zip, and the body is the bytes of the zip file.

Response fields

Response example

HTTP 201 — the snapshot was saved. Saving the same archive again also returns 201, with data.deduplicated set to 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 — saving is disabled, no snapshot created:

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

reason — "DISABLED_GLOBALLY" (the platform has not enabled the feature) or "DISABLED_FOR_PORTAL" (the Bitrix24 account owner disabled it for their account). In either case POST /v1/apps/:id/publish does not check for a snapshot.

Error response example

400 — Content-Type is not in the list of allowed archive formats:

{
  "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"
    }
  }
}

The main hint fields are shown. The full response also carries explanation with a breakdown of the format, metadataHeaders with the list of metadata headers, and exampleCurl with a ready-made command.

Errors

Full list of common API errors — Errors.

Known specifics

Deduplication is scoped to a single owner. Matching happens only among the versions of the same application for POST /v1/apps/:id/sources and the same server for POST /v1/infra/servers/:id/sources. The very same archive saved on two different servers or under two applications yields two versions and two objects in storage — each owner keeps its own version history.

The entire archive is sent again on a repeat save. The platform computes sha256 as it receives the data and can identify a match only after receiving the entire request body.

A deduplicated save clears 409 SNAPSHOT_REQUIRED. The check before POST /v1/apps/:id/publish treats a deduplicated save like a new save: it records when the version was submitted again and measures the snapshot's age from that time. The data.timestamp field still reports when the version was created — it does not move, so the stored file name and the version's place in the retention policy stay the same. If you re-save the very same sources after a 409 SNAPSHOT_REQUIRED, the next publish goes through — you do not have to change the bytes to refresh the snapshot.

See also

• Source code storage
• List versions
• Version tags and notes
• Automatic save on deploy
• Version lifetime and cleanup