لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/source-storage/versions.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

List versions

GET /v1/apps/:id/sources

Returns the history of saved source-code versions of the application and its linked server versions.

The operation stays available even when source saving is disabled: the previously saved history remains readable.

Parameters

Parameter Type Required Description
Parameterid (path) TypeUUID Requiredyes DescriptionApplication identifier. Get it via GET /v1/apps.
Parametersha256 (query) Typestring Requiredno DescriptionA probe for whether an archive with the given contents already exists: exactly 64 hexadecimal characters, case-insensitive, otherwise 400 INVALID_SHA256. The response has the same shape as without the parameter but contains only versions with this hash: if the archive is found, versions holds one or more entries (the same contents may have been saved both to the application and to its server), and currentVersionId, totalVersions, and totalSizeBytes are computed over them only. If not, versions is an empty array and totalVersions is 0. The linkedServerSources section is not computed in this case, so the probe stays lightweight: the array is empty, linkedServerSourcesTruncated is false, and there is no linkedServerHint field.

Examples

curl — personal key

Terminal 
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/apps/<APP_ID>/sources

curl — OAuth application

Terminal 
curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.com/v1/apps/<APP_ID>/sources

JavaScript — personal key

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/apps/${appId}/sources`,
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } },
)
const { data } = await res.json()
console.log(`Versions: ${data.totalVersions}, latest: ${data.currentVersionId}`)

JavaScript — OAuth application

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/apps/${appId}/sources`,
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  },
)
const { data } = await res.json()
console.log(`Versions: ${data.totalVersions}, latest: ${data.currentVersionId}`)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success.
Fielddata.totalVersions Typenumber DescriptionTotal number of non-deleted versions. Counted without a cap, so with a long history it exceeds the length of the versions array.
Fielddata.currentVersionId Typestring | null DescriptionIdentifier of the most recent version (v<N>). null if there are no versions.
Fielddata.totalSizeBytes Typenumber DescriptionTotal size of all archives in bytes.
Fielddata.versions Typearray DescriptionThe list of versions, newest first. Deleted versions are not included. At most 500 entries are returned — with a longer history the array is truncated.
Fielddata.versions[].versionId Typestring DescriptionVersion identifier of the form v<N>.
Fielddata.versions[].filename Typestring DescriptionFilename in storage. Contains a -published or -manual suffix based on the version's current tags; with both tags, -published.
Fielddata.versions[].contentType Typestring | null DescriptionThe type the archive was saved with: application/gzip, application/x-tar, application/zip, or application/octet-stream. null for early versions whose type was not recorded.
Fielddata.versions[].timestamp Typestring DescriptionSave time (ISO 8601, UTC).
Fielddata.versions[].size Typenumber DescriptionArchive size in bytes.
Fielddata.versions[].sha256 Typestring DescriptionSHA-256 of the archive contents. Used for deduplication within one owner.
Fielddata.versions[].tags Typestring[] DescriptionVersion tags. manual and published protect the version from automatic cleanup; any other tags are free-form labels from the X-Tags header at save time or from PATCH.
Fielddata.versions[].savedBy.userId Typestring | null DescriptionVibecode user identifier.
Fielddata.versions[].savedBy.session Typestring | null DescriptionAI session identifier from the X-AI-Session-Id header.
Fielddata.versions[].linkedDeployId Typestring | null DescriptionMarker of the latest event involving the version. deploy:… — the version was saved or confirmed by a deploy. publish:<time> — the version was published via POST /v1/apps/:id/publish. Publishing overwrites the deploy marker. null — the version has had neither a deploy nor a publication.
Fielddata.versions[].deployStatus Typestring | null DescriptionHow the latest deploy of this version ended: success or failed. null if the version has never been deployed — for example, if it was saved manually and never passed to a deploy as source.versionId. Publishing does not change this field, but on some older published versions success was set by the publication, not by a deploy.
Fielddata.versions[].note Typestring | null DescriptionNote from the X-Note header at save time or from PATCH. For a version saved by a deploy, it holds the deploy's changelog field or, without one, the service string Auto-saved on deploy … with the same deploy marker as in linkedDeployId.
Fielddata.versions[].serverContext Typeobject | null DescriptionThe server managed by this application's key (vibe_app_*), if the version is linked to one. Server data is current as of the request. null if the version is not linked to a server.
Fielddata.versions[].serverContext.serverId Typestring DescriptionServer identifier. Get it via GET /v1/infra/servers.
Fielddata.versions[].serverContext.serverName Typestring DescriptionSystem name of the server.
Fielddata.versions[].serverContext.serverDisplayName Typestring DescriptionDisplay name of the server. An empty string if the server has none.
Fielddata.versions[].serverContext.linkedApp Typeobject | null DescriptionThe application the server's managing key is issued for. null if the server is managed by a personal key.
Fielddata.versions[].serverContext.linkedApp.appId Typestring DescriptionApplication identifier. Get it via GET /v1/apps.
Fielddata.versions[].serverContext.linkedApp.title Typestring DescriptionApplication title.

Linked server versions

The versions array lists app-scoped versions. These include versions of a server managed by this application's key (vibe_app_*): their serverContext is filled in. Versions of servers on a personal key (stored via POST /v1/infra/servers/:id/sources or by auto-save on deploy) are not included in versions — they are returned in a separate field data.linkedServerSources, grouped by server. The Response example below shows a populated section.

Field Type Description
Fielddata.linkedServerSources[] Typearray DescriptionGroups of server versions, one per server. Always present. Empty if there are no linked server versions or the section was not computed; the cases are listed below the table.
Fielddata.linkedServerSources[].serverContext Typeobject DescriptionThe group's server. Same fields as data.versions[].serverContext.
Fielddata.linkedServerSources[].totalVersions Typenumber DescriptionExact number of versions on the server, not limited by the list size below.
Fielddata.linkedServerSources[].totalSizeBytes Typenumber DescriptionTotal size of that server's versions.
Fielddata.linkedServerSources[].versions[] Typearray DescriptionServer versions in the same shape as versions[], but without the serverContext field: it sits on the group. The version number here comes from the server's history: it may match the number of a different version in versions, and the server's sequence might not start at v1 and may contain gaps.
Fielddata.linkedServerSourcesTruncated Typeboolean DescriptionAlways present. true means the section is incomplete: there are more than 50 servers with versions or more than 200 of their versions in total. true also comes back when the section could not be built, in which case the array is empty. The full list is available per server via GET /v1/infra/servers/:serverId/sources.
Fielddata.linkedServerHint Typeobject DescriptionPresent only when linkedServerSources is non-empty; otherwise, the field is absent from the response. Points to the authoritative list and download endpoints for server versions.
Fielddata.linkedServerHint.message Typestring DescriptionExplains where the server versions are stored and where to get them. The text is in English.
Fielddata.linkedServerHint.listEndpoint Typestring DescriptionEndpoint template for listing a server's versions.
Fielddata.linkedServerHint.downloadEndpoint Typestring DescriptionEndpoint template for downloading a server version.
Fielddata.linkedServerHint.docs Typestring DescriptionLink to the markdown page of the Source code storage section.

linkedServerSources is populated on a request without ?sha256= when the caller is the app author (personal vibe_api_* key) or a Bitrix24 account administrator. In this section, the author sees only the servers of the requesting key and the server bound to that key's application. Servers created with the author's other personal keys do not appear in the section, even when the author is a Bitrix24 account administrator: a request for their sources with this key gets 404 SERVER_NOT_FOUND. When the call uses an OAuth application key, the section is empty: a machine key does not enumerate the author's personal servers. Downloads and the full per-server list are available via GET /v1/infra/servers/:serverId/sources, using the identifier from serverContext.serverId.

Response example

HTTP 200:

JSON 
{
  "success": true,
  "data": {
    "totalVersions": 2,
    "currentVersionId": "v2",
    "totalSizeBytes": 49678,
    "versions": [
      {
        "versionId": "v2",
        "filename": "2026-08-04T10-36-36-711Z-v2.tar.gz",
        "contentType": "application/gzip",
        "timestamp": "2026-08-04T10:36:36.711Z",
        "size": 174,
        "sha256": "1b8d9dcdb0960d4cea381ae1f80bfaab4af3a27ec9645136242575ac35f9da3b",
        "tags": [],
        "savedBy": {
          "userId": "48bdfd33-5fbe-4ad1-a02c-9b5c7ae65f77",
          "session": null
        },
        "linkedDeployId": null,
        "deployStatus": null,
        "note": "Fixed the sign-in form",
        "serverContext": null
      },
      {
        "versionId": "v1",
        "filename": "2026-08-04T10-01-25-947Z-v1.tar.gz",
        "contentType": "application/gzip",
        "timestamp": "2026-08-04T10:01:25.947Z",
        "size": 49504,
        "sha256": "e28aaf8af203804c934e6881c94472a420174f58c9442ecef82dba44c6cf989b",
        "tags": [],
        "savedBy": {
          "userId": "48bdfd33-5fbe-4ad1-a02c-9b5c7ae65f77",
          "session": null
        },
        "linkedDeployId": null,
        "deployStatus": null,
        "note": "First version",
        "serverContext": null
      }
    ],
    "linkedServerSources": [
      {
        "serverContext": {
          "serverId": "86dba796-5b36-49ef-a12e-55f1fc2229dd",
          "serverName": "shop-api",
          "serverDisplayName": "Shop: API",
          "linkedApp": null
        },
        "totalVersions": 1,
        "totalSizeBytes": 1430,
        "versions": [
          {
            "versionId": "v1",
            "filename": "2026-09-03T07-30-46-098Z-v1.tar.gz",
            "contentType": "application/gzip",
            "timestamp": "2026-09-03T07:30:46.098Z",
            "size": 1430,
            "sha256": "3ac41f26c943713b4ed4b85a8ec20a7b7d1dbdfeeee0634712251419a15a328b",
            "tags": [],
            "savedBy": {
              "userId": "48bdfd33-5fbe-4ad1-a02c-9b5c7ae65f77",
              "session": null
            },
            "linkedDeployId": "deploy:2026-09-03T07:30:44.843Z",
            "deployStatus": "success",
            "note": "Auto-saved on deploy 2026-09-03T07:30:44.843Z"
          }
        ]
      },
      {
        "serverContext": {
          "serverId": "07312566-9915-4338-bf3f-997318013237",
          "serverName": "landing",
          "serverDisplayName": "Landing",
          "linkedApp": null
        },
        "totalVersions": 1,
        "totalSizeBytes": 374,
        "versions": [
          {
            "versionId": "v1",
            "filename": "2026-08-07T11-53-13-340Z-v1.tar.gz",
            "contentType": "application/gzip",
            "timestamp": "2026-08-07T11:53:13.340Z",
            "size": 374,
            "sha256": "98021c03c7ccd84493d872e1dfcbb083686368b6df8e2b53b64a1ce8bfd72e20",
            "tags": [],
            "savedBy": {
              "userId": null,
              "session": null
            },
            "linkedDeployId": "deploy:2026-08-07T11:53:13.038Z",
            "deployStatus": "success",
            "note": "Auto-saved on deploy 2026-08-07T11:53:13.038Z"
          }
        ]
      }
    ],
    "linkedServerSourcesTruncated": false,
    "linkedServerHint": {
      "message": "This app has source versions stored under a server (server-keyed storage). List and download them via the server endpoint.",
      "listEndpoint": "GET /v1/infra/servers/:serverId/sources",
      "downloadEndpoint": "GET /v1/infra/servers/:serverId/sources/:versionId/download",
      "docs": "https://vibecode.bitrix24.com/docs-content-en/source-storage.md"
    }
  }
}

Error response example

404 — there is no application with that identifier:

JSON 
{
  "success": false,
  "error": {
    "code": "APP_NOT_FOUND",
    "message": "Application not found"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_SHA256 DescriptionThe sha256 parameter is not exactly 64 hexadecimal characters.
HTTP403 CodeSOURCE_APP_ID_MISMATCH DescriptionThe call was made with an authorization key vibe_app_… issued for a different application. Such a key can access only its own application's snapshots, even when both applications were created by the same author.
HTTP403 CodeNOT_AUTHORIZED DescriptionThe personal key belongs neither to the application author nor to a Bitrix24 account administrator and was not issued for this application.
HTTP404 CodeAPP_NOT_FOUND DescriptionThe application does not exist, was deleted, or belongs to another portal.

Full list of common API errors — Errors.

See also