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 Req. 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 app

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 app

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
id number ID of the created epic
groupId number Scrum project ID
name string Epic name
description string Epic description
color string Epic color
createdBy number Author ID
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. Only the Bitrix24 user the key acts as, with access to the scrum project, can create epics. Otherwise the Bitrix24 account returns 422 BITRIX_ERROR with the message "Access denied".

See also