# Task kanban stages

`GET /v1/tasks/stages/:entityId`

Returns the current kanban columns of a workgroup or the personal "My tasks" plan of the current user. Use it to display the board's set of stages and their order.

Bitrix24 API: `task.stages.get`
Scope: `task`

## Parameters

| Parameter | Type | Required | Default | Description |
|----------|-----|:-----:|-----------|----------|
| `entityId` (path) | number | yes | — | Owner of the stages: workgroup identifier or `0` — the personal "My tasks" plan of the current user. Group source: `GET /v1/workgroups` |

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/tasks/stages/7" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/tasks/stages/7" \
  -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/tasks/stages/7', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data } = await res.json()
```

### JavaScript — OAuth application

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

const { success, data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of columns, sorted by `sort` |
| `data[].id` | number | Stage identifier |
| `data[].title` | string | Column name |
| `data[].sort` | number | Sort order on the board |
| `data[].color` | string | Column color in `RRGGBB` format |
| `data[].systemType` | string | System stage type: `NEW`, `WORK`, `REVIEW`, `FINISH`. For custom columns — `null` |
| `data[].entityId` | number | Owner identifier — group or user |
| `data[].entityType` | string | Owner type: `G` — group, `U` — personal plan |

## Response example

Kanban stages of group 7:

```json
{
  "success": true,
  "data": [
    {
      "id": 87,
      "title": "New",
      "sort": 100,
      "color": "00C4FB",
      "systemType": "NEW",
      "entityId": 7,
      "entityType": "G"
    },
    {
      "id": 88,
      "title": "In progress",
      "sort": 200,
      "color": "47D1E2",
      "systemType": null,
      "entityId": 7,
      "entityType": "G"
    },
    {
      "id": 89,
      "title": "Done",
      "sort": 300,
      "color": "75D900",
      "systemType": null,
      "entityId": 7,
      "entityType": "G"
    }
  ]
}
```

## Error response example

400 — `entityId` is less than zero:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "entityId must be a non-negative integer (0 = personal plan)"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `entityId` is less than zero or not a number |
| 403 | `BITRIX_ACCESS_DENIED` | No access to this group's tasks, or no group exists with the given `entityId` |
| 403 | `SCOPE_DENIED` | The key lacks the `task` scope |
| 401 | `TOKEN_MISSING` | The key has no access tokens configured |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**Group columns and task history do not match.** The method returns the current columns of the group kanban. In the task history the `STAGE` event stores the stage name at the moment of transition — it may differ from the group's current columns, and sprint stages are not part of the group kanban. To analyze past transitions, rely on the value from the history rather than on this reference.

## See also

- [Task change history](/docs/task-history)
- [Tasks](/docs/entities/tasks)
- [Entity reference](/docs/entity-api)
- [Errors](/docs/errors)