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

Create a section

POST /v1/catalog-sections

Creates a catalog section. Fields are passed flat at the JSON root.

Request fields (body)

Field Type Req. Default Description
iblockId number yes — ID of the catalog the section belongs to. List: GET /v1/catalogs
name string yes — Section name
iblockSectionId number no null Parent section ID. null — top-level section
code string no null Section symbolic code
xmlId string no null External identifier
sort number no 500 Sort index
active boolean no true Whether the section is active
description string no null Section description

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-sections" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "iblockId": 25,
    "name": "New arrivals",
    "sort": 100
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-sections" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "iblockId": 25,
    "name": "New arrivals",
    "sort": 100
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-sections', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    iblockId: 25,
    name: 'New arrivals',
    sort: 100,
  }),
})

const { success, data } = await res.json()
console.log('Section ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-sections', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    iblockId: 25,
    name: 'New arrivals',
    sort: 100,
  }),
})

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

Response fields

The full object of the created section is returned.

Field Type Description
id number Identifier of the created section
iblockId number Catalog ID
iblockSectionId number | null Parent section ID. null — top-level section
name string Section name
code string | null Section symbolic code
xmlId string | null External identifier
sort number Sort index
active boolean Whether the section is active
description string | null Section description
descriptionType string Description format: text or html

Response example

JSON 
{
  "success": true,
  "data": {
    "active": true,
    "code": null,
    "description": null,
    "descriptionType": "text",
    "iblockId": 25,
    "iblockSectionId": null,
    "id": 215,
    "name": "New arrivals",
    "sort": 100,
    "xmlId": null
  }
}

Error response example

422 — a required field was not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Required fields: name"
  }
}

Errors

HTTP Code Description
422 BITRIX_ERROR A required field was not passed — the message names the missing one (Required fields: iblockId or Required fields: name)
400 READONLY_FIELD id was passed in the body — this field is set by the system and is not accepted on creation
403 SCOPE_DENIED The key lacks the catalog scope
401 MISSING_API_KEY X-Api-Key was not passed

Full list of common API errors — Errors.

See also