#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.

Bitrix24 API: tasks.api.scrum.epic.*, tasks.api.scrum.task.*, tasks.api.scrum.backlog.get Scope: task

#Endpoints

#Quick start

#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,
    "description": "Mirror of an epic from an external tracker",
    "color": "#5eead4"
  }'

Response 201:

{
  "success": true,
  "data": {
    "id": 87,
    "groupId": 7,
    "name": "Chat folders",
    "description": "Mirror of an epic from an external tracker",
    "createdBy": 1,
    "modifiedBy": 1,
    "color": "#5eead4"
  }
}

#Bind a task to an epic

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 }'

The response is the task's actual placement after the change (the API re-reads it so you can verify the binding applied):

{
  "success": true,
  "data": { "entityId": 1, "epicId": 87, "storyPoints": "" }
}

#Epic fields (POST / PATCH)

#Task placement fields (PATCH /v1/scrum/tasks/:taskId)

#What to know before you start

1. entityId is resolved automatically. If the task is already in scrum, its current placement (backlog or sprint) is kept. If not, the API finds the backlog of the task's scrum project and places it there. Pass entityId explicitly only when you need to put the task into a specific sprint.
2. The task must belong to a group. Auto-placement works through the task's groupId. A task without a workgroup returns 400 TASK_NOT_IN_GROUP — move it into a scrum project first (PATCH /v1/tasks/:id { "groupId": N }) or pass entityId explicitly.
3. The group must be a scrum project. For a regular (non-scrum) group Bitrix24 cannot find a backlog — the API returns 422 BACKLOG_NOT_RESOLVED.
4. The epic's and the task's groupId must match. Bitrix24 rejects binding a task to an epic from another project.
5. PATCH returns the actual placement. The native Bitrix24 method returns only true — the API additionally re-reads the task's scrum row so the response is verifiable (no silent no-ops).
6. Permissions. Creating epics and moving tasks requires the key's B24 user to be a member of the scrum project with the right to create tasks.
7. The epic list paginates automatically. GET /v1/scrum/epics returns up to limit epics (default 200, max 1000) — the API fetches the Bitrix24 pages of 50 records for you.

#Typical scenario: mirroring an external tracker

1. Create an epic: POST /v1/scrum/epics { name, groupId } → remember data.id.
2. Create a task: `POST /v1/tasks` { title, groupId, responsibleId, tags }.
3. Bind it to the epic: PATCH /v1/scrum/tasks/:taskId { epicId } — the task is automatically placed into the project backlog.
4. When the epic is renamed in the external tracker: PATCH /v1/scrum/epics/:id { name }.
5. Verify the placement: GET /v1/scrum/tasks/:taskId.

#Errors

#See also

• Tasks — creating and updating the tasks themselves
• Task chat — reading task chat messages
• Workgroups — source of groupId
• Limits and optimization — rate limits