[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-task-stages\u002Fupdate":3,"docs-tabs-task-stages\u002Fupdate":6},{"content":4,"lastmod":5},"# Update a task stage\n\n`PATCH \u002Fv1\u002Ftask-stages\u002F:stageId`\n\nChanges the title, color or position of a stage in a workgroup kanban or in My Plan.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|----------|\n| `stageId` (path) | number | yes | Stage ID. List: [`GET \u002Fv1\u002Ftasks\u002Fstages\u002F:entityId`](\u002Fdocs\u002Ftask-stages\u002Flist) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|----------|\n| `title` | string | no | New title. An empty string and a whitespace-only string are refused |\n| `color` | string | no | Color in `RRGGBB` or `#RRGGBB` format. Stored without `#` |\n| `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 |\n\nAt least one field is required. An empty body and any other fields, including `sort`, are refused with `400 INVALID_PARAMS`.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftask-stages\u002F629\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"title\": \"Approval\", \"color\": \"FF8800\"}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftask-stages\u002F629\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"title\": \"Approval\", \"color\": \"FF8800\"}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftask-stages\u002F629', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ title: 'Approval', color: 'FF8800' }),\n})\n\nconst { success, data } = await res.json()\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftask-stages\u002F629', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ title: 'Approval', color: 'FF8800' }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | Always `true` on success |\n| `data` | object | Update result |\n| `data.id` | number | ID of the updated stage |\n| `data.updated` | boolean | Always `true` |\n\nThe response does not contain the stage itself. Read the new values and order with [`GET \u002Fv1\u002Ftasks\u002Fstages\u002F:entityId`](\u002Fdocs\u002Ftask-stages\u002Flist).\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 629,\n    \"updated\": true\n  }\n}\n```\n\n## Error response example\n\n400 — an empty body or a field not listed in the table, for example `sort`:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"Provide title, color or afterStageId; unsupported fields are refused\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 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` |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `TOKEN_MISSING` | The key has no valid Bitrix24 token |\n| 403 | `SCOPE_DENIED` | The key does not have the `task` or `tasks` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only |\n| 403 | `BITRIX_ACCESS_DENIED` | The key's user has no rights to the group kanban |\n| 404 | `ENTITY_NOT_FOUND` | No stage with this `stageId` exists. The `message` text comes from Bitrix24 in the Bitrix24 account language |\n| 422 | `BITRIX_ERROR` | Bitrix24 did not confirm the update: `Bitrix24 did not confirm the update; reread stages before retrying` |\n| 422 | `BITRIX_ERROR` | Bitrix24 refused the update; the reason is in `message` |\n\nFull list of common API errors: [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n- **`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.\n- **`afterStageId` from another kanban does not return an error.** The response is `200`, and the stage moves to the end of its own board.\n- **`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.\n\n## See also\n\n- [Tasks: kanban, My Plan and the day plan](\u002Fdocs\u002Ftasks)\n- [Task kanban stages](\u002Fdocs\u002Ftask-stages)\n- [Create a task stage](\u002Fdocs\u002Ftasks\u002Fstages)\n- [Delete an empty task stage](\u002Fdocs\u002Ftask-stages\u002Fdelete)\n- [Task change history](\u002Fdocs\u002Ftask-history)\n","2026-10-14",{},1795344089759]