#API overview

Vibecode provides a single REST interface for working with Bitrix24 entities: CRM, tasks, users, calendar, drive, catalog, workflows, and others. All entities share the same set of operations.

Base URL: https://vibecode.bitrix24.com Authorization: X-Api-Key: your_key header vibe_app_… keys additionally require an Authorization: Bearer header with a session token on every entity request. For unattended jobs (cron, a scheduler) with no user at the screen, use a vibe_api_… key. More details — Creating and using a key.

#Available operations

Every entity supports the standard set of operations. The path follows the /v1/{entity} template.

#List — `GET /v1/{entity}`

Fetch records with pagination, sorting, and field selection.

curl -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.com/v1/deals?limit=100&offset=0"

Parameters:

Auto-pagination: when limit > 50, Vibecode automatically requests several pages from Bitrix24 and returns all records in a single response.

#Get by ID — `GET /v1/{entity}/{id}`

curl -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.com/v1/deals/123"

Response: { success: true, data: { id: 123, title: "...", ... } }

The select parameter also works when fetching a record by id — the response contains only the listed fields. Three forms are supported: a comma-separated list ?select=id,title,stageId, a repeated key ?select[]=id&select[]=title, and an indexed form ?select[0]=id&select[1]=title. The id field is always returned; unknown fields are skipped. The parameter is compatible with include — related data is resolved before the fields are selected.

#Create — `POST /v1/{entity}`

curl -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  "https://vibecode.bitrix24.com/v1/deals" \
  -d '{"title": "New deal", "stageId": "NEW", "amount": 150000}'

Response: { success: true, data: { id: 456, ... } } (HTTP 201)

A body with no field returns 400 EMPTY_CREATE_BODY — Error codes.

#Update — `PATCH /v1/{entity}/{id}`

curl -X PATCH -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  "https://vibecode.bitrix24.com/v1/deals/123" \
  -d '{"stageId": "WON", "amount": 200000}'

A body with no field returns 400 EMPTY_UPDATE_BODY — Error codes.

#Delete — `DELETE /v1/{entity}/{id}`

curl -X DELETE -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.com/v1/deals/123"

#Search — `POST /v1/{entity}/search`

Search with filtering. More on filter syntax: Filtering

curl -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  "https://vibecode.bitrix24.com/v1/deals/search" \
  -d '{"filter": {"stageId": "NEW", "amount": {"$gte": 100000}}, "sort": {"createdAt": "desc"}, "limit": 200}'

Parameters:

Windowed search: for large datasets, search automatically splits the request into time windows. If this causes timeouts — disable it via autoWindow: false.

#Aggregation — `POST /v1/{entity}/aggregate`

Counts and numeric aggregations (sum, avg, min, max) with filtering.

curl -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "amount", "function": "sum" },
      { "field": "amount", "function": "avg" }
    ],
    "filter": { "stageId": "WON" }
  }' \
  "https://vibecode.bitrix24.com/v1/deals/aggregate"

Parameters (body):

How it works: count is computed with a single fast call to Bitrix24. For sum/avg/min/max the platform loads the records matching the filter (up to 5000 — beyond that it is flagged meta.truncated: true) and computes on the Vibecode side. For an invalid field the response includes the list of available ones.

User fields (UF) are supported in sum/avg/min/max for the UF types integer, double, money. groupBy accepts UF fields of any type. Details — in the Aggregation POST — UF fields section below.

Smart processes (items) use a path parameter: POST /v1/items/:entityTypeId/aggregate. Reserved entityTypeId values (1, 2, 3, 4, 7, 31) are served by the dedicated APIs for deals, leads, contacts, companies, quotes, and invoices.

#Aggregation POST — UF fields

The canonical POST variant of aggregation accepts an array of expressions and supports user fields (UF_CRM_*, ufCrm_*).

curl -X POST https://vibecode.bitrix24.com/v1/deals/aggregate \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "function": "sum", "field": "amount" },
      { "function": "sum", "field": "UF_CRM_BUDGET" },
      { "function": "avg", "field": "UF_CRM_SCORE" }
    ],
    "groupBy": "UF_CRM_PRIORITY"
  }'

UF support rules:

Money fields are stored in Bitrix24 as the string "amount|currency" (for example "1500.50|USD"). The aggregate extracts the numeric part before | — all arithmetic operations are correct.

Errors:

UF field cache: one call to crm.{entity}.fields per portal+entity combination (+entityTypeId for items). TTL 5 minutes — repeat aggregates within the window incur no extra requests.

#Field schema — `GET /v1/{entity}/fields`

Get the description of all entity fields with their types.

curl -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.com/v1/deals/fields"

Each field's metadata in the response carries the display name label and a purpose note description, where they are defined for the field. Field names do not need a separate reference — they arrive with the schema.

#Batch operations — `POST /v1/{entity}/batch`

Bulk create, update, or delete records of a single entity.

{ "action": "create", "items": [{ "title": "Deal 1" }, { "title": "Deal 2" }] }

To work with different entities in one request, use the Batch API.

#Response format

All endpoints return a single format:

{
  "success": true,
  "data": [ ... ],
  "meta": { "total": 150, "hasMore": true }
}

#Field transformation

Vibecode automatically transforms field names when sending a request. Always use camelCase in requests:

{ "title": "Deal", "stageId": "NEW", "assignedById": 1 }

In responses the field format depends on the Bitrix24 API of the specific entity:

Entities with a declared field schema (including tasks) return the documented fields in camelCase (id/title/status/responsibleId/…). tasks was previously mislisted in the UPPER_CASE row — its list/get responses are fully camelCase. The UPPER_CASE form may persist only for raw/undeclared fields of the entities in the second row.

It's not just the case that differs — for some fields the name itself differs. For example, the deal amount is called amount in Vibecode, while the source name of this field in Bitrix24 is opportunity. The Vibecode name is shown in the Field column of the GET /v1/{entity}/fields schema, and the source Bitrix24 name is in the Bitrix24 column. In requests and when reading the response, use the name from the Field column — the field is returned under it, and the source Bitrix24 name is not returned. The mapping for each entity is on its fields page, for example Deal fields.

#Multi-value fields (email, phone, web)

The contact fields email, phone, and web hold several values with types. The set depends on the entity — email and phone exist on contacts, companies, and leads, web only on companies. The format differs on input and on output.

On input — an array of objects [{ "value": "contact@example.com", "typeId": "WORK" }]. A single string "contact@example.com" and an array of strings are also accepted. The typeId depends on the field — WORK / HOME / MOBILE / OTHER for phone, WORK / HOME / MAILING / OTHER for email. Default WORK.

{ "email": [{ "value": "contact@example.com", "typeId": "WORK" }] }

The UPPER form with VALUE and VALUE_TYPE keys is not accepted — 400 INVALID_MULTIFIELD_SHAPE. Use camelCase value and typeId.

On output — the primary value comes as a string ("email": "contact@example.com"), and the full list of values with types is in the fm array. Per-type values are available in dedicated fields (emailWork, phoneMobile).

The exact set of typeId values and output fields for each entity is on its page, for example Contacts and Companies.

#User fields (UF)

User fields are passed and returned without name transformation. Both Bitrix24 formats are supported:

• Legacy API: UF_CRM_1234567890
• SPA API: ufCrm_1234567890

{ "UF_CRM_1234567890": "value" }

The field name in the response matches what Bitrix24 returns. To get the list of user fields, use GET /v1/userfields/:entity.

Managing user fields: Custom Fields

#Special entities

#Smart Processes (Items)

Smart processes use entityTypeId in the URL: GET /v1/items/{entityTypeId}.

# List of smart-process records with entityTypeId = 1058
curl -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.com/v1/items/1058?limit=10"

List of available smart processes: GET /v1/smart-processes.

#Calendar Events

Require mandatory parameters: type (user/group/company) and ownerId.

curl -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.com/v1/calendar-events?type=user&ownerId=1"

#Files

Require folderId. Obtain it from GET /v1/storages → the rootFolderId field.

#Rate Limit

10 requests/second — the Bitrix24 account-level limit, shared across all keys.

How to stay within the limit:

• Batch API — 50 calls per 1 limit unit
• POST /v1/{entity}/batch — up to 500 CRUD records for 10 units (not 500)
• POST /v1/{entity}/aggregate — count runs as a single fast call; sum/avg/min/max load up to 5000 records and are computed on the Vibecode side
• The select parameter — loading only the needed fields reduces the response size

More: Optimization — patterns for dashboards, bulk operations, scanning large volumes

#Writing with a read-only key

A key in read-only access mode performs reads and receives 403 WRITE_BLOCKED_READONLY_KEY on any write call — create, update, delete, or an action on an entity. The full description of the code and the details fields — Error codes. How to switch the mode and how the Bitrix24 account policy works — Access mode.

#Usage patterns

#Related sections

• Related data (include) — loading related entities in one request
• Filtering — three filter syntaxes, dates, NOT filters
• Batch API — up to 50 calls in one request
• All entities — full list of entities with links
• Optimization — rate limits, performance patterns
• Error codes — platform error reference