## Update a stage

`PATCH /v1/scrum/stages/:stageId`

Renames, recolours and reorders a column. Partial update — send only what changes.

The path carries no sprint segment: Bitrix24 identifies a column by `stageId` alone.

## Path parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `stageId` | number | yes | Stage ID. Obtain with `GET /v1/scrum/sprints/:sprintId/stages` |

## Request body

| Field | Type | Required | Description |
|------|-----|:-----:|---------|
| `name` | string | no | Column name. Up to 255 characters |
| `type` | string | no | `NEW`, `WORK` or `FINISH` |
| `sort` | number | no | Column order |
| `color` | string | no | Six hexadecimal characters. A leading `#` is stripped |

At least one field is required. The `sprintId` field is rejected.

## Examples

### curl — personal key

```bash
curl -X PATCH https://vibecode.bitrix24.com/v1/scrum/stages/561 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Under review", "color": "47D1E2" }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/scrum/stages/561', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Under review', color: '47D1E2' }),
})

const { data } = await res.json()
console.log(data.updated)
```

## Response example

```json
{
    "success": true,
    "data": { "updated": true }
}
```

The response does not carry the column itself: the Bitrix24 method does not report which sprint it belongs to, so it cannot be re-read without an extra request. For current values, see [List stages](/docs/scrum/stages/list).

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | Empty body; `stageId` is not a positive integer; `sprintId` sent; a value failed validation |
| 404 | `STAGE_NOT_FOUND_OR_NO_ACCESS` | The stage does not exist **or** belongs to a scrum project you cannot access |
| 403 | `SCOPE_DENIED` | The key lacks the `task` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only |
| 401 | `TOKEN_MISSING` | The key has no tokens configured |

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

## Known specifics

- **`STAGE_NOT_FOUND_OR_NO_ACCESS` merges two causes on purpose.** Bitrix24 answers "no such stage" and "the stage exists but is not yours" identically, so the two cannot be told apart. A separate code for the second case would confirm that someone else's column exists.
- **Moving to another sprint is not exposed.** Bitrix24 can do it, but the column then silently disappears from a live board. Create the column in the sprint you mean instead.

## See also

- [List stages](/docs/scrum/stages/list)
- [Create a stage](/docs/scrum/stages/create)
- [Scrum kanban stages](/docs/scrum/stages)