# Calendar events

Manage Bitrix24 calendar events: personal, group, and company calendars. Supports creating, retrieving, updating, and deleting events, as well as fetching the field schema.

Bitrix24 API: `calendar.event.*`
Scope: `calendar`

## Operations

- [Create event](./calendar-events/create.md) — `POST /v1/calendar-events`
- [List events](./calendar-events/list.md) — `GET /v1/calendar-events`
- [Get event](./calendar-events/get.md) — `GET /v1/calendar-events/:id`
- [Update event](./calendar-events/update.md) — `PATCH /v1/calendar-events/:id`
- [Delete event](./calendar-events/delete.md) — `DELETE /v1/calendar-events/:id`
- [Search events](./calendar-events/search.md) — `POST /v1/calendar-events/search`
- [Event fields](./calendar-events/fields.md) — `GET /v1/calendar-events/fields`

## Key fields

| Field | Description |
|------|---------|
| `type` | Calendar type: `user`, `group`, `company_calendar` |
| `ownerId` | Calendar owner ID. For `type=user` — employee ID from `GET /v1/users`, for `type=group` — workgroup ID |
| `name` | Event title |
| `from` / `to` | Event start and end in ISO 8601 |
| `timezoneFrom` / `timezoneTo` | Event timezone in IANA format (`UTC`). Optional — without it, the timezone of the employee the API key is bound to is used |
| `skipTime` | All-day event — when `true`, the duration is fixed at 24 hours |
| `sectionId` | Calendar section ID |
| `attendees` | Array of invited employee IDs for writing (`POST`/`PATCH`). On read, attendees come in the `attendeeList`, `attendeesCodes` fields |
| `rrule` | Recurrence schedule of a recurring event — an object with periodicity and series-boundary fields |

Full field list — [`GET /v1/calendar-events/fields`](./calendar-events/fields.md).

## What you need to know before working

1. **A calendar is identified by the `type` + `ownerId` pair.** This pair is required both for listing events and for creating them. Events are always tied to a specific calendar, not to the Bitrix24 account as a whole.
2. **Creating an event requires 5 fields:** `type`, `ownerId`, `name`, `from`, `to`. For an all-day event, pass `skipTime: true`; the time in `from`/`to` is ignored, and the event duration is fixed at 24 hours.
3. **`from` and `to` accept ISO 8601 in any form:** with an offset (`"2026-06-01T10:00:00+00:00"`), in UTC (`"2026-06-01T10:00:00Z"`), or without a zone (`"2026-06-01T10:00:00"`). The response returns ISO 8601 with an offset; the instant and wall-clock match what is displayed in the user's calendar.
4. **The event timezone is set via `timezoneFrom` / `timezoneTo`.** Pass an IANA name (`UTC`, `Asia/Almaty`, `UTC`). If the parameters are omitted, the event is created in the timezone of the employee who owns the API key.
5. **`PATCH` is partial.** When updating a single field, Vibecode reads the current event state and automatically supplies `type`, `ownerId`, `name`, which Bitrix24 requires on every update.
6. **Disabling a source is on the application side, not the platform.** The entity API is stateless: to stop receiving calendar events, the application does not call `GET /v1/calendar-events`. The platform stores no "source enabled" flag and does not resume loading based on the application's saved settings. `calendar-events` responses are not cached — Vibecode caches only `GET /v1/users` and `GET /v1/statuses`, see [Caching](/docs/optimization). Stale data after a source is disabled comes from the application's own state, not from the platform.

## Typical scenario

1. Find the calendar owner: [`GET /v1/users`](/docs/entities/users) for a personal calendar, or a workgroup ID for a group calendar.
2. Get upcoming events: [`GET /v1/calendar-events?type=user&ownerId=1`](./calendar-events/list.md).
3. Create a new one or update an existing one: [`POST /v1/calendar-events`](./calendar-events/create.md) / [`PATCH /v1/calendar-events/:id`](./calendar-events/update.md).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Auto-pagination | kicks in when `limit > 50` |
| `offset` on large selections | `limit ≤ 500` recommended when `offset ≥ 2500` |
| Batch requests | 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

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