# Delete an empty task stage

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

Deletes a stage with no tasks from a workgroup kanban or from My Plan. A deleted stage cannot be restored through the API — create a new one if needed.

## Parameters

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

## Examples

### curl — personal key

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

### curl — OAuth application

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

if (res.status === 204) {
  console.log('Stage deleted')
}
```

### JavaScript — OAuth application

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

if (res.status === 204) {
  console.log('Stage deleted')
}
```

## Response

On successful deletion the API returns HTTP status `204 No Content` with an empty body. Success is indicated by the status code, not the content.

## Response example

```
HTTP/1.1 204 No Content
```

## Error response example

409 — the stage contains tasks:

```json
{
  "success": false,
  "error": {
    "code": "STAGE_NOT_EMPTY",
    "message": "The stage contains tasks; move them first (including tasks not visible to you)"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `stageId` is not a positive integer: `stageId must be a positive integer` |
| 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 lacks 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`, including when the stage is deleted a second time. The `message` text comes from Bitrix24 in the Bitrix24 account's language |
| 409 | `STAGE_NOT_EMPTY` | The stage contains tasks: `The stage contains tasks; move them first (including tasks not visible to you)` |
| 409 | `STAGE_IS_SYSTEM` | The stage is first on the board, that is, the default stage: `The first stage cannot be deleted` |
| 422 | `BITRIX_ERROR` | Bitrix24 did not confirm the deletion: `Bitrix24 did not confirm deletion; reread stages before retrying` |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the deletion. The text is in `message` |

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

## Known specifics

- **Emptiness counts all tasks.** Tasks the key's user cannot see are counted too. If `STAGE_NOT_EMPTY` comes back for a stage that looks empty, it holds tasks not accessible to the key's user.
- **How to delete the first stage.** First make another stage the first one: [`PATCH /v1/task-stages/:stageId`](/docs/task-stages/update) with `afterStageId: 0`. Group tasks without a stage are then assigned to the former first stage, and the deletion returns `409 STAGE_NOT_EMPTY`. Find them in the [task list](/docs/entities/tasks/list) with `filter[stageId]=<stage ID>`, move them with the [move method](/docs/tasks/move-stage) and retry the deletion.

## See also

- [Tasks: kanban, My Plan and the day plan](/docs/tasks)
- [Task kanban stages](/docs/task-stages)
- [Move a task with ordering](/docs/tasks/move-stage)
- [Update a task stage](/docs/task-stages/update)