# Bookings

Bookings reserve Bitrix24 account resources for a given time interval: create, get by id, list and search by date range, update, and delete. Each booking is tied to one or more resources and stores a period from and to.

Bitrix24 API: `booking.v1.booking.*`
Scope: `booking`

## Operations

- [Create a booking](./bookings/create.md) — `POST /v1/bookings`
- [List bookings](./bookings/list.md) — `GET /v1/bookings`
- [Get a booking](./bookings/get.md) — `GET /v1/bookings/:id`
- [Update a booking](./bookings/update.md) — `PATCH /v1/bookings/:id`
- [Delete a booking](./bookings/delete.md) — `DELETE /v1/bookings/:id`
- [Search bookings](./bookings/search.md) — `POST /v1/bookings/search`
- [Booking fields](./bookings/fields.md) — `GET /v1/bookings/fields`

## Fields

### Editable fields

Accepted on [create](./bookings/create.md) and [update](./bookings/update.md).

| Field | Type | Description |
|------|-----|---------|
| `resourceIds` | number[] | Ids of the resources the booking reserves. Required on create, the array cannot be empty. The resource list cannot be fetched through the Vibecode API — specify the known ids |
| `datePeriod` | object | Booking period. Required on create. Structure: `from` and `to`, each with `timestamp` (Unix seconds) and `timezone` (IANA-format time zone, e.g. `UTC`) |
| `name` | string | Booking name. Optional — may be `null` |
| `description` | string | Booking description. Optional — may be `null` |

### Read-only

Returned in the response, not accepted on create and update.

| Field | Type | Description |
|------|-----|---------|
| `id` | number | Booking id |

## What you need to know before working

1. **Two fields are required to create:** `resourceIds` (non-empty array) and `datePeriod`. Without either of them the response is `422 BITRIX_ERROR` with the list of missing fields. `name` and `description` are optional.
2. **`datePeriod` is a nested object, not a string.** Time is given as `{"from": {"timestamp": 1780132384, "timezone": "UTC"}, "to": {"timestamp": 1780135984, "timezone": "UTC"}}`. `timestamp` is Unix seconds, `timezone` is an IANA-format time zone.
3. **List and search require a date interval.** `GET /v1/bookings` and `POST /v1/bookings/search` take required `dateFrom` and `dateTo` (ISO 8601 format or Unix seconds). Without them — `400 MISSING_REQUIRED_PARAMS`. Bookings outside the interval are not included in the response.
4. **Field names stay as they are.** Field names in the response match the names in the request (`resourceIds`, `datePeriod`) — there is no additional case conversion.
5. **The field set is fixed.** All available fields are listed in the "Fields" section above.

## Typical scenario

1. Create a booking for the required period: [`POST /v1/bookings`](./bookings/create.md).
2. Get bookings for an interval: [`GET /v1/bookings?dateFrom=...&dateTo=...`](./bookings/list.md).
3. Change the period or name: [`PATCH /v1/bookings/:id`](./bookings/update.md).
4. Cancel the booking: [`DELETE /v1/bookings/:id`](./bookings/delete.md).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Required interval for list and search | `dateFrom` + `dateTo` |
| Default page size | 50 (`limit`) |
| 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)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [Entities reference](/docs/entities-index)