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
iblockTypeId (query) string no lists Infoblock type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — internal workflows
structure — company-structure type (stock absence-calendar iblock absence)
sort (query) string no — Sorting in the format FIELD:direction. Fields: ID, IBLOCK_TYPE, NAME, CODE, SORT, TIMESTAMP_X. Direction asc or desc. Example: sort=NAME:asc
start (query) number no 0 Offset for paginated retrieval
offset (query) number no 0 Alias 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
socnetGroupId (query) number no — Workgroup identifier for the lists_socnet type

Bitrix24 returns up to 50 lists per call. For the next page, increase start by 50. 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
success boolean Always true on success
data array Array of lists
data[].ID string The list identifier IBLOCK_ID
data[].NAME string List name
data[].IBLOCK_TYPE_ID string Infoblock type
data[].CODE string Symbolic code. Comes as null if the code is not set
data[].DESCRIPTION string List description
data[].ACTIVE string Active state: Y or N
data[].SORT string Sort index
data[].TIMESTAMP_X string Date of last modification
data[].BIZPROC string Whether workflows are available: Y or N
data[].ELEMENTS_NAME string Plural name for the list's elements
data[].SECTIONS_NAME string Plural name for sections
meta.total number Total number of lists of the given type

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
400 INVALID_IBLOCK_TYPE iblockTypeId is not in the allowed set
400 INVALID_SORT_FIELD The sort field or direction is not supported
400 INVALID_PARAMS start or offset is not a non-negative integer. Such a value used to be dropped silently, and the page served was not the one asked for
409 LISTS_MODULE_NOT_ENABLED The Lists module is not enabled on the portal
403 SCOPE_DENIED The API key lacks the lists scope
401 TOKEN_MISSING The API key has no configured tokens
400 UNSUPPORTED_FILTER A filter parameter was passed, and this endpoint has none. The error text names what to use instead

The full list of common API errors — 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