On-Call Schedules API

Create and manage on-call schedules through the Ionhour API — rotations, participants, and overrides, plus querying who is currently on call for any given team.

On-call schedules define who is responsible for responding to incidents at any given time. See On-Call Schedules for conceptual documentation.

These are dashboard API endpoints — they require an OAuth session token ($ACCESS_TOKEN) and do not accept ionh_ API keys. On-call schedules currently have no API-key surface (neither the Integration API nor MCP exposes them); manage them from the dashboard. See which credential goes where.

Create Schedule

POST /on-call-schedules

Request Body

Field	Type	Required	Description
`workspaceId`	number	Yes	Workspace this schedule belongs to
`name`	string	Yes	Schedule name
`description`	string	No	Schedule description
`timezone`	string	No	Timezone for handoff times (default: `UTC`)
`handoffNotificationMinutes`	number	No	Minutes before handoff to notify incoming person (default: 15, `null` to disable)
`enabled`	boolean	No	Whether the schedule is active (default: true)
`rotations`	array	No	Rotations to create with the schedule (see below)

Rotation Object

Field	Type	Required	Description
`name`	string	No	Rotation name
`type`	string	Yes	`daily`, `weekly`, or `custom`
`layerPosition`	number	Yes	Priority within the schedule (0 = highest)
`effectiveFrom`	string	Yes	ISO datetime when this rotation starts
`effectiveUntil`	string	No	ISO datetime when this rotation ends (`null` = indefinite)
`handoffTime`	string	Yes	Time of day for shift changes (e.g., `09:00`)
`handoffDay`	number	No	Day of week for weekly rotations (1=Mon, 7=Sun, default: 1)
`customShiftHours`	number	No	Shift length in hours for `custom` rotations
`participants`	array	No	Ordered list of participants (see below)

Participant Object

Field	Type	Required	Description
`userId`	number	Yes	User to include in the rotation
`position`	number	Yes	Order in the rotation (0-indexed)

Example

curl -X POST https://api.ionhour.com/api/on-call-schedules \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": 1,
    "name": "Primary On-Call",
    "timezone": "America/New_York",
    "handoffNotificationMinutes": 15,
    "rotations": [
      {
        "name": "Weekly Rotation",
        "type": "weekly",
        "layerPosition": 0,
        "effectiveFrom": "2025-01-06T09:00:00Z",
        "handoffTime": "09:00",
        "handoffDay": 1,
        "participants": [
          { "userId": 1, "position": 0 },
          { "userId": 2, "position": 1 },
          { "userId": 3, "position": 2 }
        ]
      }
    ]
  }'

List Schedules

GET /on-call-schedules

Query Parameters

Parameter	Type	Required	Description
`workspaceId`	number	Yes	Filter by workspace

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.ionhour.com/api/on-call-schedules?workspaceId=1"

Get Schedule

GET /on-call-schedules/:id

Returns a schedule with its rotations, participants, and overrides.

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.ionhour.com/api/on-call-schedules/1

Update Schedule

PUT /on-call-schedules/:id

curl -X PUT https://api.ionhour.com/api/on-call-schedules/1 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Schedule", "timezone": "Europe/London"}'

Delete Schedule

DELETE /on-call-schedules/:id

curl -X DELETE https://api.ionhour.com/api/on-call-schedules/1 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Overrides

Create Override

POST /on-call-overrides

Field	Type	Required	Description
`scheduleId`	number	Yes	Schedule to override
`overrideUserId`	number	Yes	User who will cover
`startAt`	string	Yes	ISO datetime when override begins
`endAt`	string	Yes	ISO datetime when override ends
`replacedUserId`	number	No	User being replaced (`null` = unconditional override)
`reason`	string	No	Reason for the override

curl -X POST https://api.ionhour.com/api/on-call-overrides \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduleId": 1,
    "overrideUserId": 5,
    "replacedUserId": 2,
    "startAt": "2025-03-10T09:00:00Z",
    "endAt": "2025-03-17T09:00:00Z",
    "reason": "Alice on vacation"
  }'

Delete Override

DELETE /on-call-overrides/:id

curl -X DELETE https://api.ionhour.com/api/on-call-overrides/3 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

On-Call Schedules API

On this page