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

Create an epic

POST /v1/scrum/epics

Creates an epic in a scrum project. The body is flat, with no fields wrapper.

Request fields (body)

Field Type Required Description
name string yes Epic name. Up to 65,535 characters
groupId number yes Scrum project (workgroup) ID. List: GET /v1/workgroups
description string no Epic description. Up to 65,535 characters
color string no Epic color, for example "#5eead4". Up to 64 characters
createdBy number no Author ID. Defaults to the user the key belongs to. List: GET /v1/users

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/scrum/epics \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-verify create",
    "groupId": 45,
    "description": "Mirror of an epic from an external tracker",
    "color": "#5eead4"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/epics', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'doc-verify create',
    groupId: 45,
    description: 'Mirror of an epic from an external tracker',
    color: '#5eead4',
  }),
})

const { data } = await res.json()
console.log('Epic ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/epics', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'doc-verify create',
    groupId: 45,
    description: 'Mirror of an epic from an external tracker',
    color: '#5eead4',
  }),
})

const { data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data object The created epic
data.id number ID of the created epic
data.groupId number Scrum project ID
data.name string Epic name
data.description string Epic description
data.color string Epic color
data.createdBy number Author ID
data.modifiedBy number ID of the last editor. Equals 0 on creation

Response example

JSON 
{
    "success": true,
    "data": {
        "id": 11,
        "groupId": 45,
        "name": "doc-verify create",
        "description": "Mirror of an epic from an external tracker",
        "createdBy": 1,
        "modifiedBy": 0,
        "color": "#5eead4"
    }
}

Error response example

400 — validation failed:

JSON 
{
    "success": false,
    "error": {
        "code": "INVALID_PARAMS",
        "message": "name is required"
    }
}

Errors

HTTP Code Description
400 INVALID_PARAMS name or groupId is missing, or a value has the wrong type
422 BITRIX_ERROR Bitrix24 returned an error while creating the epic, for example no scrum project exists with the given groupId
403 SCOPE_DENIED The key lacks the task scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only
401 TOKEN_MISSING The key has no configured tokens

Full list of common API errors — Errors.

Known specifics

  • Access. The Bitrix24 user the key acts as must have access to the scrum project to create epics. Otherwise Bitrix24 returns 422 BITRIX_ERROR with the message "Access denied".

See also