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

Search pipelines

POST /v1/categories/:entityTypeId/search

Returns the pipelines of the specified CRM entity type from the request body rather than from the query string.

The same set of pipelines is served by GET /v1/categories/:entityTypeId.

Parameters

Parameter Type Required Description
entityTypeId (path) number yes CRM entity type identifier. Deals — 2, invoices — 31, smart processes — the value from GET /v1/smart-processes

Request fields (body)

Field Type Required Default Description
limit number no 50 Number of records, up to 5000
offset number no — How many pipelines to skip from the start of the list
select string[] no — Field selection: ["id", "name", "sort"]

Examples

In the examples entityTypeId equals 2 — deals. Substitute the type you need.

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/categories/2/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 5 }'

curl — OAuth app

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/categories/2/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 5 }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/categories/2/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ limit: 5 }),
})

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

JavaScript — OAuth app

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/categories/2/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ limit: 5 }),
})

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

Response fields

Field Type Description
success boolean Always true on success
data array Array of pipelines for the type
data[].id number Pipeline identifier. For the main deal pipeline it equals 0
data[].name string Pipeline name
data[].sort number Sort order
data[].entityTypeId number CRM entity type identifier, mirrors the path segment
data[].isDefault boolean Marks the main pipeline of the type
data[].originId string External identifier. Empty string for pipelines with no external binding
data[].originatorId string Source of the external binding. Empty string for pipelines with none
meta.total number Number of pipelines the type has
meta.hasMore boolean Whether pipelines remain beyond limit
meta.durationMs number Request duration in milliseconds

For the main pipeline the originId and originatorId keys are absent from the response — check that a key is present before reading it.

Response example

JSON 
{
  "success": true,
  "data": [
    { "id": 1, "name": "Newest", "sort": 100, "entityTypeId": 2, "isDefault": false, "originId": "", "originatorId": "" },
    { "id": 11, "name": "English", "sort": 200, "entityTypeId": 2, "isDefault": false, "originId": "", "originatorId": "" },
    { "id": 0, "name": "General", "sort": 300, "entityTypeId": 2, "isDefault": true },
    { "id": 3, "name": "Partners", "sort": 400, "entityTypeId": 2, "isDefault": false, "originId": "", "originatorId": "" },
    { "id": 9, "name": "Tenders", "sort": 500, "entityTypeId": 2, "isDefault": false, "originId": "", "originatorId": "" }
  ],
  "meta": {
    "total": 8,
    "hasMore": true,
    "durationMs": 1847
  }
}

Error response example

404 — no CRM type with this entityTypeId:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Smart process not found"
  }
}

Errors

HTTP Code Description
400 INVALID_DYNAMIC_PARAM entityTypeId in the path is not a positive integer
404 ENTITY_NOT_FOUND entityTypeId does not match an existing CRM type
422 BITRIX_ERROR The CRM type does not support pipelines. Quotes 7 have none
403 SCOPE_DENIED The API key lacks the crm scope
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 exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of general API errors — Errors.

Known specifics

The selection is not narrowed within a type. The only selection condition is the entityTypeId path segment. The filter and order fields are accepted without error but have no effect: a request carrying them returns the same set of pipelines in the same order as a request without them. Look up the pipeline you need in the returned array by name or id, and to get one known pipeline in full use GET /v1/categories/:entityTypeId/:id.

See also