لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/lists/sections.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Sections

Group list elements into sections: get the list of sections, create new ones, update and delete them. Sections support nesting — a section can have a parent.

Bitrix24 API: lists.section.* Scope: lists

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
ParameteriblockId (path) Typestring Requiredyes Default— DescriptionList ID or symbolic code. Use the ID or CODE field from List of lists
ParameteriblockTypeId (query) Typestring Requiredno Defaultlists DescriptionInfoblock type. Values:
lists — regular lists, the default
lists_socnet — workgroup lists
bitrix_processes — service workflows
structure — company structure type (contains the built-in absence calendar infoblock absence)
ParametersocnetGroupId (query) Typenumber Requiredno Default— DescriptionWorkgroup ID for lists of type lists_socnet. A positive integer from the id field returned by List workgroups. Omit it for regular lists
Parameterfilter (query) Typeobject Requiredno Default— DescriptionFilter 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
Parameterfilter.SECTION_ID Typenumber Requiredno Default— DescriptionParent 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
Parameterselect (query) Typestring Requiredno Default— DescriptionComma-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

Terminal 
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

Terminal 
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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of section objects. For the object structure, see Get section. Returns [] if no sections match
Fieldmeta Typeobject DescriptionSection count information
Fieldmeta.total Typenumber DescriptionTotal 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
HTTP400 CodeINVALID_FILTER Descriptionfilter 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
HTTP400 CodeINVALID_IBLOCK_TYPE DescriptioniblockTypeId is not one of lists, bitrix_processes, lists_socnet, structure
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo access to the list
HTTP422 CodeBITRIX_ERROR DescriptionThe 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"
HTTP409 CodeLISTS_MODULE_NOT_ENABLED DescriptionThe Lists module is not enabled on the portal
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the lists scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — 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