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

Update a section

PATCH /v1/lists/:iblockId/sections/:sectionId

Updates the fields of an existing list section. Pass the fields to change inside the fields object using the Bitrix24 field format.

Parameters

Parameter Type Required Description
ParameteriblockId (path) Typestring Requiredyes DescriptionList ID or symbolic code. Use the ID or CODE field from List of lists
ParametersectionId (path) Typenumber Requiredyes DescriptionSection ID, a positive integer from the ID field returned by List sections

Request body fields

Field Type Required Description
Fieldfields Typeobject Requiredyes DescriptionSection fields to change. Keys are uppercase with underscores
Fieldfields.NAME Typestring Requiredyes DescriptionNon-empty section name. Include it even when changing other fields. The current name is in the NAME field returned by Get section
Fieldfields.CODE Typestring Requiredno DescriptionSection symbolic code
Fieldfields.SORT Typenumber Requiredno DescriptionSort index
Fieldfields.ACTIVE Typestring Requiredno DescriptionWhether the section is active: Y or N
Fieldfields.IBLOCK_SECTION_ID Typenumber Requiredno DescriptionParent section ID from the ID field returned by List sections. 0 moves the section to the root of the list
Fieldfields.XML_ID Typestring Requiredno DescriptionExternal section ID for data exchange
Fieldfields.EXTERNAL_ID Typestring Requiredno DescriptionAlias for XML_ID
Fieldfields.DESCRIPTION Typestring Requiredno DescriptionSection description. An empty string clears the description
Fieldfields.DESCRIPTION_TYPE Typestring Requiredno DescriptionDescription format: text or html
Fieldfields.PICTURE Typearray Requiredno DescriptionSection image: an array ["filename.png", "BASE64_DATA"]. The second element contains the file content encoded in Base64
FieldiblockTypeId Typestring Requiredno DescriptionInfoblock type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — service workflows
structure — company-structure type (contains the built-in absence-calendar infoblock absence)
FieldsocnetGroupId Typenumber Requiredno DescriptionID of the workgroup that contains the list. For a workgroup list, pass iblockTypeId: "lists_socnet" and the group ID from the id field returned by List workgroups. Omit it for a regular list

Pass the fields to change and fields.NAME. All other section settings keep their current values.

Examples

curl — personal key

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/lists/23/sections/215 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "NAME": "North-Western region",
      "SORT": 200
    }
  }'

curl — OAuth application

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/lists/23/sections/215 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "NAME": "North-Western region",
      "SORT": 200
    }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/23/sections/215', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      NAME: 'North-Western region',
      SORT: 200,
    },
  }),
})

const { data } = await res.json()
console.log(data.updated)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/23/sections/215', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      NAME: 'North-Western region',
      SORT: 200,
    },
  }),
})

const { data } = await res.json()

Response fields

HTTP 200. To retrieve the updated fields, call Get section.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionUpdate result
Fielddata.updated Typeboolean Descriptiontrue on successful update

Response example

JSON 
{
  "success": true,
  "data": {
    "updated": true
  }
}

Error response example

422 — the section name fields.NAME is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Required parameter \"NAME\" is missing",
    "b24Code": "ERROR_REQUIRED_PARAMETERS_MISSING"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionsectionId is not a positive integer
HTTP400 CodeMISSING_REQUIRED_FIELDS Descriptionfields is missing or is not an object
HTTP400 CodeINVALID_IBLOCK_TYPE DescriptioniblockTypeId is not one of lists, lists_socnet, bitrix_processes, structure
HTTP422 CodeBITRIX_ERROR Descriptionfields.NAME is missing, including when fields is empty. The response contains b24Code: "ERROR_REQUIRED_PARAMETERS_MISSING"
HTTP422 CodeBITRIX_ERROR Descriptionfields.NAME is an empty string. The response contains b24Code: "ERROR_UPDATE_SECTION"
HTTP422 CodeBITRIX_ERROR DescriptionThe section or list does not exist. The response contains b24Code: "ERROR_SECTION_NOT_FOUND"
HTTP422 CodeBITRIX_ERROR DescriptionThe list type does not match the request parameters, for example when socnetGroupId is passed for a regular list. The response contains b24Code: "0"
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo permission to access the list or section
HTTP409 CodeLISTS_MODULE_NOT_ENABLED DescriptionThe Lists module is not enabled on the Bitrix24 portal
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key operates in read-only mode
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the lists scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no access tokens configured

Full list of common API errors — Errors.

See also