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

Update a flow

PATCH /v1/tasks/flows/:flowId

Changes the settings of an existing task flow by its ID.

Parameters

Parameter Type Required Description
ParameterflowId (path) Typenumber Requiredyes DescriptionFlow ID, a positive integer. List: GET /v1/tasks/flows

Request fields (body)

Field Type Required Description
FieldflowData Typeobject Requiredyes DescriptionNew values of the flow fields. Sent to Bitrix24 unchanged; the flow ID is taken from the path
FieldflowData.id Typenumber Requiredno DescriptionFlow ID. If passed, it must be a number equal to flowId from the path
FieldflowData.name Typestring Requiredno DescriptionFlow name. It must not match the name of another flow in the Bitrix24 account
FieldflowData.plannedCompletionTime Typenumber Requiredno DescriptionTime to complete a task, in seconds, for example 86400 — one day
FieldflowData.distributionType Typestring Requiredno DescriptionHow tasks reach assignees: manually — a moderator assigns them, queue — in turn among the employees in responsibleList, himself — employees take tasks themselves
FieldflowData.responsibleList Typearray Requiredno DescriptionWho receives the tasks: an array of pairs like ["user", "3"], where the second element is the employee ID as a string. With manually, the list holds the flow moderator. List: GET /v1/users
FieldflowData.groupId Typenumber Requiredno DescriptionID of the workgroup to bind the flow to. List: GET /v1/workgroups
FieldflowData.ownerId Typenumber Requiredno DescriptionFlow administrator ID. List: GET /v1/users
FieldflowData.taskCreators Typearray Requiredno DescriptionWho can submit tasks to the flow: an array of pairs. [["meta-user", "all-users"]] — all employees
FieldflowData.description Typestring Requiredno DescriptionFlow description. If not passed, reset to an empty string
FieldflowData.matchWorkTime Typenumber Requiredno Description1 — weekends and holidays are skipped when the deadline is calculated, 0 — they are counted. If not passed, reset to 1
FieldflowData.responsibleCanChangeDeadline Typenumber Requiredno Description1 — the assignee can change the task deadline, 0 — cannot. If not passed, reset to 1
FieldflowData.taskControl Typenumber Requiredno Description1 — a completed task goes to its creator for review, 0 — no review. If not passed, reset to 0
FieldflowData.notifyAtHalfTime Typenumber Requiredno Description1 — remind the assignee halfway to the deadline, 0 — no reminder. If not passed, reset to 0
FieldflowData.notifyOnQueueOverflow Typenumber Requiredno DescriptionNotify the flow administrator when the number of tasks in the queue exceeds this number. If not passed, reset to null — no notification
FieldflowData.notifyOnTasksInProgressOverflow Typenumber Requiredno DescriptionNotify the flow administrator when the number of tasks in progress exceeds this number. If not passed, reset to null — no notification
FieldflowData.notifyWhenEfficiencyDecreases Typenumber Requiredno DescriptionNotify the flow administrator when efficiency drops below this value, in percent. If not passed, reset to null — no notification
FieldanalyticsParams Typeobject Requiredno DescriptionInternal Bitrix24 analytics tags. They do not affect the flow

The body must not contain keys other than flowData and analyticsParams. Flags are passed as the numbers 1 and 0 and come back in the response as true and false.

Important: the fields marked "If not passed, reset to …" are reset on every call, including a call with "flowData": {}. Other fields missing from flowData keep their current values. To change one setting without losing the others, read the flow with GET /v1/tasks/flows/:flowId and pass the resettable fields with their current values.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/tasks/flows/20" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flowData": {
      "name": "Website request processing",
      "description": "Customer requests from the website",
      "plannedCompletionTime": 172800
    }
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/tasks/flows/20" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flowData": {
      "name": "Website request processing",
      "description": "Customer requests from the website",
      "plannedCompletionTime": 172800
    }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/flows/20', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    flowData: {
      name: 'Website request processing',
      description: 'Customer requests from the website',
      plannedCompletionTime: 172800,
    },
  }),
})

const { success, data } = await res.json()
if (success) {
  console.log('New name:', data.name)
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/flows/20', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    flowData: {
      name: 'Website request processing',
      description: 'Customer requests from the website',
      plannedCompletionTime: 172800,
    },
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionThe flow after the change. The set of fields is the same as in the GET /v1/tasks/flows/:flowId response
Fielddata.id Typenumber DescriptionFlow ID
Fielddata.taskCreators Typearray DescriptionAn empty array, even if taskCreators was passed in the request or set earlier. The saved value is in GET /v1/tasks/flows/:flowId
Fielddata.team Typearray DescriptionAn empty array. The flow team is in GET /v1/tasks/flows/:flowId

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 20,
    "creatorId": 1,
    "ownerId": 1,
    "groupId": 178,
    "templateId": 0,
    "efficiency": 100,
    "active": true,
    "plannedCompletionTime": 172800,
    "activity": "2026-10-20T00:23:04+00:00",
    "name": "Website request processing",
    "description": "Customer requests from the website",
    "distributionType": "queue",
    "responsibleList": [
      ["user", "3"]
    ],
    "demo": false,
    "responsibleCanChangeDeadline": true,
    "matchWorkTime": true,
    "matchSchedule": false,
    "taskControl": false,
    "notifyAtHalfTime": false,
    "notifyOnQueueOverflow": null,
    "notifyOnTasksInProgressOverflow": null,
    "notifyWhenEfficiencyDecreases": null,
    "taskCreators": [],
    "team": [],
    "trialFeatureEnabled": false
  }
}

Error response example

422 — no flow with this flowId exists:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Unknown error. [Flow: 267]",
    "b24Code": "0"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionflowId is not a positive integer. Message: flowId must be a positive safe integer
HTTP400 CodeINVALID_PARAMS DescriptionThe body is not an object or contains keys other than flowData and analyticsParams. Message: body must be an object with supported fields only
HTTP400 CodeINVALID_PARAMS DescriptionflowData is not passed or is not an object. Message: flowData must be an object
HTTP400 CodeINVALID_PARAMS DescriptionflowData.id is not equal to flowId from the path or is passed as a string. Message: flowData.id must match flowId
HTTP400 CodeINVALID_PARAMS DescriptionanalyticsParams is not an object. Message: analyticsParams must be an object
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not found
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe key has neither the task nor the tasks scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode. error.details.switchUrl holds the address of the section where the mode is changed
HTTP422 CodeBITRIX_ERROR DescriptionNo flow with this flowId exists. The message looks like Unknown error. [Flow: 267]; there is no 404 response in this case
HTTP422 CodeBITRIX_ERROR DescriptionThe name is taken by another flow. Message: A flow with this name already exists
HTTP429 CodeRATE_LIMITED DescriptionThe request rate to Bitrix24 or to the platform is exceeded. Retry after the delay in the Retry-After header
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unreachable or returned a server error
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time

Full list of common API errors — Errors.

See also