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

Sprints

Read sprints from scrum projects: the full list visible to the key, the project's current active sprint, or one record by ID. A sprint ID is also used by operations on the columns of its board.

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

List sprints

GET /v1/scrum/sprints

Returns the sprints of the Bitrix24 account's scrum projects. Board stage operations and reading a single sprint need the identifier from the id field.

Parameters

Parameter Type Default Description
ParametergroupId (query) Typenumber Default— DescriptionScrum project ID. List: GET /v1/workgroups. Without the parameter, the response contains every sprint the key can see
Parameterlimit (query) Typenumber Default200 DescriptionHow many sprints to return, from 1 to 1000

Pagination. Pages are fetched automatically — the response arrives as a single array of up to limit records, and the method has no offset parameter. A limit above 1000 is clamped to 1000 without an error.

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/sprints \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/scrum/sprints \
  -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/sprints', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
const active = data.filter((sprint) => sprint.status === 'active')
console.log(active.map((sprint) => `${sprint.id}: ${sprint.name}`))

JavaScript — OAuth application

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

const { data } = await res.json()
console.log(data.map((sprint) => sprint.name))

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of sprints
Fielddata[].id Typenumber DescriptionSprint ID. The same value as sprintId in stage operations
Fielddata[].groupId Typenumber DescriptionScrum project ID. List: GET /v1/workgroups
Fielddata[].entityType Typestring DescriptionRecord type, sprint
Fielddata[].name Typestring DescriptionSprint name
Fielddata[].goal Typestring DescriptionSprint goal. An empty string is returned when no goal is set
Fielddata[].sort Typenumber DescriptionSprint order within the project
Fielddata[].createdBy Typenumber DescriptionID of the sprint author. List: GET /v1/users
Fielddata[].modifiedBy Typenumber DescriptionID of the user who last changed the sprint. List: GET /v1/users
Fielddata[].dateStart Typestring DescriptionSprint start in ISO 8601 with the account's UTC offset
Fielddata[].dateEnd Typestring DescriptionSprint end in ISO 8601 with the account's UTC offset
Fielddata[].status Typestring Descriptionplanned, active or completed

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 9,
      "groupId": 45,
      "entityType": "sprint",
      "name": "Sprint 2",
      "goal": "",
      "sort": 0,
      "createdBy": 29,
      "modifiedBy": 29,
      "dateStart": "2023-09-01T01:00:00+00:00",
      "dateEnd": "2024-04-16T12:20:42+00:00",
      "status": "completed"
    },
    {
      "id": 11,
      "groupId": 45,
      "entityType": "sprint",
      "name": "Sprint 3",
      "goal": "",
      "sort": 0,
      "createdBy": 29,
      "modifiedBy": 29,
      "dateStart": "2023-09-15T01:00:00+00:00",
      "dateEnd": "2023-09-29T01:00:00+00:00",
      "status": "active"
    },
    {
      "id": 21,
      "groupId": 53,
      "entityType": "sprint",
      "name": "Sprint 6",
      "goal": "",
      "sort": 0,
      "createdBy": 1,
      "modifiedBy": 1,
      "dateStart": "2024-06-05T01:00:00+00:00",
      "dateEnd": "2024-06-19T01:00:00+00:00",
      "status": "active"
    }
  ]
}

Error response example

400 — an invalid groupId value:

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 is not a positive integer
HTTP400 CodeINVALID_PARAMS Descriptionlimit is not a positive integer
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error, e.g. "Access denied" when the key's user has no access to the scrum project
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the task scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no tokens configured

The full list of common API errors — Errors.

Known specifics

  • Without groupId the sprints of different projects are interleaved. The response is not grouped by project, so split the result on your side by each record's groupId field.
  • Completed sprints stay in the result. The response is not limited to the project's current sprint. If you only need the current one, use GET /v1/scrum/sprints/active.

See also