لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/scrum/epics.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Scrum epics

Create, read, rename and recolor epics in a scrum project. An epic groups tasks within a single Bitrix24 workgroup. Tasks are bound to an epic through task placement in scrum.

Scope: task | Base URL: https://vibecode.bitrix24.com/v1 | Auth: X-Api-Key

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
Fieldname Typestring Requiredyes DescriptionEpic name. Up to 65,535 characters
FieldgroupId Typenumber Requiredyes DescriptionScrum project (workgroup) ID. List: GET /v1/workgroups
Fielddescription Typestring Requiredno DescriptionEpic description. Up to 65,535 characters
Fieldcolor Typestring Requiredno DescriptionEpic color, for example "#5eead4". Up to 64 characters
FieldcreatedBy Typenumber Requiredno DescriptionAuthor 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe created epic
Fielddata.id Typenumber DescriptionID of the created epic
Fielddata.groupId Typenumber DescriptionScrum project ID
Fielddata.name Typestring DescriptionEpic name
Fielddata.description Typestring DescriptionEpic description
Fielddata.color Typestring DescriptionEpic color
Fielddata.createdBy Typenumber DescriptionAuthor ID
Fielddata.modifiedBy Typenumber DescriptionID 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
HTTP400 CodeINVALID_PARAMS Descriptionname or groupId is missing, or a value has the wrong type
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error while creating the epic, for example no scrum project exists with the given groupId
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the task scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP401 CodeTOKEN_MISSING DescriptionThe 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