For AI agents: markdown of this page — /docs-content-en/entities/calendar-sections.md documentation index — /llms.txt

Calendar sections

Managing Bitrix24 calendar sections: personal, group, and meeting-room calendars. A section is the calendar itself, where events live. One employee can have several sections, for example "Work" and "Personal", while a group has one or more group calendars.

Bitrix24 API: calendar.section.* Scope: calendar

List sections

GET /v1/calendar-sections

Returns all calendar sections for a type + ownerId pair. A single employee may have several sections — for example, "Work", "Personal", "Team meetings".

Parameters

Parameter Type Req. Default Description
type (query) string yes — Calendar type: user — personal, group — group, company_calendar — company calendar, location — meeting room
ownerId (query) number yes — Calendar owner identifier. For an employee — GET /v1/users, for a workgroup — its id, for type=location — 0
limit (query) number no 50 Number of records, up to 5000. When limit > 50, auto-pagination is enabled
offset (query) number no 0 Accepted, but does not affect the selection — the list returns all sections of the type + ownerId pair

Filtering via filter[...] is not supported. Any filter[name]=... key returns 400 UNSUPPORTED_FILTER before reaching Bitrix24.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/calendar-sections?type=user&ownerId=1" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const params = new URLSearchParams({ type: 'user', ownerId: '1' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/calendar-sections?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Found ${meta.total} sections`)

JavaScript — OAuth application

javascript 
const params = new URLSearchParams({ type: 'user', ownerId: '1' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/calendar-sections?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data array Array of sections
meta.total number Total number of sections in the selection
meta.hasMore boolean Whether there are more records beyond limit

Fields of a single section in the data array:

Field Type RO Description
id number yes Section identifier
name string no Name
description string no Description
type string no Calendar type: user, group, company_calendar, location
ownerId number no Calendar owner identifier
color string no Section color in #RRGGBB format
textColor string no Text color in #RRGGBB format
export object no iCal export parameters: { "ALLOW": boolean, "SET": "all" | "3_9" | "6_12" }. The keys inside the object are uppercase, the format is preserved on write and read without transformations
access object yes Access rights map: key — access-right identifier, value — numeric permission identifier
perm object yes Current employee's permissions map: view_time, view_title, view_full, add, edit, edit_section, access
isCollab boolean yes Collab membership
createdBy number yes Section creator identifier
dateCreate datetime yes Creation date
updatedAt datetime yes Last modification date

"RO" — the field is read-only, it cannot be passed in POST / PATCH, otherwise Vibecode returns 400 READONLY_FIELD.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 42,
      "name": "Work",
      "description": "Main work calendar",
      "type": "user",
      "ownerId": 1,
      "color": "#9cbeee",
      "textColor": "#283000",
      "export": {
        "ALLOW": true,
        "SET": "3_9"
      },
      "access": {
        "U1": "calendar_owner",
        "G2": 13
      },
      "perm": {
        "view_time": true,
        "view_title": true,
        "view_full": true,
        "add": true,
        "edit": true,
        "edit_section": true,
        "access": true
      },
      "isCollab": false,
      "createdBy": 1,
      "dateCreate": "2026-05-15T09:34:33+00:00",
      "updatedAt": "2026-05-15T09:34:33+00:00"
    }
  ],
  "meta": {
    "total": 1,
    "hasMore": false
  }
}

Error response example

400 — required type or ownerId not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_PARAMS",
    "message": "GET /v1/calendar-sections requires query parameters: type, ownerId. Example: GET /v1/calendar-sections?type=...&ownerId=..."
  }
}

Errors

HTTP Code Description
400 MISSING_REQUIRED_PARAMS type or ownerId not passed
400 UNSUPPORTED_FILTER A filter[...] key was passed — filtering is not supported. Only type, ownerId, limit, offset are allowed
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

The full list of common API errors — Errors.

Known specifics

limit trims the output on the Vibecode API side, offset has no effect. The list always returns all sections of the specified type + ownerId pair. limit trims the received array to N records, while offset is accepted but ignored — you cannot skip records with it.

The export field preserves Bitrix24 casing. The keys inside export stay ALLOW and SET in uppercase — they are not converted to camelCase. The same when sending via POST /v1/calendar-sections: pass exactly { "ALLOW": true, "SET": "3_9" }.

A section cannot be fetched by a single id via the API. The GET /v1/calendar-sections/:id endpoint is not supported. To find one section by id — get the list and filter on the client side: data.find(s => s.id === 42).

See also