## 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 | Required | Default | Description |
|----------|-----|:-----:|-----------|---------|
| `type` (query) | string | yes | — | Calendar type: `user` — personal, `group` — workgroup, `company_calendar` — company calendar, `location` — meeting room |
| `ownerId` (query) | number | yes | — | Calendar owner identifier. For an employee — the ID from [`GET /v1/users`](/docs/entities/users/list), 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 result set — the list returns all sections of the `type` + `ownerId` pair |
| `select` (query) | string | no | — | Comma-separated fields to include in the response: `?select=id,name,color` |
| `filter` (query) | object | no | — | Another way to pass `type` and `ownerId`. The list accepts no other keys: for example, `filter[name]=...` returns `400 UNSUPPORTED_FILTER` before reaching Bitrix24.<br>[Filtering syntax](/docs/filtering). Example: `?filter[type]=user&filter[ownerId]=1` |
| `sort` (query) | string | no | — | Accepted, but does not affect the order of sections in the response |
| `order` (query) | object \| string | no | — | Both forms — `?order[id]=desc` and `?order=desc` — are accepted but, like `sort`, do not affect the order of sections in the response. In the `order[field]` form, a direction other than `asc`, `desc`, `ASC`, or `DESC` returns `400 INVALID_SORT_DIRECTION` |
| `withTotal` (query) | string | no | — | The values `true` and `false` are recognized. For sections, the parameter does not affect the response: `meta.total` is returned even with `withTotal=false` |

## 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 result set |
| `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. For an employee — the ID from [`GET /v1/users`](/docs/entities/users/list) |
| `color` | string | no | Section color in `#RRGGBB` format |
| `textColor` | string | no | Text color in `#RRGGBB` format |
| `export` | object | no | Export parameters in iCal format. The key set depends on the direction: on read, the response carries `ALLOW`, `PATH`, and `LINK`; on write, the endpoint accepts `ALLOW` and `SET` — see [Create a section](./create.md). The keys are uppercase and are not converted to camelCase |
| `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 | Whether the section belongs to a collab |
| `createdBy` | number | yes | ID of the employee who created the section. Employee list: [`GET /v1/users`](/docs/entities/users/list) |
| `dateCreate` | datetime | yes | Creation date |
| `updatedAt` | datetime | yes | Last modification date |

"RO" — the field is read-only: passing it in `POST` / `PATCH` makes Vibecode return `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,
        "PATH": "https://example.bitrix24.com/company/personal/user/1/calendar/",
        "LINK": "&type=user&owner=1&ncc=1&user=1&sec_id=42&sign=704a559a691722ae080fa420dcb9d7f8"
      },
      "access": {
        "U1": 39,
        "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-15 09:34:33",
      "updatedAt": "2026-05-15 09:34:33"
    }
  ],
  "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 other than `filter[type]` and `filter[ownerId]` was passed |
| 400 | `INVALID_SORT_DIRECTION` | The direction in `order[field]` is not `asc`, `desc`, `ASC`, or `DESC` |
| 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 |
| 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header |

For the full list of common API errors, see [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` key set differs between read and write.** The response carries `ALLOW`, `PATH`, and `LINK`: `PATH` is the calendar URL in the Bitrix24 account; `LINK` is the signed query string appended to the iCal export URL. The export period is set with the `SET` key when sending via [`POST /v1/calendar-sections`](./create.md), but it never comes back in the response — store the value on your side if you need it for display. Bitrix24 key casing is preserved in both directions: the keys stay uppercase and are not converted to camelCase.

**Dates arrive in the Bitrix24 account time zone without an offset.** The format of `dateCreate` and `updatedAt` is `YYYY-MM-DD HH:MM:SS`. To parse them as a point in time, append the account's time zone offset yourself: `new Date(s.replace(' ', 'T') + '+00:00')`.

**A single section cannot be fetched by `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 it on the client side: `data.find(s => s.id === 42)`.

## See also

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