#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.tech Authorization: X-Api-Key: your_key header

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

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

Parameters:

Parameter Type Description
limit number Number of records (default 50, maximum 5000)
offset number Skip N records
select string[] Field selection: ?select=id,title,amount
order object Sorting: ?order[createdAt]=desc

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}`

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

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

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

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

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

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

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

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

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

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

Search with filtering. More on filter syntax: Filtering

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

Parameters:

Parameter Type Description
filter object Filtering conditions (three syntaxes)
sort string | object | array Sorting. Supported: "id" / "-amount" / "id,-createdAt" (string), { id: "asc", amount: "desc" } or { id: 1, amount: -1 } (object), ["id", "-amount"] (array). Invalid type → 400 INVALID_SORT_TYPE. More on pagination — see filtering.md.
limit number Number of records (default 50, maximum 5000, auto-pagination when > 50)
offset number Skip N records
autoWindow boolean false — disable date windowing for large selections

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.

Terminal 
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.tech/v1/deals/aggregate"

Parameters (body):

Parameter Type Description
aggregate array Array of aggregations: { "field": "amount", "function": "sum" }. Functions: count, sum, avg, min, max. Without an array — only count
filter object Filtering by entity fields
groupBy string | string[] Field or array of fields to group by (maximum 5). Allowed values come from the entity's aggregatable list. For entities without aggregatable (items, requisites) the parameter is not supported

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_*).

Terminal 
curl -X POST https://vibecode.bitrix24.tech/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:

Function Accepts UF types
sum, avg, min, max only integer, double, money
groupBy any UF type (string, enumeration, date, integer, …)

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

Errors:

HTTP Code When
400 INVALID_PARAMS UF type not in the integer/double/money list for sum/avg/min/max — the actual type is given in message
400 INVALID_PARAMS Field not found in the schema or the UF cache — the available standard and UF fields are listed in message

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.

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

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

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

JSON 
{ "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:

JSON 
{
  "success": true,
  "data": [ ... ],
  "total": 150,
  "meta": { "hasMore": true }
}
Field Description
success true on successful execution
data Array of records (list/search) or an object (get/create)
total Total number of records (for list/search)
meta.hasMore Whether there are more records to load

#Field transformation

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

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

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

Response format Entities Response example
camelCase CRM (deals, contacts, companies, leads, quotes, invoices), tasks, catalog, sale, documents, bookings { "id": 1, "title": "Deal", "stageId": "NEW" }
UPPER_CASE (raw/undeclared fields only) users, departments, files, folders, calendar-events, activities, workgroups { "ID": 1, "NAME": "…" }

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.

#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
JSON 
{ "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}.

Terminal 
# List of smart-process records with entityTypeId = 1058
curl -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.tech/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.

Terminal 
curl -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.tech/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 portal-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

#Usage patterns

Task Approach
Dashboard / analytics POST /v1/{entity}/aggregate — counters and sums by filter
Bulk update POST /v1/{entity}/batch with action=update
Data from several entities POST /v1/batch — deals + tasks + contacts in 1 request
Record + related data ?include=company,contact — related data in one response
Scanning 1000+ records POST /v1/{entity}/search with limit + offset