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

Scrum: epics and task placement

Manage scrum in Bitrix24 projects: create and rename epics, bind tasks to epics, place tasks in the backlog, set story points. 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 is already 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

Error codes

HTTP Code Cause
400 INVALID_PARAMS Request field validation failed
400 TASK_NOT_IN_GROUP 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
422 BITRIX_ERROR Task not found or not placed in scrum, or another Bitrix24 error

Full list of common API errors — Errors.

See also