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

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 — workgroup, 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 result set — 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 result set
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 Export parameters in iCal format. The key set depends on the direction: on read the response carries ALLOW, PATH, and LINK, on write the endpoint accepts ALLOW and SET — see Create a section. The keys are uppercase and are not converted to camelCase
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 and 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,
        "PATH": "https://example.bitrix24.com/company/personal/user/1/calendar/",
        "LINK": "&type=user&owner=1&ncc=1&user=1&sec_id=42&sign=704a559a691722ae080fa420dcb9d7f8"
      },
      "access": {
        "U1": 39,
        "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-15 09:34:33",
      "updatedAt": "2026-05-15 09:34:33"
    }
  ],
  "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
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

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 key set differs between read and write. The response carries ALLOW, PATH, and LINK: PATH is the calendar address on the Bitrix24 account, LINK is the signed tail of the iCal export URL. The export period is set with the SET key when sending via POST /v1/calendar-sections, but it never comes back in the response — store the value on your side if you need it for display. Bitrix24 key casing is preserved in both directions: the keys stay uppercase and are not converted to camelCase.

Dates arrive in the Bitrix24 account time zone with no offset stated. The format of dateCreate and updatedAt is YYYY-MM-DD HH:MM:SS. To parse them as a point in time, append the account offset yourself: new Date(s.replace(' ', 'T') + '+00:00').

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