---
title: "Schedule Overrides"
description: "List and add on-call schedule overrides: one-off \"X covers for Y\" windows on top of a schedule's regular rotation."
---

`GET /api/im/schedules/:id/overrides` · `POST /api/im/schedules/:id/overrides`

An **override** is a one-off "X covers for Y" window on a [schedule](./schedules): a user substituted in for a fixed time range, on top of whatever the regular rotation would otherwise produce: a holiday swap or a sick-day cover, without editing the rotation itself. Overrides are materialized into shifts by the same background worker that materializes the regular rotation.

## Authentication

Requires the base IM access every endpoint in this API needs (an IM-eligible role, or an organization-wide API token; Incident Management must be enabled for the organization). Listing is available to any IM-eligible role. **Adding** an override additionally requires the write bar: your role must be `admin`, or you must be a team admin of the schedule's team.

## List overrides

`GET /api/im/schedules/:id/overrides`

Returns the schedule's overrides, ordered by `id`. **This order is load-bearing**, not incidental. `im_schedule_override` has no priority column: precedence between overlapping overrides is decided by creation order (later creation wins), and the materializer reads them in this exact order. This endpoint cannot offer reordering, since there is nowhere to persist a reordered precedence.

### Example (cURL)

```bash
curl -X GET "$BASE_URL/api/im/schedules/7/overrides" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

### Response

`200 OK`

```json
[
  {
    "id": 12,
    "scheduleId": 7,
    "userId": "u_abc123",
    "userName": "Jane Doe",
    "startsAt": "2026-08-01T00:00:00.000Z",
    "endsAt": "2026-08-08T00:00:00.000Z",
    "createdAt": "2026-07-20T10:00:00.000Z"
  }
]
```

## Add an override

`POST /api/im/schedules/:id/overrides`

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|--------------|
| `userId` | string | Yes | The user covering during this window. Must belong to your organization. |
| `startsAt` | ISO 8601 date-time | Yes | Window start. |
| `endsAt` | ISO 8601 date-time | Yes | Window end. Must be strictly after `startsAt`. |

### Example (cURL)

```bash
curl -X POST "$BASE_URL/api/im/schedules/7/overrides" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "u_abc123",
    "startsAt": "2026-08-01T00:00:00.000Z",
    "endsAt": "2026-08-08T00:00:00.000Z"
  }'
```

### Response

`200 OK`: the newly created override row (same shape as the list above).

## Common errors

- `401 Unauthorized` when not authenticated
- `403 Forbidden` (`imAccessDenied`) when using a customer-scoped token, or a session without an IM-eligible role
- `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization
- `403 Forbidden` (`imTeamWriteDenied`) (add only) when your role is not `admin` and you are not a team admin of the schedule's team
- `404 Not Found` (`imScheduleNotFound`) when `:id` does not exist, or belongs to another organization
- `400 Bad Request` (`invalidRequestBody`) (add only) when `userId` is missing, `startsAt`/`endsAt` is missing or not a valid timestamp, or `startsAt` is not strictly before `endsAt`
- `404 Not Found` (`userNotFound`) (add only) when `userId` does not belong to your organization