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

List epics

GET /v1/scrum/epics

Returns the epics of the Bitrix24 account's scrum projects, optionally filtered by a specific scrum project.

Parameters

Parameter Type Required Default Description
ParametergroupId (query) Typenumber Requiredno Default— DescriptionFilter by scrum project. List: GET /v1/workgroups
Parameterlimit (query) Typenumber Requiredno Default200 DescriptionMaximum number of epics in the response. Up to 1000

When limit > 50, the API automatically fetches additional records and returns them as a single array, so all epics are returned even when the Bitrix24 account has more than 50.

The generic filter parameter is not applied by this endpoint. By default, the API preserves the previous HTTP 200 response and data, adds Warning: 299 - "filter is not supported on this endpoint and was ignored", and records unsupported-filter use in the server log.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/scrum/epics?groupId=45" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/scrum/epics?groupId=45" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/epics?groupId=45', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Epics:', data.length)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/epics?groupId=45', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of epics
Fielddata[].id Typenumber DescriptionEpic identifier
Fielddata[].groupId Typenumber DescriptionEpic's scrum project. List: GET /v1/workgroups
Fielddata[].name Typestring DescriptionEpic name
Fielddata[].description Typestring DescriptionEpic description
Fielddata[].createdBy Typenumber DescriptionEpic author. List: GET /v1/users
Fielddata[].modifiedBy Typenumber DescriptionWho edited the epic last. 0 if it was never edited. List: GET /v1/users
Fielddata[].color Typestring DescriptionEpic color in HEX format

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 3,
      "groupId": 45,
      "name": "Authorization",
      "description": "",
      "createdBy": 29,
      "modifiedBy": 0,
      "color": "#c4baed"
    },
    {
      "id": 5,
      "groupId": 45,
      "name": "Payments",
      "description": "",
      "createdBy": 29,
      "modifiedBy": 0,
      "color": "#ffcbd8"
    },
    {
      "id": 7,
      "groupId": 45,
      "name": "Reports",
      "description": "Summary reports by sprint",
      "createdBy": 1,
      "modifiedBy": 1,
      "color": "#69dafc"
    }
  ]
}

Error response example

400 — validation failed:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupId must be a positive integer"
  }
}

Errors

HTTP Code Description
HTTP200 CodeWarning: 299 DescriptionThe filter is ignored by default; previous data is preserved and the warning is sent in the Warning header.
HTTP400 (strict mode only) CodeUNSUPPORTED_FILTER DescriptionThe server mode is disabled by default; until it is enabled, the endpoint preserves HTTP 200 and the previous data.
HTTP400 CodeINVALID_PARAMS DescriptiongroupId or limit is not a positive integer
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the task scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens

Full list of common API errors — Errors.

See also