Para agentes de IA: markdown de esta página — /docs-content-en/lists/lists.md índice de la documentación — /llms.txt

Los artículos de la documentación están disponibles actualmente en inglés.

Lists

Create lists, retrieve their metadata, change settings, and delete a list entirely. A list is a Bitrix24 infoblock addressed by a numeric IBLOCK_ID or a symbolic code.

Bitrix24 API: lists.* Scope: lists

List of lists

GET /v1/lists

Returns lists of the given infoblock type available to the current API key in the Bitrix24 account.

Parameters

Parameter Type Required Default Description
ParameteriblockTypeId (query) Typestring Requiredno Defaultlists DescriptionInfoblock type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — internal workflows
structure — company structure type (holds the built-in absence chart iblock absence)
Parametersort (query) Typestring Requiredno Default— DescriptionSorting in the format FIELD:direction. Fields: ID, IBLOCK_TYPE, NAME, CODE, SORT, TIMESTAMP_X. Direction asc or desc. Example: sort=NAME:asc
Parameterstart (query) Typenumber Requiredno Default0 DescriptionPage offset. For the next page, pass meta.next from the previous response
Parameteroffset (query) Typenumber Requiredno Default0 DescriptionAlias of start. Applied when start is not passed AND the value is greater than zero — zero addresses the same first page as no offset at all
ParametersocnetGroupId (query) Typenumber Requiredno Default— DescriptionWorkgroup identifier for the lists_socnet type

Start with start=0, then pass meta.next from the response as the next start. Stop when meta.next is absent or the number of collected lists reaches meta.total. The total number of lists of the given type is in meta.total.

Examples

curl — personal key

Terminal
curl https://vibecode.bitrix24.com/v1/lists \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal
curl https://vibecode.bitrix24.com/v1/lists \
  -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', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data, meta } = await res.json()
console.log('Lists:', meta.total)

JavaScript — OAuth application

javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/lists', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Response fields

Response fields are in Bitrix24 form: keys are uppercase with underscores, numeric values and flags (Y/N) come as strings, unset fields are null.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of lists
Fielddata[].ID Typestring DescriptionThe list identifier IBLOCK_ID
Fielddata[].NAME Typestring DescriptionList name
Fielddata[].IBLOCK_TYPE_ID Typestring DescriptionInfoblock type
Fielddata[].CODE Typestring DescriptionSymbolic code. Comes as null if the code is not set
Fielddata[].DESCRIPTION Typestring DescriptionList description
Fielddata[].ACTIVE Typestring DescriptionActive state: Y or N
Fielddata[].SORT Typestring DescriptionSort index
Fielddata[].TIMESTAMP_X Typestring DescriptionDate of last modification
Fielddata[].BIZPROC Typestring DescriptionWhether workflows are available: Y or N
Fielddata[].ELEMENTS_NAME Typestring DescriptionPlural name for the list's elements
Fielddata[].SECTIONS_NAME Typestring DescriptionPlural name for sections
Fieldmeta.total Typenumber DescriptionTotal number of lists of the given type
Fieldmeta.next Typenumber DescriptionOffset for the next page, as reported by Bitrix24. Pass it as start. Absent on the last page

The main fields are shown. The list object also contains other Bitrix24 infoblock metadata fields.

Response example

JSON
{
  "success": true,
  "data": [
    {
      "ID": "121",
      "NAME": "Task list",
      "IBLOCK_TYPE_ID": "lists",
      "CODE": "my_list",
      "DESCRIPTION": "A list for managing daily tasks",
      "ACTIVE": "Y",
      "SORT": "600",
      "TIMESTAMP_X": "12/11/2025 11:40:53 am",
      "BIZPROC": "N",
      "ELEMENTS_NAME": "Items",
      "SECTIONS_NAME": "Categories"
    },
    {
      "ID": "117",
      "NAME": "Projects",
      "IBLOCK_TYPE_ID": "lists",
      "CODE": "my_custom_list",
      "DESCRIPTION": "A list for tracking project tasks",
      "ACTIVE": "Y",
      "SORT": "500",
      "TIMESTAMP_X": "12/03/2025 10:34:00 am",
      "BIZPROC": "Y",
      "ELEMENTS_NAME": "Tasks",
      "SECTIONS_NAME": "Sections"
    }
  ],
  "meta": { "total": 11 }
}

Error response example

400 — invalid infoblock type:

JSON
{
  "success": false,
  "error": {
    "code": "INVALID_IBLOCK_TYPE",
    "message": "iblockTypeId must be one of: lists, bitrix_processes, lists_socnet, structure (default: lists)."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_IBLOCK_TYPE DescriptioniblockTypeId is not in the allowed set
HTTP400 CodeINVALID_SORT_FIELD DescriptionThe sort field or direction is not supported
HTTP400 CodeINVALID_PARAMS Descriptionstart or offset is not a non-negative integer. Previously, such a value was silently ignored and the wrong page was returned
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
HTTP400 CodeUNSUPPORTED_FILTER DescriptionA filter parameter was passed, and this endpoint has none. The error text names what to use instead

For the full list of common API errors, see Errors.

Known specifics

Not every list has a symbolic code. The CODE field comes as null if no code was set. Such a list is addressed in single-list operations only by the numeric IBLOCK_ID.

See also