For AI agents: markdown of this page — /docs-content-en/entities/catalog-sections/list.md documentation index — /llms.txt

List sections

GET /v1/catalog-sections

Returns a list of catalog sections with support for filtering, sorting, field selection, and pagination. Requires the filter[iblockId] filter — the catalog to select sections from. Without this filter, the request returns 400.

Parameters

Parameter Type Required Default Description
Parameterfilter Typeobject Requiredyes Default— DescriptionFiltering conditions. The filter[iblockId] key is required — the catalog ID from GET /v1/catalogs.
Filtering syntax. Example: ?filter[iblockId]=25
Parameterselect Typestring Requiredno Default— DescriptionField selection: ?select=id,name,sort. Only the listed fields are returned
Parametersort Typestring Requiredno Default— DescriptionSort field. The - prefix means descending order: ?sort=-sort
Parameterlimit Typenumber Requiredno Default50 DescriptionNumber of records (up to 5000)
Parameteroffset Typenumber Requiredno Default0 DescriptionOffset from the start of the result set

To select sections of a single parent, add filter[iblockSectionId].

For limit > 50, the response is automatically assembled from several pages on the server side. The maximum is 5000 records per call. If more records match the filter than were returned, meta.hasMore is true.

Examples

curl — personal key

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/catalog-sections?filter[iblockId]=25" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/catalog-sections?filter[iblockId]=25" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const url = 'https://vibecode.bitrix24.com/v1/catalog-sections?filter[iblockId]=25'
const res = await fetch(url, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Sections: ${meta.total}`)

JavaScript — OAuth application

javascript 
const url = 'https://vibecode.bitrix24.com/v1/catalog-sections?filter[iblockId]=25'
const res = await fetch(url, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of sections
Fielddata[].id Typenumber DescriptionSection identifier
Fielddata[].iblockId Typenumber DescriptionID of the catalog the section belongs to. List: GET /v1/catalogs
Fielddata[].iblockSectionId Typenumber | null DescriptionParent section ID. null means a top-level section. List: GET /v1/catalog-sections
Fielddata[].name Typestring DescriptionSection name
Fielddata[].code Typestring | null DescriptionSection symbolic code
Fielddata[].xmlId Typestring | null DescriptionExternal identifier
Fielddata[].sort Typenumber DescriptionSort index
Fielddata[].active Typeboolean DescriptionWhether the section is active
Fielddata[].description Typestring | null DescriptionSection description
Fielddata[].descriptionType Typestring DescriptionDescription format: text or html
Fieldmeta.total Typenumber DescriptionTotal number of records matching the filter
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "active": true,
      "code": "clothes",
      "description": null,
      "descriptionType": "text",
      "iblockId": 25,
      "iblockSectionId": null,
      "id": 31,
      "name": "Clothing",
      "sort": 50,
      "xmlId": null
    },
    {
      "active": true,
      "code": "shoes",
      "description": null,
      "descriptionType": "text",
      "iblockId": 25,
      "iblockSectionId": 31,
      "id": 35,
      "name": "Footwear",
      "sort": 100,
      "xmlId": null
    }
  ],
  "meta": {
    "total": 37,
    "hasMore": false
  }
}

Error response example

400 — filter on a non-existent field:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'bogus' for entity 'catalog-sections'. Available: id, iblockId, iblockSectionId, name, xmlId, code, sort, active, description, descriptionType"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FILTER DescriptionThe required filter[iblockId] filter was not passed. The request is rejected before Bitrix24 is called — the message contains the name of the missing field and a call example
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionFiltering by a field the section does not have. The message contains the list of available fields
HTTP400 CodeUNKNOWN_SORT_FIELD DescriptionSorting by a field the section does not have
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the catalog scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not provided
HTTP429 CodeRATE_LIMITED DescriptionRate 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.

See also