## 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` — group, `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 selection — 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

```bash
curl "https://vibecode.bitrix24.com/v1/calendar-sections?type=user&ownerId=1" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
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 selection |
| `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 | iCal export parameters: `{ "ALLOW": boolean, "SET": "all" \| "3_9" \| "6_12" }`. The keys inside the object are uppercase, the format is preserved on write and read without transformations |
| `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, it 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,
        "SET": "3_9"
      },
      "access": {
        "U1": "calendar_owner",
        "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-15T09:34:33+00:00",
      "updatedAt": "2026-05-15T09:34:33+00:00"
    }
  ],
  "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 |

The full list of common API errors — [Errors](/docs/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` field preserves Bitrix24 casing.** The keys inside `export` stay `ALLOW` and `SET` in uppercase — they are not converted to camelCase. The same when sending via [`POST /v1/calendar-sections`](./create.md): pass exactly `{ "ALLOW": true, "SET": "3_9" }`.

**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

- [Create section](./create.md)
- [Update section](./update.md)
- [Delete section](./delete.md)
- [Batch operations](./batch.md)
- [Calendar events](/docs/entities/calendar-events)