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, defaultlists_socnet — workgroup listsbitrix_processes — internal workflowsstructure — 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
curl https://vibecode.bitrix24.com/v1/lists \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth application
curl https://vibecode.bitrix24.com/v1/lists \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
JavaScript — personal key
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
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
{
"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:
{
"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.