Para agentes de IA: markdown desta página — /docs-content-en/scrum.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

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
POST /v1/scrum/epics tasks.api.scrum.epic.add Create an epic
GET /v1/scrum/epics tasks.api.scrum.epic.list List epics
GET /v1/scrum/epics/:id tasks.api.scrum.epic.get Get an epic
PATCH /v1/scrum/epics/:id tasks.api.scrum.epic.update Rename / update an epic
GET /v1/scrum/tasks/:taskId tasks.api.scrum.task.get Get a task's scrum placement
PATCH /v1/scrum/tasks/:taskId tasks.api.scrum.task.update Place / move a task
GET /v1/scrum/sprints tasks.api.scrum.sprint.list Sprints of a scrum project
GET /v1/scrum/sprints/active tasks.api.scrum.sprint.list Active sprint of a project
GET /v1/scrum/sprints/:id tasks.api.scrum.sprint.get Get a sprint by ID
GET /v1/scrum/sprints/:sprintId/stages tasks.api.scrum.kanban.getStages Columns of a sprint board
POST /v1/scrum/sprints/:sprintId/stages tasks.api.scrum.kanban.addStage Create a column
PATCH /v1/scrum/stages/:stageId tasks.api.scrum.kanban.updateStage Update a column

Error codes

HTTP Code Cause
400 INVALID_PARAMS Request field validation failed
400 TASK_NOT_IN_GROUP The task has no workgroup — auto-placement into the backlog is impossible
403 SCOPE_DENIED The key lacks the task scope
422 BACKLOG_NOT_RESOLVED The task's group is not a scrum project, no backlog found
404 STAGE_NOT_FOUND_OR_NO_ACCESS The kanban stage does not exist, or belongs to a scrum project you cannot access
422 BITRIX_ERROR Task not found or not placed in scrum, or another Bitrix24 error

Full list of common API errors — Errors.

See also