## 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

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

### curl — OAuth application

```bash
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](/docs/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](/docs/keys-auth#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

- [Creating and using a key](/docs/keys-auth)
- [Key self-description](/docs/keys-auth/me)
- [Access mode](/docs/keys-auth/access-mode)
- [CRUD endpoint reference](/docs/entity-api)
- [Errors](/docs/errors)