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

## Operations

- [List sections](./calendar-sections/list.md) — `GET /v1/calendar-sections`
- [Create a section](./calendar-sections/create.md) — `POST /v1/calendar-sections`
- [Update a section](./calendar-sections/update.md) — `PATCH /v1/calendar-sections/:id`
- [Delete a section](./calendar-sections/delete.md) — `DELETE /v1/calendar-sections/:id`
- [Batch operations](./calendar-sections/batch.md) — `POST /v1/calendar-sections/batch`

## What is not supported

| Operation | Reason |
|---|---|
| `GET /v1/calendar-sections/:id` | You cannot fetch a section by a single `id` — only a list by the `type` + `ownerId` pair is available. Request `GET /v1/calendar-sections?type=<...>&ownerId=<...>` and filter the result by the `id` field on the client side |
| `GET /v1/calendar-sections/fields` | Field descriptions are not available via the API — the field list is fixed and listed in [List sections](./calendar-sections/list.md) |
| `POST /v1/calendar-sections/search` | Search across sections is not supported |
| `POST /v1/calendar-sections/aggregate` | Aggregation across sections is not supported |

If you try to call a forbidden operation, for example `GET /v1/calendar-sections/42`, the Vibecode API returns `404`.

## Key fields

| Field | Description |
|------|---------|
| `id` | Section identifier |
| `type` | Calendar type: `user`, `group`, `company_calendar`, `location` |
| `ownerId` | Calendar owner identifier. For `type=user` — the employee `id` from `GET /v1/users`, for `type=group` — the workgroup `id`, for `type=location` — `0` |
| `name` | Section name |
| `color` | Section color in `#RRGGBB` format |
| `textColor` | Text color in `#RRGGBB` format |
| `export` | Export parameters in iCal format: `{ "ALLOW": boolean, "SET": "all" \| "3_9" \| "6_12" }` — the field keeps the Bitrix24 case and passes through without transformations |
| `access` | Section access-rights map. Returned read-only |
| `perm` | Permission map of the current employee. Returned read-only |
| `isCollab` | Whether it belongs to a collab. Returned read-only |

The full list of fields with types is in the [`GET /v1/calendar-sections`](./calendar-sections/list.md) response.

## What you need to know before you start

1. **A section is defined by the `type` + `ownerId` pair.** This pair is required both for the list and for deletion. It is also required for create and update.
2. **The `export` field is passed as an object.** Unlike the other fields, the keys inside `export` — `ALLOW` and `SET` — are in upper case and are kept without transformations on write and read.
3. **`PATCH` requires `type` + `ownerId` in the request body.** A section cannot be found by a single `id` — so on update you must explicitly state which section this `id` belongs to. The same numeric `id` can occur in different contexts — for example, for employee `1` and employee `2`.
4. **`DELETE` requires `type` + `ownerId` in the query string or body.** If both are passed, the query string takes priority. If the parameters are omitted, the Vibecode API returns `400 MISSING_REQUIRED_PARAMS` before reaching Bitrix24.
5. **Deleting a section is irreversible.** The request runs without confirmation and without the option to undo it via the API. If the section still holds events you need, move them to another section in advance via [`PATCH /v1/calendar-events/:id`](/docs/entities/calendar-events/update) with a new `sectionId`.

## Typical scenario

1. Get the list of an employee's sections: [`GET /v1/calendar-sections?type=user&ownerId=1`](./calendar-sections/list.md).
2. If you need a new separate section, for example "Team meetings", create it: [`POST /v1/calendar-sections`](./calendar-sections/create.md).
3. Rename it or change the color: [`PATCH /v1/calendar-sections/:id`](./calendar-sections/update.md).
4. If the section is no longer needed, move the events you need to another section in advance, as described in item 5 "What you need to know before you start", then delete it: [`DELETE /v1/calendar-sections/:id`](./calendar-sections/delete.md).

After a section is created, its `id` can be passed to [`POST /v1/calendar-events`](./calendar-events/create.md) via the `sectionId` field, so that all events are written to a single section.

## Limits

| Limit | Value |
|-------|----------|
| Maximum sections per request `limit` | 5000 |
| Auto-pagination | enabled when `limit > 50` |
| Batch of operations for one entity | up to 500 items in [`POST /v1/calendar-sections/batch`](./calendar-sections/batch.md) |
| Universal batch | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Rate limit | shared for the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Calendar events](/docs/entities/calendar-events)
- [Entity API](/docs/entity-api)
- [Batch](/docs/batch)
- [Entities reference](/docs/entities-index)