لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/scrum.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Scrum: epics, sprints, task placement and kanban stages

Manage scrum in Bitrix24 projects: read sprint lists and the current sprint, create and rename epics, bind tasks to epics, place tasks in the backlog, set story points, manage sprint board columns. Works on top of regular Tasks — first create the task via POST /v1/tasks, then place it in scrum.

Scope: task | Base URL: https://vibecode.bitrix24.com/v1 | Auth: X-Api-Key

Documentation sections

Quick start

1. Create an epic

Terminal
curl -X POST "https://vibecode.bitrix24.com/v1/scrum/epics" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Chat folders", "groupId": 7 }'

2. Bind a task to an epic

The task has already been created via POST /v1/tasks and belongs to the scrum project groupId. Binding automatically places it into the project backlog:

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": 87 }'

Full example: mirroring an external tracker

Create an epic, add a task in the scrum project, bind it to the epic and verify the placement. The backlog is resolved automatically.

javascript
const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.com/v1'
const GROUP_ID = 7 // scrum project, list: GET /v1/workgroups

// ── 1. Create an epic ───────────────────────────────────────────
const epicRes = await fetch(`${BASE}/scrum/epics`, {
  method: 'POST',
  headers: { 'X-Api-Key': VIBE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Chat folders', groupId: GROUP_ID })
})
const { data: epic } = await epicRes.json()
console.log(`Epic created, ID: ${epic.id}`)

// ── 2. Create a task in the same scrum project ──────────────────
const taskRes = await fetch(`${BASE}/tasks`, {
  method: 'POST',
  headers: { 'X-Api-Key': VIBE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'Lay out the folder list', groupId: GROUP_ID, responsibleId: 1 })
})
const { data: task } = await taskRes.json()
console.log(`Task created, ID: ${task.id}`)

// ── 3. Bind the task to the epic ────────────────────────────────
//     entityId omitted → the task is automatically placed into the project backlog
await fetch(`${BASE}/scrum/tasks/${task.id}`, {
  method: 'PATCH',
  headers: { 'X-Api-Key': VIBE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ epicId: epic.id, storyPoints: '3' })
})

// ── 4. Verify the actual placement ──────────────────────────────
const placeRes = await fetch(`${BASE}/scrum/tasks/${task.id}`, {
  headers: { 'X-Api-Key': VIBE_KEY }
})
const { data: placement } = await placeRes.json()
console.log('Placement:', placement)

Endpoint reference

Method Path Bitrix24 method Description
MethodPOST Path/v1/scrum/epics Bitrix24 methodtasks.api.scrum.epic.add DescriptionCreate an epic
MethodGET Path/v1/scrum/epics Bitrix24 methodtasks.api.scrum.epic.list DescriptionList epics
MethodGET Path/v1/scrum/epics/:id Bitrix24 methodtasks.api.scrum.epic.get DescriptionGet an epic
MethodPATCH Path/v1/scrum/epics/:id Bitrix24 methodtasks.api.scrum.epic.update DescriptionRename / update an epic
MethodGET Path/v1/scrum/tasks/:taskId Bitrix24 methodtasks.api.scrum.task.get DescriptionGet a task's scrum placement
MethodPATCH Path/v1/scrum/tasks/:taskId Bitrix24 methodtasks.api.scrum.task.update DescriptionPlace / move a task
MethodGET Path/v1/scrum/sprints Bitrix24 methodtasks.api.scrum.sprint.list DescriptionSprints of a scrum project
MethodGET Path/v1/scrum/sprints/active Bitrix24 methodtasks.api.scrum.sprint.list DescriptionActive sprint of a project
MethodGET Path/v1/scrum/sprints/:id Bitrix24 methodtasks.api.scrum.sprint.get DescriptionGet a sprint by ID
MethodGET Path/v1/scrum/sprints/:sprintId/stages Bitrix24 methodtasks.api.scrum.kanban.getStages DescriptionColumns of a sprint board
MethodPOST Path/v1/scrum/sprints/:sprintId/stages Bitrix24 methodtasks.api.scrum.kanban.addStage DescriptionCreate a column
MethodPATCH Path/v1/scrum/stages/:stageId Bitrix24 methodtasks.api.scrum.kanban.updateStage DescriptionUpdate a column
MethodGET Path/v1/scrum/groups/:groupId/dod/settings Bitrix24 methodtasks.scrum.DoD.getSettings DescriptionRead DoD settings
MethodGET Path/v1/scrum/groups/:groupId/tasks/:taskId/dod/necessary Bitrix24 methodtasks.scrum.DoD.isNecessary DescriptionCheck whether DoD is needed
MethodPOST Path/v1/scrum/groups/:groupId/dod/types/:typeId/settings Bitrix24 methodtasks.scrum.DoD.saveSettings DescriptionSave DoD settings
MethodPOST Path/v1/scrum/tasks/:taskId/dod/:typeId Bitrix24 methodtasks.scrum.DoD.saveList DescriptionSave a task's DoD list
MethodGET Path/v1/scrum/groups/:groupId/burn-down Bitrix24 methodtasks.scrum.Sprint.getBurnDownInfo DescriptionBurn-down source data
MethodGET Path/v1/scrum/groups/:groupId/team-speed Bitrix24 methodtasks.scrum.Sprint.getTeamSpeedInfo DescriptionCompleted-sprint flag
MethodPOST Path/v1/scrum/backlogs Bitrix24 methodtasks.api.scrum.backlog.add DescriptionCreate a backlog
MethodPATCH Path/v1/scrum/backlogs/:id Bitrix24 methodtasks.api.scrum.backlog.update DescriptionUpdate a backlog
MethodDELETE Path/v1/scrum/backlogs/:id Bitrix24 methodtasks.api.scrum.backlog.delete DescriptionDelete a backlog
MethodDELETE Path/v1/scrum/epics/:id Bitrix24 methodtasks.api.scrum.epic.delete DescriptionDelete an epic
MethodPOST Path/v1/scrum/sprints Bitrix24 methodtasks.api.scrum.sprint.add DescriptionCreate a sprint
MethodPATCH Path/v1/scrum/sprints/:id Bitrix24 methodtasks.api.scrum.sprint.update DescriptionUpdate a sprint
MethodDELETE Path/v1/scrum/sprints/:id Bitrix24 methodtasks.api.scrum.sprint.delete DescriptionDelete a sprint
MethodPOST Path/v1/scrum/sprints/:id/start Bitrix24 methodtasks.api.scrum.sprint.start DescriptionStart a sprint
MethodPOST Path/v1/scrum/groups/:groupId/sprints/active/complete Bitrix24 methodtasks.api.scrum.sprint.complete DescriptionComplete the group's active sprint
MethodDELETE Path/v1/scrum/stages/:stageId Bitrix24 methodtasks.api.scrum.kanban.deleteStage DescriptionDelete a stage
MethodPOST Path/v1/scrum/sprints/:sprintId/kanban/tasks/:taskId Bitrix24 methodtasks.api.scrum.kanban.addTask DescriptionAdd a task to the board
MethodDELETE Path/v1/scrum/sprints/:sprintId/kanban/tasks/:taskId Bitrix24 methodtasks.api.scrum.kanban.deleteTask DescriptionRemove a task from the board

Error codes

HTTP Code Cause
HTTP400 CodeINVALID_PARAMS CauseRequest field validation failed
HTTP400 CodeTASK_NOT_IN_GROUP CauseThe task has no workgroup — auto-placement into the backlog is impossible
HTTP403 CodeSCOPE_DENIED CauseThe key lacks the task scope
HTTP422 CodeBACKLOG_NOT_RESOLVED CauseThe task's group is not a scrum project, no backlog found
HTTP404 CodeSTAGE_NOT_FOUND_OR_NO_ACCESS CauseThe kanban stage does not exist, or belongs to a scrum project you cannot access
HTTP404 CodeENTITY_NOT_FOUND CauseThe task, epic or sprint was not found, or the task is not placed in scrum
HTTP422 CodeBITRIX_ERROR CauseOther Bitrix24 errors

Full list of common API errors — Errors.

See also