For AI agents: markdown of this page — /docs-content-en/keys-auth/guide.md documentation index — /llms.txt

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 appears — for example, when an application needs to find out field types and constraints before user authorization.

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

javascript 
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

javascript 
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.importantNotes and data.knownIssues — nuances and constraints, plus pointers to documentation sections. Below — the response envelope, the structure of a data.entities[] element and the nested contract of the fieldsDetailed field.

Field Type Description
success boolean Always true on success
data object Reference: overview, entity contracts, API usage rules
data.overview string Overview description of the available API surface
data.entities array Contracts of entities available to the key
data.entities[].name string Entity identifier for /v1/<name> paths
data.entities[].basePath string Entity base path. For dynamic entities contains the parameter segment, for example /v1/items/:entityTypeId
data.entities[].scope string Scope required to access the entity
data.entities[].bitrixEntity string Entity name on the Bitrix24 side
data.entities[].operations object Available operations. Keys — list, getById, create, update, delete, search, aggregate, batch. Only supported operations are present
data.entities[].operations.<op>.method string HTTP method of the operation
data.entities[].operations.<op>.path string Operation path. Some operations additionally carry params, example, note, requiredParams
data.entities[].fields object Compact field map: the field name maps to a type or type, readonly string
data.entities[].fieldsDetailed object Detailed field contract: the field name maps to an object with type and constraints
data.entities[].fieldsDetailed.<field>.type string Field type
data.entities[].fieldsDetailed.<field>.readonly boolean Read-only field. Present when true
data.entities[].fieldsDetailed.<field>.required boolean Field is required on creation. Present when true
data.entities[].fieldsDetailed.<field>.createOnly boolean Field is set only on creation and not accepted on update. Present when true
data.entities[].fieldsDetailed.<field>.nullable boolean The field can come back as null. Present when true
data.entities[].fieldsDetailed.<field>.enum array Allowed values of an enumeration field
data.entities[].fieldsDetailed.<field>.enum[].value number or string Value the field accepts
data.entities[].fieldsDetailed.<field>.enum[].label string English name of the value
data.entities[].fieldsDetailed.<field>.enum[].labelRu string Russian name of the value
data.entities[].fieldsDetailed.<field>.enum[].description string Explanation of the value. Not present for all values
data.entities[].responseFormats object Response shape examples for list, get, create operations
data.entities[].docs string Link to the entity documentation page. Present if the page exists
data.entities[].requiredListParams array Required query parameters of the list operation. Present for entities that require them
data.entities[].requiredFilterFields array Required filter fields. Present for entities that require them
data.importantNotes object Nuances of working with fields common to several entities — the stageId format, deal money fields and others
data.knownIssues array Known method constraints, filtered by the key's scopes
data.knownIssues[].method string Bitrix24 method the constraint applies to
data.knownIssues[].scope string Method scope
data.knownIssues[].issue string Constraint description
data.knownIssues[].workaround string Workaround
data.accessModeNote string A reminder about read-only mode and the WRITE_BLOCKED_READONLY_KEY code
data.changelog, data.errors, data.feedback, data.entityApi, data.entitiesIndex string Pointers to documentation sections — URL and a short section description
data.workflows, data.notifications, data.calls, data.keysAuth and other sections object Sections beyond the entity API. Each contains description, an endpoints array with methods and paths, and docs with links to documentation

Response example

Shown is one data.entities element and part of the structural blocks. The full response contains contracts of all entities available to the key.

JSON 
{
  "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 — key not passed:

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

Errors

HTTP Code Description
401 MISSING_API_KEY The X-Api-Key header is missing
401 INVALID_API_KEY The key is not found
401 KEY_INACTIVE The key is revoked
401 KEY_EXPIRED The key's expiration has passed
403 IP_NOT_ALLOWED Request from an address outside the allowed IP list

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.

The composition of data.entities depends on the key. A key sees only the entities of 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 guide, 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