Para agentes de IA: markdown desta página — /docs-content-en/source-storage.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Source code storage

Source code storage automatically saves snapshots of your application's code on every deploy. If someone else or a new AI session starts working on the application, they can download the latest version and continue from the same point — the code is not lost.

Documentation sections

Why it matters

When you are refining an application, it is important not to lose the working version of the code. Source code storage does that automatically: on every successful deploy the platform saves a snapshot of the sources. If someone else or a new AI session starts working on the application later — they download the latest version and continue from the same point, without manually passing archives around.

A snapshot belongs to the application rather than to a particular developer: the code stays with the application even when the team changes.

How it differs from Git and GitHub

This is not a version control system and not a replacement for Git. Source code storage covers a narrower need — a safety net and project handoff.

Source code storage Git / GitHub
What it stores whole archive snapshots of the code change history line by line
When it saves automatically on every deploy manually, on a developer's command
Git skills required no yes
Branches, merges, version comparison no yes

If you need team development with branches and history, use Git. If you just need to avoid losing working code and to be able to return to a previous version, storage is enough.

How it works

  1. You refine the application and start a deploy.
  2. The platform saves a source snapshot on its own — the next version: v1, v2, v3, …
  3. At any time you can list the versions and download the one you need.
  4. Before the application is published, the platform checks that a snapshot has been saved.
edit code  →  deploy  →  snapshot vN saved automatically
                                      ↓
        list versions  →  download any  →  continue work

Core concepts

  • Snapshot — an archived copy of the application's source code at the moment of saving.
  • Version vN — the sequence number of a snapshot (v1, v2, …). The newest one is considered current.
  • Tag — a manual or published label: marks a version as important so automatic cleanup does not delete it.
  • Deduplication — if the code has not changed, no new snapshot is created and the existing version is returned. Applies within a single owner — a server or an application.

Access and endpoints

Base URL: https://vibecode.bitrix24.com/v1
Authorization: the X-Api-Key header. Snapshots can be managed by the application authorization key (vibe_app_*), the application author's personal key (vibe_api_*), or a Bitrix24 account administrator.
Allowed archive formats: application/gzip, application/x-tar, application/zip, application/octet-stream.
Body limit: 500 MB per request.

Application snapshots:

Method Path Action
POST /v1/apps/:id/sources Save a snapshot
GET /v1/apps/:id/sources List versions
GET /v1/apps/:id/sources/:versionId Single-version metadata
GET /v1/apps/:id/sources/:versionId/download Signed download link
PATCH /v1/apps/:id/sources/:versionId Update tags / note
POST /v1/apps/:id/sources/:versionId/tag Add or remove a tag
DELETE /v1/apps/:id/sources/:versionId Delete a version
POST /v1/apps/:id/sources/cleanup Bulk cleanup

Server snapshots — the same family keyed by the server. The differences and the full list of paths are on the Server-keyed source endpoints page.

Aggregated registry: GET /v1/me/sources — every snapshot owner the key can reach, see Source registry.

Save contract

The body of POST …/sources is the raw archive bytes, not multipart/form-data. Metadata travels in headers, not as form fields and not as query parameters.

Header Required Description
Content-Type yes An archive format from the list above. Any other value → 400 INVALID_CONTENT_TYPE
Content-Length yes Body size in bytes. Without it (Transfer-Encoding: chunked) → 411 MISSING_CONTENT_LENGTH
X-Filename no Display filename. If it is not provided, the name is derived from Content-Type. Characters outside a-zA-Z0-9._- → 400 INVALID_FILENAME
X-Tags no Comma-separated tags. manual and published are recognized — they protect the version from automatic cleanup
X-Note no A note stored with the version record
X-AI-Session-Id no AI session identifier — groups snapshots in the manifest
Terminal 
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-Tags: manual" \
  -H "X-Note: Added OAuth flow" \
  --data-binary @app-sources.tar.gz

The code source for a deploy — the source field of POST /v1/infra/servers/:id/deploy accepts three mutually exclusive forms:

Form What it is
source.content An inline base64 archive — always works, including on a Galaxy app
source.url A signed link from Vibecode storage. On a Galaxy app this must be enabled for you separately
source.versionId An already saved version of the form vN. On a Galaxy app this must be enabled for you separately

The full walkthrough of saving — Save a snapshot. Auto-save and deploying from a version — Automatic save on deploy.

Quick start

To hand the project over to another developer or a new AI session — three calls:

Terminal 
# 1. What is already saved for this application
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/apps/<APP_ID>/sources

# 2. A link to the archive of the version you need (valid for 30 minutes)
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/apps/<APP_ID>/sources/v1/download

# 3. Download the archive using that link — no additional headers
curl -o source-v1.tar.gz "<url from the response above>"

Error codes

Refusals specific to source storage:

HTTP Code When returned
400 INVALID_CONTENT_TYPE Content-Type is not in the list of allowed archive formats
400 INVALID_SHA256 The sha256 parameter is not exactly 64 hexadecimal characters
400 INVALID_VERSION_ID The versionId format does not match v<non-negative integer>
400 INVALID_KEEP_LATEST The keepLatest value is not a non-negative integer
400 SOURCE_VERSION_REQUIRES_APP Deploy by versionId onto a server owned by another key, and the server's owner is not bound to an application
403 NOT_AUTHORIZED The key is neither an application key, the author's personal key, nor a Bitrix24 account administrator key
403 PORTAL_KEY_REQUIRED The key is not bound to a portal — the aggregated registry is unavailable to such a key
403 SOURCE_APP_ID_MISMATCH An authorization key vibe_app_… targets snapshots of a different application
403 INFRA_FORBIDDEN_FOR_COWORK_KEY A save, a metadata edit, or a delete was made with a Cowork/Code key — Project key for deploy
404 APP_NOT_FOUND The application does not exist, was deleted, or belongs to another portal
404 VERSION_NOT_FOUND No version with that versionId exists, or it was deleted
404 SOURCE_VERSION_NOT_FOUND The version was not found in either the server's context or the application's
409 SNAPSHOT_REQUIRED Publishing without a saved snapshot, or a deploy from an external URL
409 PROTECTED_BY_TAG The version is protected by the manual or published tag
410 SOURCE_VERSION_BYTES_PURGED The version record still exists, but the bytes have already been purged from storage
411 MISSING_CONTENT_LENGTH The save request arrived without Content-Length
415 UNSUPPORTED_ARCHIVE_FORMAT The first bytes of the archive contradict the declared Content-Type
502 SOURCE_DOWNLOAD_URL_FAILED Storage is temporarily unavailable — retry the request

The full reference of API error codes — Error codes.

See also