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

Search inventory documents

POST /v1/catalog-documents/search

Searches inventory documents using conditions specified in the request body. Use this endpoint for filters with operators and date-range queries. For simpler queries, use the list endpoint with a filter in the query string.

Request fields (body)

Field Type Default Description
Fieldfilter Typeobject Default— DescriptionFilter by fields listed by GET /v1/catalog-documents/fields.
Filtering syntax. Example: {"docType": {"$in": ["A", "S"]}, "status": "N"}
Fieldselect Typestring[] Default— DescriptionFields in the response: ["id", "title", "status"]. A comma-separated string "id,title,status" is also accepted. Names come from GET /v1/catalog-documents/fields
Fieldsort Typestring | object | string[] Default— DescriptionSorting: "-id" — descending, "id" — ascending, or an object {"id": "desc"}. Also accepted under the name order. If omitted, documents are sorted by id ascending
Fieldlimit Typenumber Default50 DescriptionNumber of records, from 1 to 5000. A value above 5000 is capped at 5000
Fieldoffset Typenumber Default0 DescriptionHow many records to skip. A value above zero combined with window splitting is rejected — see UNSTABLE_OFFSET_PAGINATION in the "Errors" section
FieldautoWindow Typeboolean Defaulttrue DescriptionSplit the search into weekly windows when filtering by a date range longer than 14 days. false disables splitting

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-documents/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "docType": "S", "status": "N" },
    "select": ["id", "title", "docType", "status", "total"],
    "sort": "-id",
    "limit": 2
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-documents/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "docType": "S", "status": "N" },
    "select": ["id", "title", "docType", "status", "total"],
    "sort": "-id",
    "limit": 2
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-documents/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { docType: 'S', status: 'N' },
    select: ['id', 'title', 'docType', 'status', 'total'],
    sort: '-id',
    limit: 2,
  }),
})

const { success, data, meta } = await res.json()
console.log(`Unposted stock adjustments returned: ${data.length}`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-documents/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { docType: 'S', status: 'N' },
    select: ['id', 'title', 'docType', 'status', 'total'],
    sort: '-id',
    limit: 2,
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of inventory documents (all fields — see Inventory document fields). If select is set, only the listed fields are returned
Fieldmeta.total Typenumber DescriptionThe exact number of documents matching the filter, when known. Omitted when the search across time windows is incomplete
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more documents beyond limit
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds
Fieldmeta.autoWindowed Typeboolean Descriptiontrue if the search was split into weekly windows. Returned only when splitting occurs
Fieldmeta.windowCount Typenumber DescriptionNumber of windows. Returned with autoWindowed: true
Fieldmeta.batchWaves Typenumber DescriptionNumber of waves of parallel requests across windows. Returned with autoWindowed: true
Fieldmeta.warnings Typearray DescriptionRequest warnings. Returned when select contains an unknown document field name. The warning has code UNKNOWN_SELECT_FIELD and specifies the unknown name in field. The other fields are returned

Use meta.hasMore to determine whether there are more results: a page with exactly limit records can still be the last page.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 299,
      "title": "Stock adjustment — warehouse 11",
      "docType": "S",
      "status": "N",
      "total": null
    },
    {
      "id": 151,
      "title": "stock adjustment 33",
      "docType": "S",
      "status": "N",
      "total": null
    }
  ],
  "meta": {
    "total": 36,
    "hasMore": true,
    "durationMs": 103
  }
}

When filtering by a date range longer than 14 days, for example {"filter": {">=dateCreate": "2025-01-01T00:00:00Z", "<dateCreate": "2025-07-01T00:00:00Z"}}, meta also contains autoWindowed, windowCount and batchWaves:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Stock adjustment #2",
      "dateCreate": "2025-01-10T11:49:37.000Z"
    },
    {
      "id": 3,
      "title": "Goods receipt #12",
      "dateCreate": "2025-06-27T05:00:47.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false,
    "autoWindowed": true,
    "windowCount": 26,
    "batchWaves": 1,
    "durationMs": 219
  }
}

In the example above, all windows were read successfully and duplicates removed, so meta.total is the exact number of matches. The field is omitted when the search stops early at limit or a window returns an incomplete result. The API does not make additional requests solely to obtain a count. data.length is the number of returned documents; meta.hasMore indicates whether more results are available.

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
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionFilter by a field the document does not have. The message lists the allowed fields
HTTP400 CodeUNKNOWN_SORT_FIELD DescriptionSorting by a field the document does not have. The message lists the allowed fields
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionThe filter contains an unsupported operator. The message lists the supported ones
HTTP400 CodeINVALID_SORT_TYPE Descriptionsort is not a string, an object or an array of strings, for example a number
HTTP400 CodeINVALID_SELECT_TYPE Descriptionselect is not a string or an array of strings, for example a number
HTTP400 CodeINVALID_LIMIT Descriptionlimit is not a number, for example "abc"
HTTP400 CodeINVALID_REQUEST DescriptionThe request body is not a JSON object, for example an array
HTTP400 CodeUNSTABLE_OFFSET_PAGINATION Descriptionoffset is greater than zero and the filter covers a date range longer than 14 days. Fetch everything in one request with limit up to 5000, or pass autoWindow: false with "sort": "id", or split the date range into parts yourself
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the catalog scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe provided API key was not found
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys for the portal share this 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.

See also