> ## Documentation Index
> Fetch the complete documentation index at: https://docs.happyuptime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Schedules

Create and manage on-call schedules.

# On-Call schedules

A **schedule** owns one or more **layers**. Each layer is an independent rotation; layers stack to model Primary / Secondary / Manager / etc.

## List schedules

GET `/oncall/schedules`

```bash
curl https://happyuptime.com/api/v1/oncall/schedules \
  -H "Authorization: Bearer hu_your_api_key"
```

```json
{
  "data": [
    {
      "id": "sch_abc123",
      "name": "Engineering On-Call",
      "description": "24/7 production",
      "layer_count": 3,
      "current_oncall": [
        { "layer": "Primary", "user_id": "usr_alice", "name": "Alice" },
        { "layer": "Secondary", "user_id": "usr_bob", "name": "Bob" }
      ],
      "created_at": "2026-04-01T00:00:00Z"
    }
  ]
}
```

## Get schedule

GET `/oncall/schedules/{id}`

Returns the schedule with all layers and members nested.

```json
{
  "data": {
    "id": "sch_abc123",
    "name": "Engineering On-Call",
    "layers": [
      {
        "id": "lyr_p1",
        "position": 0,
        "name": "Primary",
        "rotation_type": "weekly",
        "timezone": "America/New_York",
        "handoff_day": 1,
        "handoff_hour": 9,
        "restriction_type": "none",
        "members": [
          { "user_id": "usr_alice", "position": 0 },
          { "user_id": "usr_bob", "position": 1 }
        ]
      }
    ]
  }
}
```

## Create schedule

POST `/oncall/schedules`

Schedule name.

Optional description.

Array of layer objects (see [Layers](/api/oncall/layers)). Minimum one layer.

```json
{
  "name": "Engineering On-Call",
  "layers": [
    {
      "name": "Primary",
      "rotation_type": "weekly",
      "timezone": "America/New_York",
      "handoff_day": 1,
      "handoff_hour": 9,
      "members": ["usr_alice", "usr_bob", "usr_carol"]
    }
  ]
}
```

## Update schedule

PATCH `/oncall/schedules/{id}`

Updates name/description. Layer changes go through `/layers` endpoints.

## Delete schedule

DELETE `/oncall/schedules/{id}`

Cascades to layers, members, fixed shifts, and overrides.

## Current on-call

GET `/oncall/schedules/{id}/current`

Resolves the current on-call person for every layer.

```json
{
  "data": [
    {
      "layer_id": "lyr_p1",
      "layer_name": "Primary",
      "user": { "id": "usr_alice", "name": "Alice", "slack_id": "U01ABCD" },
      "reason": "rotation",
      "shift_ends_at": "2026-04-22T13:00:00Z"
    }
  ]
}
```

`reason` is one of `override`, `fixed_shift`, `rotation`, or `none` (no one on call).