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

Update list

PATCH /v1/lists/:iblockId

Changes the settings of an existing list. Editable fields are passed inside the fields object in Bitrix24 format. The list is addressed by numeric IBLOCK_ID or symbolic code in the path.

Parameters

Parameter Type Required Description
iblockId (path) string yes Numeric IBLOCK_ID or symbolic code of the list. Use ID or CODE from the List lists response

Request fields (body)

Core settings: name (fields.NAME), description (fields.DESCRIPTION), and sort index (fields.SORT).

Field Type Required Description
fields object yes List settings to update. Keys are uppercase. Settings you omit retain their current values
fields.NAME string no List name. An empty string is not allowed
fields.DESCRIPTION string no List description
fields.SORT number no Sort index in the list of lists
fields.ACTIVE string no Active status: Y or N. An inactive list cannot be retrieved through Get list
fields.BIZPROC string no Enable workflows: Y or N
fields.PICTURE string[] no List image. An array of two strings: the file name and its Base64-encoded contents, for example ["image.png", "BASE64_CONTENT"]
iblockTypeId string no Infoblock type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — internal workflows
structure — company structure type (contains the built-in absence calendar infoblock absence)
socnetGroupId number no ID of the workgroup containing the list. For a workgroup list, pass iblockTypeId: "lists_socnet" and the ID of that workgroup. Use the id field from the List workgroups response. Omit this parameter for a regular list
messages object no Labels for elements, sections, and their actions in the list interface. Supported fields are listed below. The SECTION_NAME field is ignored
messages.ELEMENTS_NAME string no Plural label for elements, for example Requests
messages.ELEMENT_NAME string no Singular label for an element, for example Request
messages.ELEMENT_ADD string no Label for the action that adds an element
messages.ELEMENT_EDIT string no Label for the action that edits an element
messages.ELEMENT_DELETE string no Label for the action that deletes an element
messages.SECTIONS_NAME string no Plural label for sections, for example Categories
messages.SECTION_ADD string no Label for the action that adds a section
messages.SECTION_EDIT string no Label for the action that edits a section
messages.SECTION_DELETE string no Label for the action that deletes a section
rights object no List access permissions. Each key is a user or department code containing its ID, and each value is a letter code for a permission. Codes, ID sources, and restrictions on changing permissions are described in the RIGHTS parameter in the Bitrix24 reference

Examples

curl — personal key

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/lists/23 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "NAME": "Request registry for the quarter",
      "SORT": 200
    }
  }'

curl — OAuth application

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/lists/23 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "NAME": "Request registry for the quarter",
      "SORT": 200
    }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/23', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      NAME: 'Request registry for the quarter',
      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', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      NAME: 'Request registry for the quarter',
      SORT: 200,
    },
  }),
})

const { data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data object Request result
data.updated boolean true if the request completed successfully. Does not guarantee that any values changed

Response example

HTTP 200 OK:

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

Error response example

400 — a required parameter is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "`fields` is required and must be an object."
  }
}

Errors

HTTP Code Description
400 MISSING_REQUIRED_FIELDS The fields object is missing
400 INVALID_IBLOCK_TYPE iblockTypeId is not one of lists, lists_socnet, bitrix_processes, structure
403 BITRIX_ACCESS_DENIED Bitrix24 denied access to the list
404 LIST_NOT_FOUND Bitrix24 could not find a list with the specified ID or code
422 BITRIX_ERROR An empty list name was passed in fields.NAME. Bitrix24 returns b24Code: ERROR_UPDATE_IBLOCK
409 LISTS_MODULE_NOT_ENABLED The Lists module is not enabled on the Bitrix24 portal
403 WRITE_BLOCKED_READONLY_KEY The key operates in read-only mode
403 SCOPE_DENIED The key lacks the lists scope
401 TOKEN_MISSING The key has no access tokens configured

Full list of common API errors — Errors.

Known specifics

Updates without changes. An empty fields object and unknown fields inside it, such as ID, do not cause an error. The response contains data.updated: true, even though the settings do not change. Pass only the fields listed in the table. You can check the saved values through Get list.

See also