Schedules & On-Call

An on-call schedule maps a time-series onto a rotating set of users. Escalation-policy steps reference schedules; at dispatch time, the schedule resolves to whoever is on-call right now.

Endpoints

Method	Path	Description	Scope
GET	/api/v1/schedules	List schedules.	schedules
POST	/api/v1/schedules	Create.	schedules
GET	/api/v1/schedules/{id}	Read.	schedules
PATCH	/api/v1/schedules/{id}	Update (metadata + layers).	schedules
DELETE	/api/v1/schedules/{id}	Delete. Fails if referenced by a policy.	schedules
GET	/api/v1/schedules/{id}/on-call	Who is on-call at at=<timestamp> (default now).	schedules
POST	/api/v1/schedules/{id}/overrides	Create a temporary override.	schedules
DELETE	/api/v1/schedules/{id}/overrides/{overrideID}	Cancel an override.	schedules

Schedule document

{
  "id": "01HXSCHED...",
  "name": "Platform primary",
  "timezone": "America/Los_Angeles",
  "layers": [
    {
      "name": "Weekday business hours",
      "rotation_type": "weekly",
      "start_at": "2026-01-06T09:00:00-08:00",
      "handoff_time": "Mon 09:00",
      "participants": ["usr_alice", "usr_bob", "usr_carol"],
      "restrictions": [
        {"days": ["mon","tue","wed","thu","fri"], "start": "09:00", "end": "17:00"}
      ]
    },
    {
      "name": "After-hours",
      "rotation_type": "daily",
      "participants": ["usr_dave", "usr_eve"]
    }
  ]
}

Layers are evaluated top-to-bottom at the at timestamp; the first matching layer wins. A restriction-less layer is the catch-all fallback.

Who’s on-call?

GET /api/v1/schedules/{id}/on-call?at=2026-04-24T19:00:00Z

{
  "data": {
    "schedule_id": "01HXSCHED...",
    "at": "2026-04-24T19:00:00Z",
    "user_id": "usr_dave",
    "user_email": "[email protected]",
    "layer": "After-hours",
    "until": "2026-04-25T19:00:00Z"
  }
}

If the schedule has no one on-call at that time (all layers empty), the field user_id is null and callers relying on the schedule’s target-resolution fall through to the next escalation step.

Overrides

POST /api/v1/schedules/{id}/overrides
{
  "user_id": "usr_frank",
  "start_at": "2026-04-25T00:00:00Z",
  "end_at":   "2026-04-25T08:00:00Z",
  "reason": "Alice PTO; covering."
}

Overrides take precedence over the layer rotation for the overlap window. Call DELETE to cancel before the override ends.