## List sections

`GET /v1/lists/:iblockId/sections`

Returns the sections of the specified list. Sections group elements and can form a tree — a section may have a parent section.

## Parameters

| Parameter | Type | Required | Default | Description |
|----------|-----|:-----:|:---------:|---------|
| `iblockId` (path) | string | yes | — | List ID or symbolic code. Use the `ID` or `CODE` field from [List of lists](/docs/lists/lists/list) |
| `iblockTypeId` (query) | string | no | `lists` | Infoblock type. Values:<br>`lists` — regular lists, the default<br>`lists_socnet` — workgroup lists<br>`bitrix_processes` — service workflows<br>`structure` — company structure type (contains the built-in absence calendar infoblock `absence`) |
| `socnetGroupId` (query) | number | no | — | Workgroup ID for lists of type `lists_socnet`. A positive integer from the `id` field returned by [List workgroups](/docs/entities/workgroups/list). Omit it for regular lists |
| `filter` (query) | object | no | — | Filter by section fields, such as `ID`, `NAME`, `CODE`, `ACTIVE`, `GLOBAL_ACTIVE`. Pass all conditions as one JSON object or in bracket notation: `?filter={"NAME":"Invoices"}` or `?filter[NAME]=Invoices`. An empty `?filter=` means "no filter". Mixing forms or nesting brackets deeper than two levels returns `400 INVALID_FILTER`. Unknown names and names with operators, such as `>ID`, are ignored |
| `filter.SECTION_ID` | number | no | — | Parent section ID from the `ID` field returned by this method. Selects immediate child sections. `0` selects root sections. The response field `IBLOCK_SECTION_ID` and the `SORT` field do not work in filters: conditions using these names are ignored |
| `select` (query) | string | no | — | Comma-separated list of fields to return. Example: `?select=ID,NAME,CODE,IBLOCK_SECTION_ID,SORT`. Unknown names are ignored. If no names are recognized or `select` is omitted, the full section object is returned |

## Examples

### curl — personal key

```bash
curl 'https://vibecode.bitrix24.com/v1/lists/167/sections?select=ID,NAME,CODE,IBLOCK_SECTION_ID,SORT' \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl 'https://vibecode.bitrix24.com/v1/lists/167/sections?select=ID,NAME,CODE,IBLOCK_SECTION_ID,SORT' \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/167/sections?select=ID,NAME,CODE,IBLOCK_SECTION_ID,SORT', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data, meta } = await res.json()
console.log('Sections:', meta.total)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/167/sections?select=ID,NAME,CODE,IBLOCK_SECTION_ID,SORT', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
```

## Response fields

Numeric values and the `Y`/`N` flags are returned as strings. If `select` contains recognized field names, only those fields remain in the object.

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of section objects. For the object structure, see [Get section](./get.md#response-fields). Returns `[]` if no sections match |
| `meta` | object | Section count information |
| `meta.total` | number | Total number of sections matching the filter. This is the only field in `meta` |

## Response example

Response to the request with `select=ID,NAME,CODE,IBLOCK_SECTION_ID,SORT` in the examples above:

```json
{
  "success": true,
  "data": [
    {
      "ID": "263",
      "NAME": "Sales department documents",
      "CODE": "sales_docs",
      "IBLOCK_SECTION_ID": null,
      "SORT": "100"
    },
    {
      "ID": "267",
      "NAME": "Marketing department documents",
      "CODE": "marketing_docs",
      "IBLOCK_SECTION_ID": null,
      "SORT": "300"
    },
    {
      "ID": "265",
      "NAME": "Invoices",
      "CODE": "invoices",
      "IBLOCK_SECTION_ID": "263",
      "SORT": "200"
    }
  ],
  "meta": {
    "total": 3
  }
}
```

## Error response example

400 — the `filter` parameter is not valid JSON:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_FILTER",
    "message": "filter must be valid JSON, e.g. filter={\"NAME\":\"%urgent%\"}."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_FILTER` | `filter` is not a JSON object. Mixing JSON and bracket notation, conflicting forms of the same condition, and bracket nesting deeper than two levels are also rejected |
| 400 | `INVALID_IBLOCK_TYPE` | `iblockTypeId` is not one of `lists`, `bitrix_processes`, `lists_socnet`, `structure` |
| 403 | `BITRIX_ACCESS_DENIED` | No access to the list |
| 422 | `BITRIX_ERROR` | The list does not exist or its type does not match the request parameters, for example, when `socnetGroupId` is passed for a regular list. The response contains `b24Code: "0"` |
| 409 | `LISTS_MODULE_NOT_ENABLED` | The Lists module is not enabled on the portal |
| 403 | `SCOPE_DENIED` | The API key lacks the `lists` scope |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**The tree is reconstructed from `IBLOCK_SECTION_ID`.** Sections are returned as a flat array. When using `select`, include `ID` and `IBLOCK_SECTION_ID`. To build the tree, group sections by their `IBLOCK_SECTION_ID` value: `null` for root sections and the parent section ID for nested sections.

## See also

- [Get section](/docs/lists/sections/get)
- [Create a section](/docs/lists/sections/create)
- [Sections](/docs/lists/sections)
- [Filtering syntax](/docs/filtering)