---
title: "Update an on-call schedule"
method: PUT
path: "/api/v1/schedules/{schedule}"
tags: ["On-call schedules"]
---

# Update an on-call schedule

`PUT /api/v1/schedules/{schedule}`

## Request

- Base URL: `https://wardenpoint.com` (the document declares no server; this is the origin it was published from)
- URL: `https://wardenpoint.com/api/v1/schedules/{schedule}`
- Auth: API key in header `X-API-Key`

Changes only the fields present in the body; an omitted field is left alone, it is not reset to a default. Shifts that already exist are never rewritten — a new timezone or handoff moment applies from the next rotation generation, so fixing a typo in the name cannot move everybody's duty. PATCH is accepted on the same path with identical semantics.

## Path parameters

- `schedule` string, uuid, required

## Request body

- ScheduleUpdateRequest: Every field is optional and an omitted field means "leave as is" — there are no defaults on update. Renaming a schedule therefore cannot reset its timezone, and cannot switch a deliberately disabled rotation back on.
  - `name` string: New display name. Nothing enforces uniqueness on update: a name another schedule of this company already uses is accepted, and you end up with two schedules sharing a name. Create behaves differently — it hands back the existing schedule rather than making a twin — so a create issued afterwards with that shared name resolves to the older of the two.
  - `timezone` string: IANA zone name. The new handoff position applies to rotations generated after this call; existing shifts keep the exact instants they already have. Their rendered boundaries do move, though — they are returned in the schedule timezone, so changing it re-reads the same moments in the new zone.
  - `default_handoff_day_of_week` integer: ISO-8601 weekday: 1 = Monday … 7 = Sunday.
  - `default_handoff_hour` integer: Hour of the weekly handoff, in the schedule's own timezone. Takes effect on the next rotation generated; shifts already on the calendar are not moved.
  - `default_handoff_minute` integer: Minute of the weekly handoff. Same as the hour: it positions future rotations, never existing shifts.
  - `is_active` boolean: False takes the schedule out of escalation targeting without deleting anything.

## Response `200`

The updated schedule.

- object
  - `data` Schedule: One rotation. The iCal subscription link and its revocation token are deliberately absent from every API response: that URL is a bearer credential for the whole roster and is issued only in the dashboard, by a human. Ask GET /api/v1/schedules/{schedule}/on-call or /shifts instead — they answer from the same resolver the feed renders from.
    - `uuid` string, uuid
    - `name` string
    - `timezone` string: IANA zone name, e.g. "Europe/Warsaw". Two things depend on it: the weekly handoff moment below is placed in this zone (so a DST change does not shift it), and shift and handover boundaries are RENDERED in it — a handoff set for 09:00 answers `09:00+02:00`. Changing it moves nothing in the database: existing shifts keep the very instants they had, and the new handoff position applies from the next rotation generation. Their rendered wall-clock does change, because it is now read in the new zone — the same instant, told differently.
    - `handoff` object: When the weekly baton passes, expressed in the schedule's own timezone. The rotation generator starts each week here, so a DST transition never moves the wake-up boundary.
      - `day_of_week` integer: ISO-8601 weekday: 1 = Monday … 7 = Sunday.
      - `hour` integer
      - `minute` integer
    - `is_active` boolean: An inactive schedule is skipped by escalation steps that target it — they fall through to the next target or to the step's fallback recipient. Shifts and overrides are kept.
    - `on_call` ScheduleOnCall: Who is on duty per role at the moment asked about. A role with nobody on duty is absent from the object — an empty object means the rotation covers nobody right now.
      - `primary` object: First to be paged.
        - `uuid` string, uuid
        - `name` string
      - `secondary` object: Covers when primary does not acknowledge.
        - `uuid` string, uuid
        - `name` string
      - `manager` object: Operational escalation tier for prolonged incidents.
        - `uuid` string, uuid
        - `name` string
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `401`: API key missing, invalid, revoked or expired.
- `403`: API key lacks the config.write ability, or the schedule belongs to another company.
- `404`: No schedule with this UUID, or on-call schedules are switched off for this deployment.
- `422`: Validation failed — most often an unknown timezone name.

---

[API](https://skmtc.dev/wardenpoint/apis/wardenpoint-api.md) · [All operations](https://skmtc.dev/wardenpoint/apis/wardenpoint-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wardenpoint/apis/wardenpoint-api/revisions/259ee445728e?raw)