لوكلاء 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
- Scrum backlogs — create, update and delete backlogs
- Scrum epics — create, read, rename and recolor epics
- Task placement in scrum — read and change a task's scrum row: backlog or sprint, epic, story points
- Sprints — list sprints, get the current sprint, and read one by ID
- Scrum kanban stages — the columns of a sprint board
- Definition of Done — DoD settings and saving DoD lists
- Sprint metrics — Bitrix24 source data for charts and team speed
Quick start
1. Create an epic
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:
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.
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.