Pour les agents IA : markdown de cette page — /docs-content-en/source-storage/servers.md index de la documentation — /llms.txt

Les articles de documentation sont actuellement disponibles en anglais.

Server-keyed source endpoints

Eight operations on a server's snapshots — the same ones an application has, but keyed by the server identifier. This page covers only the differences: the full request and response contracts live on the pages of the app-scoped family.

Storage overview and the endpoint reference — Source code storage.

Differences from the app-scoped family

This family mirrors the app-scoped one (/v1/apps/:id/sources…) in full, but it is keyed by a server identifier rather than an application one. The request and response contracts are the same as for the app-scoped operations (the same body format, the same headers, the same error codes) — only the path prefix changes.

Authorization. Access to server versions is granted to:

  • The current managing key of the server.
  • The personal key of an application bound to this server, until the server is deleted.
  • A Bitrix24 account administrator (ADMIN) — for another user's server.
  • A member of the server development team: they may list, download, save and tag versions, but not delete a version or clean up versions.
  • The Cowork/Code desktop key — read-only: the version list, metadata and the download link. The key has access while an application owned by the key owner is bound to the server and the server has not been deleted.

Other personal keys of the server owner receive 404, even when the owner is a Bitrix24 account administrator. This includes a third-party agent key on the Cowork/Code subscription: the exception applies only to the desktop key. No key with the Cowork/Code scope can change versions: saving, tagging, editing, deleting and cleanup return 403 INFRA_FORBIDDEN_FOR_COWORK_KEY. An OAuth application key is admitted only to a server it owns itself. No explicit scope is required: there is no route-level scope check.

Method Path Action
POST /v1/infra/servers/:id/sources Save a raw-bytes snapshot
GET /v1/infra/servers/:id/sources List versions (+ ?sha256= probe)
GET /v1/infra/servers/:id/sources/:versionId Single-version metadata
GET /v1/infra/servers/:id/sources/:versionId/download Signed download link
POST /v1/infra/servers/:id/sources/:versionId/tag Add or remove a tag
PATCH /v1/infra/servers/:id/sources/:versionId Update tags / note
DELETE /v1/infra/servers/:id/sources/:versionId Delete a version — soft delete
POST /v1/infra/servers/:id/sources/cleanup Bulk cleanup
  • POST …/sources — the same contract as POST /v1/apps/:id/sources: the raw archive bytes in the body, Content-Type one of application/gzip, application/x-tar, application/zip, application/octet-stream, optional X-Filename / X-Tags / X-Note / X-AI-Session-Id headers, a required Content-Length (without it — 411 MISSING_CONTENT_LENGTH), a 500 MB body cap, deduplication by sha256 within this server.
  • GET …/sources — the server's version list. The optional ?sha256=<64-hex> parameter is a lightweight probe for the existence of an archive with those contents.
  • GET …/sources/:versionId — single-version metadata (the same shape as a versions[] item).
  • GET …/sources/:versionId/download — a signed link to the archive; the requested lifetime is 30 minutes, while the actual signature expiry, returned in expiresAt, may be shorter. The response also echoes versionId (a difference from the app-scoped endpoint) — keep it and send it back as baseVersionId on the deploy that ships your changes: if a teammate has deployed in the meantime, the platform refuses the deploy instead of overwriting their code. On a server with a development team, baseVersionId is required.
  • POST …/sources/:versionId/tag — body { "tag": "manual" | "published", "action": "add" | "remove" }.
  • PATCH …/sources/:versionId — updates the tags and/or note (three-state behavior: a string overwrites, null clears, an absent field leaves it unchanged).
  • DELETE …/sources/:versionId — soft delete. A version with the manual or published tag is protected — the request returns 409 PROTECTED_BY_TAG. First remove the tag via PATCH.
  • POST …/sources/cleanup — bulk cleanup: keeps the keepLatest most recent versions plus versions with the manual / published tags.

Deleted server. Reading and cleanup stay available after DELETE /v1/infra/servers/:id: the version list, metadata, download, tag, PATCH, DELETE, and cleanup. Saving a new version with POST …/sources on a deleted server returns 404 SERVER_NOT_FOUND. After the server is deleted, the key of a bound application and the Cowork/Code desktop key lose access to its versions and receive 404. How to find such a server and remove its versions — Versions of a deleted server.

Every version in this family's responses carries a serverContext field — the server-level display context, described in the version list fields.

See also