APIEscalation

On-Call Schedules API

On-call schedules define who is responsible for responding to escalated incidents at any point in time. Escalation policies reference schedules to determine notification targets at each escalation level. Schedules support rotation layers and temporary overrides for vacations or swaps.

Endpoints

Method	Path	Description
GET	/schedules	List all on-call schedules for the tenant
POST	/schedules	Create a new on-call schedule with rotation layers
PUT	/schedules/{id}	Update schedule layers, timezone, or overrides
DELETE	/schedules/{id}	Delete a schedule (fails if referenced by escalation policy)
GET	/schedules/{id}/current-oncall	Get the user currently on-call for this schedule

Schedule Object

Schedule Response Object

{
  "id": "sched_ops_primary",
  "name": "Primary On-Call Rotation",
  "timezone": "America/New_York",
  "layers": [
    {
      "user_ids": ["user_alice", "user_bob", "user_charlie"],
      "rotation_type": "weekly",
      "start_time": "2024-01-01T09:00:00"
    }
  ],
  "overrides": [
    {
      "user_id": "user_dave",
      "start": "2024-03-10T00:00:00Z",
      "end": "2024-03-17T00:00:00Z",
      "reason": "Alice on vacation"
    }
  ]
}

Schedule Fields Reference

Field	Type	Description
timezone	string (IANA)	Timezone for interpreting rotation start times (e.g., `America/New_York`)
layers	array	Ordered rotation layers. Each layer defines a pool of users and rotation frequency.
layers[].user_ids	string[]	Ordered list of user IDs in the rotation pool
layers[].rotation_type	string	Either `daily` or `weekly`
layers[].start_time	string (ISO 8601)	The anchor datetime for calculating rotation position
overrides	array	Temporary on-call assignments that override the rotation for a time range

Current On-Call Response

GET /schedules/{id}/current-oncall

{
  "schedule_id": "sched_ops_primary",
  "current_oncall": {
    "user_id": "user_bob",
    "name": "Bob Smith",
    "email": "bob@acme.com",
    "on_call_since": "2024-03-04T09:00:00-05:00",
    "on_call_until": "2024-03-11T09:00:00-05:00",
    "source": "layer"
  }
}

Override Priority

When an override is active, the source field in the current-oncall response will be "override" instead of "layer". Overrides always take precedence over the rotation schedule.