# 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](/docs/entities/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 epics](/docs/scrum/epics) — create, read, rename and recolor epics
- [Task placement in scrum](/docs/scrum/tasks) — read and change a task's scrum row: backlog or sprint, epic, story points

## Quick start

### 1. Create an epic

```bash
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`](/docs/entities/tasks/create) and belongs to the scrum project `groupId`. Binding automatically places it into the project backlog:

```bash
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`](/docs/scrum/epics/create) | tasks.api.scrum.epic.add | Create an epic |
| GET | [`/v1/scrum/epics`](/docs/scrum/epics/list) | tasks.api.scrum.epic.list | List epics |
| GET | [`/v1/scrum/epics/:id`](/docs/scrum/epics/get) | tasks.api.scrum.epic.get | Get an epic |
| PATCH | [`/v1/scrum/epics/:id`](/docs/scrum/epics/update) | tasks.api.scrum.epic.update | Rename / update an epic |
| GET | [`/v1/scrum/tasks/:taskId`](/docs/scrum/tasks/get) | tasks.api.scrum.task.get | Get a task's scrum placement |
| PATCH | [`/v1/scrum/tasks/:taskId`](/docs/scrum/tasks/update) | 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](/docs/errors).

## See also

- [Tasks](/docs/entities/tasks)
- [Task chat](/docs/entities/tasks/chat)
- [Workgroups](/docs/entities/workgroups)
- [Limits and optimization](/docs/optimization)