# Update a task stage

`PATCH /v1/task-stages/:stageId`

Changes the title, color or position of a stage in a workgroup kanban or in My Plan.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|----------|
| `stageId` (path) | number | yes | Stage ID. List: [`GET /v1/tasks/stages/:entityId`](/docs/task-stages/list) |

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|----------|
| `title` | string | no | New title. An empty string and a whitespace-only string are refused |
| `color` | string | no | Color in `RRGGBB` or `#RRGGBB` format. Stored without `#` |
| `afterStageId` | number | no | ID of a stage on the same kanban; the updated stage is placed after it. `0` places the stage first and makes it the default stage |

At least one field is required. An empty body and any other fields, including `sort`, are refused with `400 INVALID_PARAMS`.

## Examples

### curl — personal key

```bash
curl -X PATCH "https://vibecode.bitrix24.com/v1/task-stages/629" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Approval", "color": "FF8800"}'
```

### curl — OAuth application

```bash
curl -X PATCH "https://vibecode.bitrix24.com/v1/task-stages/629" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Approval", "color": "FF8800"}'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/task-stages/629', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ title: 'Approval', color: 'FF8800' }),
})

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

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/task-stages/629', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ title: 'Approval', color: 'FF8800' }),
})

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

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data` | object | Update result |
| `data.id` | number | ID of the updated stage |
| `data.updated` | boolean | Always `true` |

The response does not contain the stage itself. Read the new values and order with [`GET /v1/tasks/stages/:entityId`](/docs/task-stages/list).

## Response example

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

## Error response example

400 — an empty body or a field not listed in the table, for example `sort`:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Provide title, color or afterStageId; unsupported fields are refused"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `stageId` is not a positive integer, the body is empty, the body contains other fields, `title` is empty, `color` has an invalid format, or `afterStageId` is not a non-negative integer: `Provide title, color or afterStageId; unsupported fields are refused` |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `TOKEN_MISSING` | The key has no valid Bitrix24 token |
| 403 | `SCOPE_DENIED` | The key does not have the `task` or `tasks` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only |
| 403 | `BITRIX_ACCESS_DENIED` | The key's user has no rights to the group kanban |
| 404 | `ENTITY_NOT_FOUND` | No stage with this `stageId` exists. The `message` text comes from Bitrix24 in the Bitrix24 account language |
| 422 | `BITRIX_ERROR` | Bitrix24 did not confirm the update: `Bitrix24 did not confirm the update; reread stages before retrying` |
| 422 | `BITRIX_ERROR` | Bitrix24 refused the update; the reason is in `message` |

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

## Known specifics

- **`afterStageId: 0` assigns tasks without a stage to the previous default stage.** Group tasks that had no stage (`stageId: 0`) get the stage that was first before the update. No move entry appears in the history of these tasks.
- **`afterStageId` from another kanban does not return an error.** The response is `200`, and the stage moves to the end of its own board.
- **`sort` values of neighboring stages are recalculated.** After a stage is moved, Bitrix24 renumbers the `sort` values of all stages on the board in steps of 100.

## See also

- [Tasks: kanban, My Plan and the day plan](/docs/tasks)
- [Task kanban stages](/docs/task-stages)
- [Create a task stage](/docs/tasks/stages)
- [Delete an empty task stage](/docs/task-stages/delete)
- [Task change history](/docs/task-history)