Save a snapshot

Saving a source archive explicitly: 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.

Storage overview and the endpoint reference — Source code storage.

Saving a snapshot

POST /v1/apps/:id/sources

Accepts the raw bytes of the source code archive in the request body. The format is determined by the Content-Type header. Metadata (tags, note, filename) is passed via additional headers.

Binary upload only (contract v2). The endpoint accepts the raw archive bytes in the request body (--data-binary). multipart/form-data is no longer supported — such a request returns 400 INVALID_CONTENT_TYPE. Early client versions that sent multipart/form-data with form fields (-F "tag=manual") must be updated: the body is the archive bytes themselves, and the tags, note, and filename are passed via the X-Tags / X-Note / X-Filename headers (not as form fields and not as query parameters). MCP clients use the save_sources tool, which packs and sends the archive in the correct format for you.

Path parameters

Request headers

Request body

Raw archive bytes, not multipart/form-data. Maximum size — 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.

In curl the length is set automatically when the body comes from a file (--data-binary @app.tar.gz). Piping the body in by hand (... | curl --data-binary @-) gives no length — save the archive to a temporary file or set Content-Length explicitly.

Response on successful save

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

Response fields

Idempotency

Re-saving an archive with the same contents yields the same sha256 and does not create a new version. The endpoint returns HTTP 201 with deduplicated: true and the versionId of the existing version. If new tags or a note are passed on a re-save, they are added to the existing version (tags are merged, the note is overwritten).

Scope — a single owner. Matching is scoped to 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.

A match is determined by contents, so it can be established only after the body has been received in full: the platform computes sha256 on the fly over the incoming stream. That is why re-saving the same archive takes as long as the first save and transfers the same number of bytes. The result is unchanged: no new version is created, and the response carries deduplicated: true.

The check before POST /v1/apps/:id/publish accepts a deduplicated save on a par with a real one: the save marks the version as presented again, and the snapshot's age is counted from that mark. 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.

Response when saving is disabled

HTTP 200 — 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.

Examples

curl — tar.gz

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

curl — zip

curl -X POST https://vibecode.bitrix24.com/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.com/v1/apps/${appId}/sources`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.VIBE_APP_KEY,
      'Content-Type': 'application/gzip',
      'X-Note': 'Added OAuth flow',
    },
    body: archive,
  },
)
const json = await res.json()
console.log(json.data.versionId, 'deduplicated:', json.data.deduplicated)

Error codes

The full code reference — Error codes.

See also

• Source code storage
• Version list and download
• Version tags and notes
• Automatic save on deploy
• Version lifetime and cleanup