لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/scrum/sprints.md فهرس التوثيق — /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.

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
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