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

Search catalog products

POST /v1/catalog-products/search

Search catalog products using the conditions passed in the request body.

Unlike GET /v1/catalog-products, the filter, select, sort, limit, and offset parameters are passed in the JSON body rather than in the query string — conditions across several fields are expressed as a nested structure. Like the list, search requires filter.iblockId — without this field the request returns 400. The response format is the same as for the list.

The dateCreate, timestampX, dateActiveFrom, and dateActiveTo fields are not accepted in filter: the request returns 400 UNKNOWN_FILTER_FIELD before calling Bitrix24. These dates remain available in select and responses.

Request fields (body)

Parameter Type Required Default Description
Parameterfilter Typeobject Requiredyes Default— DescriptionFiltering conditions. The iblockId key is required — the catalog ID from GET /v1/catalogs.
Filtering syntax. Example: { "iblockId": 25, "active": true }
Parameterselect Typestring[] Requiredno Default— DescriptionField selection: ["iblockId", "id", "name"]. If the parameter is passed, it must include iblockId. Without select, the response carries a reduced set of fields: the symbolic code, dimensions, text fields, and several other fields are returned only when explicitly included in select — Catalog product fields lists which ones. A custom catalog property is not part of the field reference and is requested by its own name: ["iblockId", "id", "name", "property295"]
Parametersort Typestring Requiredno Default— DescriptionSort field. The - prefix means descending: "-id"
Parameterlimit Typenumber Requiredno Default50 DescriptionNumber of records (up to 5000)
Parameteroffset Typenumber Requiredno Default0 DescriptionOffset from the start of the result set

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-products/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "iblockId": 25, "active": true },
    "limit": 3
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-products/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "iblockId": 25, "active": true },
    "limit": 3
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-products/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { iblockId: 25, active: true },
    limit: 3,
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-products/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { iblockId: 25, active: true },
    limit: 3,
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of products. For the fields of each item, see Catalog product fields
Fieldmeta.total Typenumber DescriptionTotal number of records matching the filter
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds

The meta fields sit next to data, not inside it. Paginate using meta.hasMore: a data length equal to limit does not rule out the last page.

The card URL of any product from the data array is built from its iblockId and id:

https://<portal>.bitrix24.com/shop/catalog/<iblockId>/product/<id>/

<portal> is the Bitrix24 portal domain. Access is restricted by the employee's permissions in Bitrix24.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 6975,
      "iblockId": 25,
      "iblockSectionId": null,
      "name": "Delivery service",
      "active": true,
      "available": true,
      "barcodeMulti": false,
      "bundle": false,
      "canBuyZero": true,
      "measure": 9,
      "purchasingCurrency": null,
      "purchasingPrice": null,
      "quantity": 1,
      "quantityTrace": false,
      "subscribe": false,
      "vatIncluded": false,
      "weight": null,
      "withoutOrder": false,
      "dateCreate": "2025-12-02T09:14:05.000Z",
      "timestampX": "2025-12-02T09:14:05.000Z"
    }
  ],
  "meta": {
    "total": 19,
    "hasMore": true,
    "durationMs": 540
  }
}

Error response example

400 — the required filter was not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FILTER",
    "message": "POST /v1/catalog-products/search requires filter fields: iblockId. Example body: { \"filter\": {\"iblockId\":\"...\"} }"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FILTER DescriptionThe required filter.iblockId filter was not passed. The request is rejected before Bitrix24 is called — the message contains the name of the missing field and a request body example
HTTP422 CodeBITRIX_ERROR Descriptionselect was passed without iblockId (Required select fields: iblockId)
HTTP400 CodeUNKNOWN_SELECT_FIELD Descriptionselect contains a name the product does not have. The message lists the allowed names after the word Available. Custom properties of the form propertyNNN are accepted and are not part of that list
HTTP400 CodeSELECT_FIELD_NOT_RETURNED Descriptionselect contains a name that Catalog product fields shows with notReturned: true — iblockSection, for example. Drop it from select
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionUnknown filter field or a date field: dateCreate, timestampX, dateActiveFrom, dateActiveTo. The message contains the list of available fields
HTTP400 CodeUNKNOWN_SORT_FIELD DescriptionSorting by a field the product does not have. The message contains the list of available fields
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the catalog scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of common API errors, see Errors.

See also