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

Update a pipeline

PATCH /v1/categories/:entityTypeId/:id

Updates the fields of an existing pipeline of the specified CRM entity type. Pass only the fields being changed, flat at the root of the JSON — without a fields wrapper.

Parameters

Parameter Type Required Description
entityTypeId (path) number yes CRM entity type ID. 2 for deals, 31 for invoices, for a smart process — the value from GET /v1/smart-processes
id (path) number yes Pipeline identifier

Fields to update (body)

Field Bitrix24 Type Description
name name string Pipeline name
sort sort number Sort order among pipelines of the type

Examples

In the examples entityTypeId = 2 (deals), id = 15 — replace with your values.

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/categories/2/15" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partners pipeline — updated",
    "sort": 700
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/categories/2/15" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partners pipeline — updated",
    "sort": 700
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/categories/2/15', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Partners pipeline — updated',
    sort: 700,
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/categories/2/15', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Partners pipeline — updated',
    sort: 700,
  }),
})

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

Response fields

Returns the full pipeline object with the applied changes.

Field Type Description
id number Pipeline identifier
entityTypeId number CRM entity type ID, mirrors the path parameter
name string Pipeline name
sort number Sort order
isDefault boolean Whether this is the type's main pipeline
originId string External source identifier, empty string when absent
originatorId string External system identifier, empty string when absent

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 15,
    "name": "Partners pipeline — updated",
    "sort": 700,
    "entityTypeId": 2,
    "isDefault": false,
    "originId": "",
    "originatorId": ""
  }
}

Error response example

404 — pipeline with the specified id not found:

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

Errors

HTTP Code Description
400 READONLY_FIELD A read-only field was sent — code or isDefault. The message names the specific field
404 ENTITY_NOT_FOUND Pipeline with the specified id not found — message Item not found
404 ENTITY_NOT_FOUND entityTypeId does not match an existing type — message Smart process not found
403 SCOPE_DENIED API key lacks the crm scope
401 TOKEN_MISSING API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

The code and isDefault fields are read-only. Sending code or isDefault in the request body returns 400 READONLY_FIELD — remove these fields from your request. The type's main pipeline is assigned in the Bitrix24 interface.

See also