API reference v1 Developer beta

╭─────────────╮   Bearer sbk_…    ┌──────────────────────────────────┐
│ your app /  │ ────────────────▶ │  schedule-bit API  (v1)          │
│ SDK / curl  │ ◀──────────────── │  ▓ one World = one Durable Object│
╰─────────────╯   JSON / 409      └──────────────────────────────────┘
       ▲                                  │ after every commit
       │ WebSocket (live)                 ▼
       └──────────────────────── ┄┄ events ┄┄▶ signed webhooks

LAYER          WHAT IT IS                       API SURFACE
─────────────  ───────────────────────────────  ────────────────────────
schedule-bit   binary planes: slots as bits     presets, offered, positions
planes         occupiers, door, record, watch   occupiers, claims, journal
relay          one job through many Worlds      hands, relays, asks

                                 R   W      L  what it gives you
─────────────────────────────────────────────────────────────────────
WORLDS
  create a World (a resource)        ●      create a resource with a preset
  list / describe                ●          preset · seats · head hash
PRESETS
  temporal-hour  (day → 24 h)    ●          positions by date
  temporal-minute (hour → 60 m)  ●          positions by date + hour
OCCUPIERS
  holders · events · series      ●   ●      who can hold, with rank/pinned
  capacity (seats)                   ●      N may hold one slot at once
THE DOOR
  claim                              ●      receipt or refusal, never both
  claim:explain                  ●          judge without writing
  soft hold (until …)                ●      intent that lapses by the clock
  confirm · give-up · queue          ●      firm up, let go, wait in line
  release · handover                 ●      give back, pass on in one act
  displace (by rank)                 ●      loser told, offered elsewhere
  sweep                              ●      lapse overdue soft holds
READING
  offered                        ●          free slots at a position
  holdings                       ●          held + soft slots of one party
  journal ?since=                ●          sealed commits, hash-chained
RELAYS
  take a hand in                     ●      copy another World's busy-ness
  lay a relay (legs, gaps, after)    ●      one job, many hands, ordered
  windows                        ●          every start where all legs fit
  ask · sync · withdraw · delegate   ●      the four acts on a relay
  standing + possible            ●          where it stands, what's next
ASKS (a hand's inbox)
  list asks                      ●          what planners want of you
  answer: accept / reject /          ●      your yes, no, take-back,
          takeBack / moveTo                 or counter-slot
EVENTS
  watch (WebSocket)                         ●  every commit, as it lands
  webhooks (signed, retried)         ●      ●  ask.received, ask.answered…

{ "type": "https://schedule-bit.dev/problems/refused/held", "title": "Refused", "status": 409,
  "detail": "slots 10 are held by alice",
  "refusal": { "by": "held", "conflictsWith": ["alice"], "slots": "0x400", "outranked": true, "pinned": false } }

POST /claims {who, date, slots}
        │
        ▼
   ╱ stopped series? ╲──yes──▶ 409 stopped
   ╲                 ╱
        │no
   ╱ held by others?  ╲──yes──▶ outranks? ──no──▶ 409 held (by whom)
   ╲                  ╱                    │yes
        │no                                ▼
   ╱ capacity left?   ╲──no──▶ 409   displace + offer loser a slot
   ╲                  ╱                    │
        │yes                               │
   ╱ own rules pass?  ╲──no──▶ 409 rule / rest / horizon
   ╲                  ╱                    │
        │yes ◀─────────────────────────────┘
        ▼
   201 receipt {slots, displaced[], commitSeq, head}
        └──▶ one sealed commit in the journal

{ "wrote": "0x600", "slots": [9, 10],
  "displaced": [{ "occupier": "bob", "slots": [9], "offered": { "parametric": 2026, "coordinates": [9, 1], "slots": [11] } }],
  "commitSeq": 4, "head": "20fc4842bffb6b9b0341187cd5c99583" }

 planner World                       maker        printer       courier
 ──────────────                      ─────        ───────       ───────
 take in hands     ◀── busy-ness ──   ●            ●             ●
 lay relay: 4h ─2─▶ 2h ─3─▶ 1h
 windows?  → starts 9,10,11,12   (one AND over every hand's free bits)
 ask @ 9   ─────── ask ────────────▶  ●  ───────▶  ●  ─────────▶ ●
                                   accept       reject        accept
 sync      ◀────── answers ─────────  held         refused       held
 delegate leg 1 ── ask ──────────────────────▶ printer2 → accept
 sync      → ▓ all held ▓
 withdraw  → every hand's slots come free again

EVENT            HAPPENS WHEN                     WATCH (WS)  WEBHOOK
───────────────  ───────────────────────────────  ──────────  ───────
commit           any act wrote to the record          ●          ─
claim.made       a claim went through the door        ●          ●
claim.released   slots given back                     ●          ●
ask.received     a planner's ask reached you          ●          ●
ask.withdrawn    a planner took its ask back          ●          ●
ask.answered     you answered (planner may sync)      ●          ●
relay.acted      a relay asked/synced/withdrew…       ●          ●

async function verify(secret: string, body: string, header: string): Promise<boolean> {
  const [, t, v1] = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header) ?? [];
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret),
    { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
  const mac = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${t}.${body}`));
  return [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, '0')).join('') === v1;
}

                  worlds  door  relays  asks  events
auth (API keys)     ●      ●      ●      ●      ●     scoped read/write
workspace walls     ●      ●      ●      ●      ●     no cross-tenant
idempotency         ●      ●      ●      ●      ─     Idempotency-Key
audit (journal)     ─      ●      ●      ●      ─     hash-chained
tamper check        ●      ●      ●      ●      ─     replay must match head
metering            ●      ●      ●      ●      ─     per workspace/route

U=https://schedule-bit-api-dev.khaled-mailhub.workers.dev; K=sbk_…
H=(-H "authorization: Bearer $K" -H 'content-type: application/json')

curl "${H[@]}" -X POST $U/v1/worlds -d '{"name":"room-1","allowDisplace":true}'
curl "${H[@]}" -X POST $U/v1/worlds/room-1/occupiers -d '{"name":"alice","rank":1}'
curl "${H[@]}" -H 'idempotency-key: c-1' -X POST $U/v1/worlds/room-1/claims \
     -d '{"who":"alice","date":"2026-10-01","slots":[9,10]}'
curl "${H[@]}" "$U/v1/worlds/room-1/offered?date=2026-10-01"
curl "${H[@]}" "$U/v1/worlds/room-1/journal"