## Calendar section search `POST /v1/calendar-sections/search` Returns the sections of a single Bitrix24 calendar. The parameters are passed in the request body rather than in the query string. The calendar is addressed by the `type` and `ownerId` pair inside the `filter` object. The same set of sections is returned by [`GET /v1/calendar-sections`](/docs/entities/calendar-sections/list), where the `type` and `ownerId` pair is passed in the query string. ## Request fields (body) | Field | Type | Required | Default | Description | |------|-----|:-----:|-----------|---------| | `filter` | object | yes | — | The calendar address — exactly two keys, `type` and `ownerId`. Any other key returns `400 UNSUPPORTED_FILTER`. Example: `{ "type": "user", "ownerId": 1 }` | | `filter.type` | string | yes | — | Calendar type: `user`, `group`, `company_calendar`, or `location` | | `filter.ownerId` | number | yes | — | The owner identifier: for an employee, the ID from [`GET /v1/users`](/docs/entities/users); for a workgroup, the workgroup ID; for the `location` type, `0` | | `limit` | number | no | `50` | Number of records, up to 5000 | | `select` | string[] | no | — | Field selection: `["id", "name", "color"]` | ## Examples ### curl — personal key ```bash curl -X POST "https://vibecode.bitrix24.com/v1/calendar-sections/search" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "filter": { "type": "user", "ownerId": 1 }, "limit": 3 }' ``` ### curl — OAuth application ```bash curl -X POST "https://vibecode.bitrix24.com/v1/calendar-sections/search" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "filter": { "type": "user", "ownerId": 1 }, "limit": 3 }' ``` ### JavaScript — personal key ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/calendar-sections/search', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ filter: { type: 'user', ownerId: 1 }, limit: 3, }), }) const { success, data, meta } = await res.json() console.log(`Found ${meta.total} sections`) ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/calendar-sections/search', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ filter: { type: 'user', ownerId: 1 }, limit: 3, }), }) const { success, data, meta } = await res.json() ``` ## Response fields | Field | Type | Description | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data` | array | Array of sections. For the fields of a single section, see [List sections](/docs/entities/calendar-sections/list). | | `meta.total` | number | Number of sections in the selection | | `meta.hasMore` | boolean | Whether there are more records beyond `limit` | | `meta.durationMs` | number | Request duration in milliseconds | ## Response example ```json { "success": true, "data": [ { "id": 3, "name": "user@example.com", "description": null, "color": "#86b100", "textColor": "#7bd148", "export": { "ALLOW": true, "PATH": "https:///company/personal/user/1/calendar/", "LINK": "&type=user&owner=1&ncc=1&user=1&sec_id=3&sign=&bx_hit_hash=" }, "type": "user", "ownerId": 1, "createdBy": 1, "dateCreate": "2020-04-22 16:21:00", "updatedAt": "2026-08-15 15:23:51", "access": { "G2": 31, "U1": 39 }, "isCollab": false, "perm": { "view_time": true, "view_title": true, "view_full": true, "add": true, "edit": true, "edit_section": true, "access": true } } ], "meta": { "total": 1, "hasMore": false, "durationMs": 2001 } } ``` `` is the Bitrix24 portal domain; `` and `` are the export link signatures — they differ for every section. ## Error response example 400 — required keys are missing from `filter`: ```json { "success": false, "error": { "code": "MISSING_REQUIRED_PARAMS", "message": "POST /v1/calendar-sections/search requires: type, ownerId. Example body: { \"filter\": {\"type\":\"...\",\"ownerId\":\"...\"} }" } } ``` ## Errors | HTTP | Code | Description | |------|-----|---------| | 400 | `MISSING_REQUIRED_PARAMS` | `type` or `ownerId` is missing from `filter`. The message lists the missing keys | | 400 | `UNSUPPORTED_FILTER` | A key other than `type` and `ownerId` was passed in `filter` | | 403 | `SCOPE_DENIED` | The API key does not have the `calendar` scope | | 401 | `TOKEN_MISSING` | The API key has no configured tokens | | 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is temporarily unavailable — retry the request later | | 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header | For the full list of common API errors, see [Errors](/docs/errors). ## Known specifics **You cannot narrow the results within a calendar.** The `type` and `ownerId` pair addresses the calendar as a whole, and the search returns every section it holds. Look up the section you need in the returned array on your side — by `name` or `id`, for example. **The search has no offset — you cannot page through the results.** The `offset` field is accepted without an error but has no effect: a request with `limit: 1` and `offset: 1` returns the same first section as a request with no offset. To get the whole calendar, raise `limit` instead of paging. ## See also - [List sections](/docs/entities/calendar-sections/list) - [Calendar section fields](/docs/entities/calendar-sections/fields) - [Create a section](/docs/entities/calendar-sections/create) - [Batch operations on calendar sections](/docs/entities/calendar-sections/batch) - [Calendar events](/docs/entities/calendar-events)