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

List pipelines

GET /v1/categories/:entityTypeId

Returns the pipelines of the specified CRM entity type.

Parameters

Parameter Type Description
entityTypeId (path) number CRM entity type ID. Deals — 2, invoices — 31, smart processes — from GET /v1/smart-processes
select string[] Which fields to return. By default all fields are returned
limit number How many pipelines to return. 50 by default, 5000 maximum
offset number How many pipelines to skip from the start of the list

Examples

In the examples entityTypeId = 2 (deals) — replace with the type you need.

curl — personal key

Terminal 
curl -X GET https://vibecode.bitrix24.com/v1/categories/2 \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth app

Terminal 
curl -X GET https://vibecode.bitrix24.com/v1/categories/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/categories/2', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data } = await res.json()
console.log(`Pipelines: ${data.length}`)

JavaScript — OAuth app

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

const { success, data } = 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 ID. For deals the main pipeline has ID 0
data[].name string Pipeline name
data[].sort number Sort order
data[].entityTypeId number CRM entity type ID, mirrors the path parameter
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 How many pipelines the type has in total — independent of limit and offset
meta.hasMore boolean Whether pipelines remain beyond the current page

For the main deal pipeline (id 0) the originId and originatorId fields are absent from the response.

Pipeline stages are requested separately: GET /v1/statuses?filter[entityId]=DEAL_STAGE_{id}.

Response example

The response always contains meta. Additional deal pipelines have originId and originatorId; the main pipeline (id 0) does not:

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 }
  ],
  "meta": { "total": 3, "hasMore": false }
}

Smart process pipelines have a shorter set of fields:

JSON 
{
  "success": true,
  "data": [
    { "id": 3, "name": "General", "sort": 500, "entityTypeId": 174, "isDefault": true },
    { "id": 23, "name": "Extra pipeline", "sort": 510, "entityTypeId": 174, "isDefault": false }
  ],
  "meta": { "total": 2, "hasMore": false }
}

Error response example

404 — type not found:

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

Errors

HTTP Code Description
404 ENTITY_NOT_FOUND entityTypeId does not match an existing CRM type
422 BITRIX_ERROR The CRM type does not support pipelines. Quotes (type 7) have no pipelines
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

filter and order are accepted but have no effect. A request carrying them returns 200 and the same set of pipelines in the same order as a request without them. Sorting follows the sort field. Filter by name on the client side: data.filter(c => c.name === 'Sales').

Paging is relative to the full list for the type. meta.total reports how many pipelines the type has in total and does not change with limit or offset — walk the list until meta.hasMore is false.

See also