# Calendar sections

Manage 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`
- [Calendar section search](./calendar-sections/search.md) — `POST /v1/calendar-sections/search`
- [Calendar section fields](./calendar-sections/fields.md) — `GET /v1/calendar-sections/fields`
- [Create a section](./calendar-sections/create.md) — `POST /v1/calendar-sections`
- [Update section](./calendar-sections/update.md) — `PATCH /v1/calendar-sections/:id`
- [Delete a section](./calendar-sections/delete.md) — `DELETE /v1/calendar-sections/:id`
- [Batch operations on calendar sections](./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 |
| `POST /v1/calendar-sections/aggregate` | Aggregation across sections is not supported |

If you try to call an unsupported 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. The key set depends on the direction — covered below, in "What to know before you start" |
| `access` | Section access-rights map. Read-only |
| `perm` | Permission map of the current employee. Read-only |
| `isCollab` | Collab membership. Read-only |

For the full list of fields with their types, write availability, and required flags, see [Calendar section fields](./calendar-sections/fields.md).

## What 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, and its key set depends on the direction.** On write, it takes `ALLOW` and `SET`. On read, it returns `ALLOW`, `PATH`, and `LINK` — the export period you sent is not returned. Unlike the other fields, the keys inside `export` are in upper case and are not converted to camelCase.
3. **`PATCH` requires `type` + `ownerId` in the request body.** A section cannot be found by a single `id` — so on update you must explicitly specify 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 cannot be undone 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 of "What 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 across 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)
- [API reference](/docs/api-reference)