Schedule Overrides

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: 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)

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

Response

200 OK

[
  {
    "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

Example (cURL)

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