For AI agents: markdown of this page — /docs-content-en/entities/catalog-documents/list.md documentation index — /llms.txt

List inventory documents

GET /v1/catalog-documents

Returns the Bitrix24 account's inventory documents with filtering, sorting and pagination. Use it to find documents of a given type or conducting status before working with their items.

Parameters

Parameter	Type	Default	Description
Parameter`filter` (query)	Typeobject	Default—	DescriptionFiltering by the fields of `GET /v1/catalog-documents/fields`. Filtering syntax. Example: `?filter[docType]=S&filter[status]=N`
Parameter`select` (query)	Typestring	Default—	DescriptionComma-separated fields in the response: `?select=id,title,docType,status`. Field names come from `GET /v1/catalog-documents/fields`
Parameter`order` (query)	Typeobject	Default—	DescriptionSorting: `?order[id]=desc`. Short form — `?sort=-id`, where a leading minus means descending. Without the parameter, documents are sorted by `id` ascending
Parameter`limit` (query)	Typenumber	Default`50`	DescriptionNumber of records, from 1 to 5000. A value above 5000 is capped at 5000, a non-numeric value is replaced with `50`
Parameter`offset` (query)	Typenumber	Default`0`	DescriptionHow many records to skip. The offset counts records: `offset=7` starts the output at the eighth document
Parameter`withTotal` (query)	Typestring	Default—	Description`true` or `false`. The exact value `false` omits `meta.total`, but Bitrix24 still counts the documents, so this option does not make the request cheaper. Without it or with `true`, the existing counted behavior applies

Pagination. When limit > 50, Vibecode assembles the response from several pages automatically. To walk the whole result set, increase offset by limit while meta.hasMore is true.

Examples

curl — personal key

Terminal

curl "https://vibecode.bitrix24.com/v1/catalog-documents?limit=2" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal

curl "https://vibecode.bitrix24.com/v1/catalog-documents?limit=2" \
  -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/catalog-documents?limit=2', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Documents matching the filter: ${meta.total}`)

JavaScript — OAuth application

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-documents?limit=2', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Response fields

Field	Type	Description
Field`success`	Typeboolean	DescriptionAlways `true` on success
Field`data`	Typearray	DescriptionArray of inventory documents (all fields — see Inventory document fields)
Field`meta.total`	Typenumber	DescriptionTotal number of documents matching the filter. Optional: absent when `withTotal=false`
Field`meta.hasMore`	Typeboolean	DescriptionWhether there are more documents beyond `limit`
Field`meta.warnings`	Typearray	DescriptionRequest warnings. Returned when `select` contains a name that is not among the document fields: code `UNKNOWN_SELECT_FIELD`, the name in the `field` field. The request still runs and the other fields are returned

The document's products and warehouses are not included in the response — the item list with filter[docId] returns them.

Response example

JSON

{
  "success": true,
  "data": [
    {
      "commentary": null,
      "createdBy": 1,
      "currency": "USD",
      "dateCreate": "2025-01-10T11:49:37.000Z",
      "dateDocument": null,
      "dateModify": "2025-01-10T11:49:59.000Z",
      "dateStatus": "2025-01-10T11:49:59.000Z",
      "docNumber": null,
      "docType": "S",
      "id": 1,
      "modifiedBy": 1,
      "responsibleId": 1,
      "siteId": "s1",
      "status": "Y",
      "statusBy": 1,
      "title": "Stock adjustment #2",
      "total": 275000
    },
    {
      "commentary": null,
      "createdBy": 1,
      "currency": "USD",
      "dateCreate": "2025-06-27T05:00:47.000Z",
      "dateDocument": "2025-06-27T05:00:47.000Z",
      "dateModify": "2025-06-27T05:00:47.000Z",
      "dateStatus": "2025-06-27T05:00:47.000Z",
      "docNumber": null,
      "docType": "A",
      "id": 3,
      "modifiedBy": 1,
      "responsibleId": 1,
      "siteId": "s1",
      "status": "Y",
      "statusBy": 1,
      "title": "Goods receipt #12",
      "total": 5940
    }
  ],
  "meta": {
    "total": 143,
    "hasMore": true
  }
}

Error response example

400 — filter by a field the document does not have: