← Home

The rota — who answers when nobody is you

Beeper pages one human. That is the whole point. But a fleet of agents pages at any hour, and one human cannot be awake at three in the morning. The rota (BIP-F-37) is how a page finds the right person, in the right order, without losing the 1995 promise: one line, one tap, and a refusal if nobody answers.

you ──▶ agent pages the rota "night"
               │
               ▼
        who holds the pager now?
               │
        ┌──────┴──────┐
        ▼             ▼
     Alice          (nobody forgot her)
     rings          escalate_after_ms
                       │
                       ▼
                     Bob rings
                       │
                       ▼
                 nobody left → the page expires (a refusal)

The three parts

Build a rota

Pair the pagers first (GET /v1/devices lists the ids). Then:

# 1. the rota — 2 minutes per on-call before it escalates
curl -X POST https://central/v1/rotas -H "Authorization: Bearer $TOKEN" \
  -d '{"label":"night","escalate_after_seconds":120}'
# → { "rota_id": "rt_…", "label": "night", … }

# 2. the on-call humans, in escalation order (priority defaults to the end)
curl -X POST https://central/v1/rotas/rt_…/shifts -H "Authorization: Bearer $TOKEN" \
  -d '{"alias":"alice","target":"dev_alice"}'
curl -X POST https://central/v1/rotas/rt_…/shifts -H "Authorization: Bearer $TOKEN" \
  -d '{"alias":"bob","target":"dev_bob"}'

Page the rota

Any page request may name a rota. POST /page keeps its one-line simplicity:

curl -X POST https://central/page -H "Authorization: Bearer $TOKEN" \
  -d '{"message":"release 1.2.0 blocked on push","priority":"critical","rota":"night"}'

or the full shape on POST /v1/pages with "rota":"night". If the label is unknown, or nobody is on call, the answer is 422 — an agent never pages into the void.

What decided who holds the pager

Three rules, in order:

  1. A window — a shift whose starts_at/ends_at contains the moment (a day shift 07:00–22:00, a night shift 22:00–07:00).
  2. A rotation — with rotation_ms set, the pager changes hands every N milliseconds, in list order, from the rota's creation.
  3. The list — otherwise the first shift is on call, and the whole rota is the escalation order.

Escalation is a move, not a state change

When the window runs out, the page stays delivered — it simply moves to the next device:

There is no wrap: Alice, then Bob, then the page expires unanswered — a refusal, exactly like every other page nobody answers (BIP-F-07). An agent never gets a silent "maybe" from an exhausted rota.

Revoke in one gesture

curl -X DELETE https://central/v1/rotas/rt_…      # removes the rota and its shifts
curl -X DELETE https://central/v1/rotas/rt_…/shifts/sh_…   # one shift

Both write rota.changed to the audit log. Nothing is ever edited in place: a rota is a sequence of written facts.