API reference for the model

GET /v1/guide

Returns the field contract of all Bitrix24 account entities and API usage rules in one response. The model accesses it for the static field schema before a session token exists — for example, when an application needs to find out field types and constraints before user authorization.

Examples

curl — personal key

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/guide

curl — OAuth application

curl \
  -H "X-Api-Key: YOUR_APP_KEY" \
  https://vibecode.bitrix24.com/v1/guide

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/guide', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
data.entities.forEach((e) => {
  console.log(`${e.name} (${e.scope}) — ${Object.keys(e.operations).join(', ')}`)
})

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/guide', {
  headers: { 'X-Api-Key': 'YOUR_APP_KEY' },
})

const { data } = await res.json()

Response fields

The response is split into structural blocks: data.overview — an overview, data.entities — entity contracts, data.paginationCanon — the paging and counting rules shared by every entity, data.importantNotes and data.knownIssues — nuances and constraints, plus pointers to documentation sections. Below are the response envelope, the structure of a data.entities[] element and the nested contract of the fieldsDetailed field.

itemSchema has the same shape in fieldsDetailed and in GET /v1/<entity>/fields responses. The separate items key in a /fields response continues to contain the raw Bitrix24 value directory for enumeration fields and never contains an array element schema.

Response example

The example shows one data.entities element and some of the structural blocks. The full response contains contracts of all entities available to the key.

{
  "success": true,
  "data": {
    "overview": "VibeCode API proxies Bitrix24 REST API. 48 entities across CRM, tasks, users, calendar, disk, chat, and more.",
    "entities": [
      {
        "name": "deals",
        "basePath": "/v1/deals",
        "scope": "crm",
        "bitrixEntity": "deal",
        "operations": {
          "list": { "method": "GET", "path": "/v1/deals", "params": ["limit", "offset"] },
          "getById": { "method": "GET", "path": "/v1/deals/:id" },
          "create": { "method": "POST", "path": "/v1/deals" }
        },
        "fields": {
          "id": "number, readonly",
          "title": "string",
          "amount": "number",
          "currency": "string"
        },
        "fieldsDetailed": {
          "id": { "type": "number", "readonly": true },
          "title": { "type": "string" },
          "amount": { "type": "number" },
          "currency": { "type": "string" }
        },
        "responseFormats": {
          "list": "GET /v1/deals → { success: true, data: [{ id, xmlId, lastActivityTime, title, ... }], meta: { total, hasMore } }"
        },
        "docs": "https://vibecode.bitrix24.com/docs-content/entities/deals.md"
      }
    ],
    "importantNotes": {
      "stageIdFormat": {
        "description": "Deal stageId values use Bitrix24 category prefix format: C{categoryId}:{STAGE_CODE}."
      }
    },
    "knownIssues": [
      {
        "method": "crm.timeline.comment.list",
        "scope": "crm",
        "issue": "Ignores >=CREATED filter (date filtering does not work)",
        "workaround": "Fetch all comments and filter by date on client side"
      }
    ],
    "accessModeNote": "See /v1/me for current accessMode. Write methods return 403 WRITE_BLOCKED_READONLY_KEY when key is READONLY.",
    "changelog": "https://vibecode.bitrix24.com/docs-content/changelog.md — API changelog: new features (NEW), fixes (FIX), breaking changes (BC), newest first."
  }
}

Error response example

401 — no API key passed:

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

No session token needed. The vibe_app_ authorization key reads the data.entities[].fieldsDetailed contract with a single X-Api-Key header, without Authorization: Bearer. This distinguishes the endpoint from GET /v1/<entity>/fields, which needs a user context. See Passing the key.

What data.entities contains depends on the key. A key sees only the entities within its scopes. An authorization key additionally gets business process entities available to the application. A management key gets a reference across all scopes and an extra data.managementKeyNote block.

The response is returned in full. The endpoint accepts no query parameters: you cannot request a single entity or a single section of the reference, and an unknown query parameter is ignored without changing the response. To avoid reading the whole response on every run, rely on ETag and conditional requests.

Conditional requests and cache. The response carries an ETag header. A repeat request with If-None-Match and the same value returns 304 Not Modified without a body. The response is cached server-side for about 5 minutes, the response header is Cache-Control: private, max-age=300.

fieldsDetailed is a static contract. It does not contain field display names or Bitrix24 account custom fields UF_CRM_*. For display names and custom fields, use GET /v1/<entity>/fields with a user context.

See also

• Keys and authorization
• Key self-description
• Access mode
• CRUD endpoint reference
• Errors