## 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 |
|----------|-----|-----------|---------|
| `filter` (query) | object | — | Filtering by the fields of `GET /v1/catalog-documents/fields`.<br>[Filtering syntax](/docs/filtering). Example: `?filter[docType]=S&filter[status]=N` |
| `select` (query) | string | — | Comma-separated fields in the response: `?select=id,title,docType,status`. Field names come from [`GET /v1/catalog-documents/fields`](/docs/entities/catalog-documents/fields) |
| `order` (query) | object | — | Sorting: `?order[id]=desc`. Short form — `?sort=-id`, where a leading minus means descending. Without the parameter, documents are sorted by `id` ascending |
| `limit` (query) | number | `50` | Number of records, from 1 to 5000. A value above 5000 is capped at 5000, a non-numeric value is replaced with `50` |
| `offset` (query) | number | `0` | How many records to skip. The offset counts records: `offset=7` starts the output at the eighth document |
| `withTotal` (query) | string | — | `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

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

### curl — OAuth application

```bash
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 |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of inventory documents (all fields — see [Inventory document fields](/docs/entities/catalog-documents/fields)) |
| `meta.total` | number | Total number of documents matching the filter. Optional: absent when `withTotal=false` |
| `meta.hasMore` | boolean | Whether there are more documents beyond `limit` |
| `meta.warnings` | array | Request 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](/docs/entities/catalog-document-elements/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:

```json
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'bogus' for entity 'catalog-documents'. Available: id, docType, currency, responsibleId, status, dateStatus, createdBy, dateCreate, title, docNumber, commentary, dateDocument, siteId, total, modifiedBy, statusBy, dateModify"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `UNKNOWN_FILTER_FIELD` | Filter by a field the document does not have. The message lists the allowed fields |
| 400 | `UNKNOWN_SORT_FIELD` | Sorting by a field the document does not have. The message lists the allowed fields |
| 400 | `INVALID_FILTER` | The `filter` value is not recognized: pass it in bracket notation `?filter[docType]=S` or as a JSON object `?filter={"docType":"S"}`. Both notations in one request are also rejected |
| 400 | `INVALID_FILTER_OPERATOR` | The filter contains an unsupported operator. The message lists the supported ones |
| 403 | `SCOPE_DENIED` | The API key does not have the `catalog` scope |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The API key passed was not found |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The effective value is in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header |

Full list of common API errors — [Errors](/docs/errors).

## See also

- [Get an inventory document](/docs/entities/catalog-documents/get)
- [Search inventory documents](/docs/entities/catalog-documents/search)
- [Inventory document fields](/docs/entities/catalog-documents/fields)
- [List document items](/docs/entities/catalog-document-elements/list)
- [Inventory documents](/docs/entities/catalog-documents)
- [Filtering syntax](/docs/filtering)
- [Limits and optimization](/docs/optimization)