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, moves it between the backlog, sprints and epics, and sets story points and sort order. Pass only the fields you want to change.

Parameters

Parameter Type Required Description
ParametertaskId Typenumber Requiredyes DescriptionTask ID (path parameter). Source: GET /v1/tasks

Request fields (body)

At least one field is required.

Field Type Description
FieldepicId Typenumber DescriptionEpic to bind the task to. 0 — unbind from the epic. Source: GET /v1/scrum/epics
FieldentityId Typenumber DescriptionBacklog or sprint ID. Resolved automatically — pass it explicitly only to place the task into a specific sprint
FieldstoryPoints Typestring | number DescriptionStory points, for example "3" or "0.5". An empty string clears them
Fieldsort Typenumber DescriptionPosition in the list
FieldsortFloat Typenumber DescriptionPosition in the list. Takes priority over sort
FieldmodifiedBy Typenumber DescriptionID of the user who made the change. 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 application

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 application

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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe task placement after the change
Fielddata.entityId Typenumber DescriptionID of the backlog or sprint the task is in
Fielddata.epicId Typenumber DescriptionEpic ID. 0 — the task is not bound to an epic
Fielddata.storyPoints Typestring DescriptionStory points, for example "3". Empty string — not set
Fielddata.sort Typenumber DescriptionPosition in the list
Fielddata.sortFloat Typenumber DescriptionPosition in the list. Takes priority over sort
Fielddata.createdBy Typenumber DescriptionID of the placement author
Fielddata.modifiedBy Typenumber DescriptionID of the last editor
Fielddata.groupId Typenumber DescriptionID of the task's scrum project. List: GET /v1/workgroups

Response example

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

Error response example

400 — the task has no workgroup, so 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
HTTP400 CodeINVALID_PARAMS DescriptionEmpty body, a non-numeric field, or an attempt to set createdBy
HTTP400 CodeTASK_NOT_IN_GROUP DescriptionentityId is omitted, and the task has no workgroup or no task with this taskId exists — 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
HTTP404 CodeENTITY_NOT_FOUND DescriptionentityId is passed, and no task with this taskId exists
HTTP422 CodeBACKLOG_NOT_RESOLVED DescriptionThe task's workgroup is not a scrum project, so no backlog is found
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned another error — for example, the groupId of the epic and the task do not match
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the task scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP401 CodeTOKEN_MISSING DescriptionThe 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. To place tasks, the Bitrix24 user the key acts as must have access to the task's scrum project. Otherwise Bitrix24 returns 422 BITRIX_ERROR with the message "Access denied".

See also