## Delete a schedule

`DELETE /v1/work-schedules/:id`

Deletes a custom schedule from the library of the Bitrix24 account. A schedule that servers run on is deleted only with consent to move them to another run mode. A deleted schedule cannot be restored through the API — create a new one if needed.

## Parameters

| Parameter | In | Type | Required | Description |
|----------|---|-----|:-----:|----------|
| `id` | path | string | yes | ID of a custom schedule. Source — `data[].id` from the [schedule list](./list.md) |
| `reassign` | query | string | no | `true` — consent to move the servers on the schedule to another run mode before deleting it: an app goes to `IDLE` with its remembered idle threshold, 60 minutes if it has none, an agent or a bot goes to `ALWAYS`. Any other value reads as a refusal |

## Examples

### curl — personal key

```bash
curl -X DELETE "https://vibecode.bitrix24.com/v1/work-schedules/WORK_SCHEDULE_ID?reassign=true" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl -X DELETE "https://vibecode.bitrix24.com/v1/work-schedules/WORK_SCHEDULE_ID?reassign=true" \
  -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/work-schedules/${workScheduleId}?reassign=true`,
  { method: 'DELETE', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
if (res.status === 204) {
  console.log('Schedule deleted')
}
```

### JavaScript — OAuth application

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/work-schedules/${workScheduleId}?reassign=true`,
  {
    method: 'DELETE',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
if (res.status === 204) {
  console.log('Schedule deleted')
}
```

## Response

A successful delete returns HTTP status `204 No Content` with an empty body. Success is signaled by the status code, not the content. The new run modes of the moved servers are read in [`GET /v1/infra/servers/:id`](/docs/infra/servers/get).

## Response example

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

## Error response example

409 — servers run on the schedule, and `reassign=true` was not passed:

```json
{
  "success": false,
  "error": {
    "code": "WORK_SCHEDULE_IN_USE",
    "message": "The work schedule is assigned to servers: repeat with reassign=true to move them to another run mode and delete it",
    "details": { "assignedCount": 2 }
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `RUN_MODE_UNAVAILABLE` | Run modes are not enabled for the Bitrix24 account yet |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The key is not recognized: no such key exists on the platform |
| 403 | `WORK_SCHEDULE_PRESET_READONLY` | The schedule is a preset — it cannot be deleted |
| 403 | `WORK_SCHEDULE_EDIT_FORBIDDEN` | Only the author or an administrator of the Bitrix24 account may delete the schedule |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only — deleting is closed to it |
| 403 | `INFRA_SCOPE_REQUIRED` | The key lacks the `vibe:infra` scope |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | The call was made with a Cowork/Code key — the schedule library is closed to such a key. What to do — [Project deploy key](/docs/cowork/deploy-key) |
| 404 | `NOT_FOUND` | No schedule with this `id` exists in the key's Bitrix24 account, or the key is not bound to a Bitrix24 account |
| 409 | `WORK_SCHEDULE_IN_USE` | Servers run on the schedule, and `reassign=true` was not passed. The number of servers is in `error.details.assignedCount`. The same answer comes when a server was assigned to the schedule during the delete — repeat the request |
| 429 | `RATE_LIMITED` | The limit of 10 requests per minute per key is exceeded. The exact value is in the `x-ratelimit-limit` header (the ceiling is split between replicas) |

Full list of shared error codes — [Errors](/docs/errors).

## Known specifics

- **Moving covers other employees' servers too.** With `reassign=true` every server on the schedule moves to another run mode, not only the key owner's — and its cost changes together with the mode.
- **Deleted servers do not block the delete.** Servers that are already deleted do not count in `assignedCount` and are taken off the schedule without consent.

## See also

- [List schedules](./list.md)
- [Update a schedule](./update.md)
- [Set the server run mode](/docs/infra/lifecycle/run-mode)