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

Place or move a task in scrum

PATCH /v1/scrum/tasks/:taskId

Places a task in scrum and moves it between backlog, sprint and epic, sets story points and sort order. Pass only the fields you want to change.

Parameters

Parameter Type Req. Description
taskId number yes Task ID (path parameter). Source: GET /v1/tasks

Request fields (body)

At least one field is required.

Field Type Description
epicId number Epic binding. 0 — unbind from the epic. Source: GET /v1/scrum/epics
entityId number Backlog or sprint ID. Resolved automatically — pass it explicitly only to place the task into a specific sprint
storyPoints string | number Story points, for example "3" or "0.5". An empty string clears them
sort number Position in the list
sortFloat number Position in the list. Takes priority over sort
modifiedBy number ID of the editor. Source: GET /v1/users. The placement's createdBy does not change

Examples

curl — personal key

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/scrum/tasks/59 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "epicId": 11, "storyPoints": "3" }'

curl — OAuth app

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/scrum/tasks/59 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "epicId": 11, "storyPoints": "3" }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/tasks/59', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ epicId: 11, storyPoints: '3' }),
})
const { data } = await res.json()
console.log('Placement:', data)

JavaScript — OAuth app

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/tasks/59', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ epicId: 11, storyPoints: '3' }),
})
const { data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data.entityId number ID of the backlog or sprint the task is in
data.epicId number Epic ID. 0 — the task is not bound to an epic
data.storyPoints string Story points, for example "3". Empty string — not set
data.sort number Position in the list
data.sortFloat number Position in the list. Takes priority over sort
data.createdBy number ID of the placement author
data.modifiedBy number ID of the last editor

Response example

JSON 
{
  "success": true,
  "data": {
    "entityId": 1,
    "storyPoints": "3",
    "epicId": 11,
    "sort": 255,
    "sortFloat": 512,
    "createdBy": 1,
    "modifiedBy": 1
  }
}

Error response example

400 — the task has no workgroup, auto-placement into the backlog is impossible:

JSON 
{
  "success": false,
  "error": {
    "code": "TASK_NOT_IN_GROUP",
    "message": "Task 289 has no workgroup (GROUP_ID), so it cannot be placed in scrum. Move the task into a scrum project first (PATCH /v1/tasks/:id { \"groupId\": N }) or pass entityId explicitly."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS Empty body, a non-numeric field, or an attempt to set createdBy
400 TASK_NOT_IN_GROUP The task has no workgroup — auto-placement into the backlog is impossible. Move the task into a scrum project via PATCH /v1/tasks/:id { "groupId": N } or pass entityId explicitly
422 BACKLOG_NOT_RESOLVED The task's workgroup is not a scrum project, no backlog found
422 BITRIX_ERROR The task was not found or another Bitrix24 error, for example the groupId of the epic and the task do not match
403 SCOPE_DENIED The key lacks the task scope
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode
401 TOKEN_MISSING The key has no configured tokens

Full list of common API errors — Errors.

Known specifics

  • The backlog is resolved automatically. If entityId is omitted and the task is not yet in scrum, the API finds the backlog of the task's scrum project by its workgroup and places the task there. A task already placed in scrum keeps its current backlog or sprint.
  • Access. Only the Bitrix24 user the key acts as, with access to the task's scrum project, can place tasks. Otherwise the Bitrix24 account returns 422 BITRIX_ERROR with the message "Access denied".

See also