docs

schedule.pizza has one public object: a booking link. The link contains the username and the booking code. If you have it, you can read availability, book a slot, or ask the scheduler to find a time across several people. If you do not have it, username guesses should not expose availability.

Agents can pass the full link as url, or split it into user and code. Times are UTC ISO strings ending in Z.

hosts

Sign in with Google, choose a username, and share the generated booking link. New links are shown once. If a host loses the code, they create a new link and the old code stops working. Confirmed bookings appear in the dashboard. Individual bookings can be cancelled there. Group bookings stay visible, but the group organizer cancels the shared event from Google Calendar.

one person

Start with availability. Slots exclude schedule.pizza bookings and the host's Google Calendar busy times.

GET /api/v1/availability?user=alice&code=moon-tiger-seven

Then book the exact slot returned by availability. The server checks the code again and rejects the write if the slot is no longer free. A booking succeeds only after the Google Calendar event is created.

POST /api/v1/book
{
  "user": "alice",
  "code": "moon-tiger-seven",
  "slot": "2030-01-07T17:00:00.000Z",
  "name": "Ada",
  "email": "ada@example.com",
  "timezone": "America/Los_Angeles"
}

Email is required so Google can invite the booker. Public booking responses return the schedule.pizza booking id, not the Google event id.

several people

Send every participant with their booking link. The scheduler returns exact slots when everyone is free. If none exist, it returns ranked recommendations with the conflicting people and time ranges. Google event details stay private.

For people, use group scheduling and paste one schedule.pizza link per line. For agents, call the API directly. Requests are capped at eight people and a 31-day window.

POST /api/v1/schedule
{
  "participants": [
    { "user": "alice", "code": "moon-tiger-seven" },
    { "user": "bob", "code": "river-lime-harbor" }
  ],
  "durationMinutes": 30,
  "granularityMinutes": 15,
  "maxExactSlotCount": 10,
  "maxAlternativeSlotCount": 5,
  "timeZone": "America/Los_Angeles",
  "window": {
    "start": "2030-01-07T17:00:00.000Z",
    "end": "2030-01-08T01:00:00.000Z"
  }
}

POST /api/v1/recommend accepts the same body. It returns exact slots first. A response with kind: "exact" means everyone is free. A response with kind: "alternatives" is ranked by conflict cost. Lower is better.

To book an exact group slot, send the same scheduling body to /api/v1/book-group with the selected slot and booker identity.

POST /api/v1/book-group
{
  "participants": [
    { "user": "alice", "code": "moon-tiger-seven" },
    { "user": "bob", "code": "river-lime-harbor" }
  ],
  "durationMinutes": 30,
  "granularityMinutes": 15,
  "maxExactSlotCount": 10,
  "maxAlternativeSlotCount": 5,
  "timeZone": "America/Los_Angeles",
  "window": {
    "start": "2030-01-07T17:00:00.000Z",
    "end": "2030-01-08T01:00:00.000Z"
  },
  "slot": "2030-01-07T18:00:00.000Z",
  "name": "Ada",
  "email": "ada@example.com",
  "timezone": "America/Los_Angeles"
}

host agents

A signed-in host can read account state at GET /api/v1/account. Upcoming bookings are available at GET /api/v1/account/bookings. Each booking includes kind and a structured cancel object, so agents can tell individual bookings from shared group bookings. To update a host profile, call PUT /api/v1/account/profile. Renaming a profile revokes previous codes and returns a new bookingUrl. When a host creates or rotates a booking code, account responses include the absolute bookingUrl that can be handed to people or agents. Later account reads do not return the plaintext code. Account mutations require the Better Auth cookie and a same-site Origin header. To cancel an upcoming individual booking, call POST /api/v1/account/bookings/:bookingId/cancel.

Account mutation header:
Origin: https://schedule.pizza

POST /api/v1/me/bootstrap
{
  "username": "alice",
  "timezone": "America/Los_Angeles",
  "displayName": "Alice",
  "slotSizeMinutes": 30,
  "calendarId": "primary"
}

PUT /api/v1/account/profile
{
  "username": "alice",
  "timezone": "America/Los_Angeles",
  "displayName": "Alice",
  "slotSizeMinutes": 30,
  "calendarId": "primary"
}

POST /api/v1/me/booking-code

GET /api/v1/account/bookings
POST /api/v1/account/bookings/booking_123/cancel

failure model

Public calls fail closed with typed error codes. Missing or wrong booking codes return 404. Stale slots return 409. Calendar access problems return typed Google Calendar errors. The host fixes those by reconnecting Google from the dashboard.