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

Search sections

POST /v1/catalog-sections/search

Search catalog sections by conditions passed in the request body.

Unlike GET /v1/catalog-sections, the filter, select, sort, limit, and offset parameters are passed in the JSON body rather than in the URL query string — conditions across several fields are expressed as a nested structure. Like the list, search requires filter.iblockId — without this field the request returns 400. The response format is the same as for the list.

Request fields (body)

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

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-sections/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "iblockId": 25, "active": true },
    "limit": 2
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-sections/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "iblockId": 25, "active": true },
    "limit": 2
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-sections/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { iblockId: 25, active: true },
    limit: 2,
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-sections/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { iblockId: 25, active: true },
    limit: 2,
  }),
})

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 DescriptionID of the parent section. null — top-level section. List: GET /v1/catalog-sections
Fielddata[].name Typestring DescriptionSection name
Fielddata[].code Typestring | null DescriptionSymbolic code of the section
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
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds

The meta fields sit next to data, not inside it. Paginate by meta.hasMore: a page whose data length equals limit can still be the last one.

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": true,
    "durationMs": 165
  }
}

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 request body example
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionFilter on a field the section does not have. The message contains the list of available fields
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the catalog scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal, and 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