Save a snapshot

POST /v1/apps/:id/sources

Saving a source archive explicitly: when you need to tag a version, record an intermediate result without deploying, or prepare a rollback.

The request body is the raw archive bytes, and the format is declared by the Content-Type header. Tags, the note, and the filename are passed via additional headers. When you deploy, a snapshot is created automatically.

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.

Parameters

Request fields (body)

The body is 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.

Examples

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: Added OAuth flow" \
  -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: Added OAuth flow" \
  -H "X-Tags: manual" \
  --data-binary @app-sources.tar.gz

JavaScript — personal key

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': 'YOUR_API_KEY',
      'Content-Type': 'application/gzip',
      'X-Note': 'Added OAuth flow',
      'X-Tags': 'manual',
    },
    body: archive,
  },
)
const json = await res.json()
console.log(json.data.versionId, 'deduplicated:', json.data.deduplicated)

JavaScript — OAuth application

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': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/gzip',
      'X-Note': 'Added OAuth flow',
      '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:

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

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

Re-saving the same archive does not create a version. A match is determined by the sha256 of the contents. 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.

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.

A deduplicated save costs the same as the first one. 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.

A deduplicated save clears 409 SNAPSHOT_REQUIRED. The check before POST /v1/apps/:id/publish accepts it 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.

See also

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