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

List sections

GET /v1/product-sections

Returns product catalog sections with filtering and auto-pagination support. These are the same sections available via GET /v1/catalog-sections — with the same id.

Parameters

Parameter Type Default Description
Parameterlimit Typenumber Default50 DescriptionNumber of records, up to 5000. When limit > 50, Vibecode assembles several pages into one response
Parameteroffset Typenumber Default0 DescriptionOffset from the start of the selection
Parameterselect Typestring Default— DescriptionField selection: ?select=id,name,sectionId
Parametersort Typestring Default— DescriptionSorting by name, sort, code, xmlId, catalogId, sectionId: ?sort=name, a minus sign means descending: ?sort=-name
Parameterorder Typeobject Default— DescriptionSorting as an object: ?order[name]=desc. If sort is passed, it takes precedence
Parameterinclude Typestring Default— DescriptionRelated data: catalog, parentSection. See the "Related data" section
ParameterwithTotal Typestring Default— DescriptionAccepts true or false, but does not change counting or the presence of meta.total for product sections
Parameterfilter Typeobject Default— DescriptionFiltering by the fields of GET /v1/product-sections/fields. Exact-match and $in (IN set) only, by id, name, xmlId, code, catalogId, sectionId. Operators (>, >=, <, <=, !, %, $ne, $contains, $nin) and filtering by sort are not supported — you get 400 UNSUPPORTED_FILTER.
Filtering syntax. Example: ?filter[catalogId]=25. Source of catalogId: GET /v1/catalogs

Examples

curl — personal key

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/product-sections?filter[catalogId]=25&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/product-sections?filter[catalogId]=25&limit=10" \
  -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/product-sections?filter[catalogId]=25&limit=10', {
  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 res = await fetch('https://vibecode.bitrix24.com/v1/product-sections?filter[catalogId]=25&limit=10', {
  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[].name Typestring DescriptionSection name
Fielddata[].catalogId Typenumber DescriptionID of the catalog the section belongs to. Source: GET /v1/catalogs
Fielddata[].sectionId Typenumber | null DescriptionParent section ID — the id of another section from this same list. Source: GET /v1/product-sections. null for a top-level section
Fielddata[].code Typestring | null DescriptionSection symbolic code
Fielddata[].xmlId Typestring | null DescriptionExternal identifier
Fieldmeta.total Typenumber DescriptionTotal number of records matching the filter
Fieldmeta.hasMore Typeboolean DescriptionWhether more records exist beyond limit

The sort field is not returned in the list response. For the full set of section fields, see GET /v1/product-sections/fields.

To retrieve related records together with the list, use the include parameter:

GET /v1/product-sections?filter[catalogId]=25&limit=1&include=catalog,parentSection

Available include values: catalog — the product catalog the section belongs to, and parentSection — the parent section. The catalog include reads catalogs, so the key needs the catalog scope. For a top-level section, parentSection comes back as null. The result is in the _included field of each data[] element:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 31,
      "catalogId": 25,
      "sectionId": null,
      "name": "Clothing",
      "code": "clothes",
      "xmlId": "666",
      "_included": {
        "catalog": {
          "iblockId": 25,
          "iblockTypeId": "CRM_PRODUCT_CATALOG",
          "id": 25,
          "lid": "s1",
          "name": "CRM product catalog",
          "productIblockId": null,
          "skuPropertyId": null,
          "subscription": "N",
          "vatId": 1,
          "yandexExport": false
        },
        "parentSection": null
      }
    }
  ],
  "meta": {
    "total": 37,
    "hasMore": true
  }
}

More on the include parameter: Related data.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 31,
      "catalogId": 25,
      "sectionId": null,
      "name": "Clothing",
      "code": "clothes",
      "xmlId": "666"
    },
    {
      "id": 45,
      "catalogId": 25,
      "sectionId": null,
      "name": "Winter collection",
      "code": "winter",
      "xmlId": null
    }
  ],
  "meta": {
    "total": 36,
    "hasMore": true
  }
}

Error response example

403 — no scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Errors

HTTP Code Description
HTTP400 CodeUNSUPPORTED_FILTER DescriptionAn operator or a non-filterable field in the filter. Filter by exact match or $in on id, name, xmlId, code, catalogId, sectionId
HTTP400 CodeINVALID_FILTER DescriptionError in filter syntax
HTTP400 CodeINVALID_INCLUDE DescriptionUnknown name in include. The message lists the available ones: catalog, parentSection
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the crm scope
HTTP403 CodeSCOPE_DENIED Descriptioninclude=catalog was passed, but the key lacks 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.

Known specifics

Exact match only. The filter uses exact match (and $in sets) on id, name, xmlId, code, catalogId, sectionId. Operators (>, <, !, %), $ne/$contains/$nin and filtering by sort return 400 UNSUPPORTED_FILTER — so you see immediately that the filter did not apply, instead of getting the whole list unfiltered.

Sections of one parent. To get nested sections inside a specific section, filter by exact match on filter[sectionId] with the parent identifier.

Without a filter, sections of all catalogs in your Bitrix24 account are returned. To limit the selection to a single catalog, pass filter[catalogId]. To list catalogs, use GET /v1/catalogs.

See also