# WhenWhen

> Group scheduling without the sign-up. An organizer proposes time slots, participants
> answer Yes / If needed / No through one shared link, and the organizer locks in the
> winner. Anyone with the link can then add it to their calendar. No account is
> needed to create, vote, or
> finalize; no ads, no tracking, no analytics scripts. The only third-party code that
> ever loads is the Cloudflare Turnstile widget on the create page.

WhenWhen is built to be operated by software agents as well as people. Every capability
in the web UI is reachable over plain JSON, and participation needs no credential at all:
capability URLs are the authorization model.

- The **share link** (`/e/{eventId}`) authorizes reading the event and voting.
- The **edit token** returned when you vote authorizes changing that submission.
- The **admin token** returned when you create authorizes finalize, reopen and delete.
- A **view token** is needed as well on the few events an organizer has password protected.
  Those answer 403 with `"code": "locked"` on every read, calendar download and vote until you
  POST the password to `/api/events/{eventId}/unlock` and send the token it returns as an
  `X-View-Token` header. Holding the share link alone gets you the 403 and nothing else: no
  title, no times, no participants.

An agent handed a share link can vote on its owner's behalf immediately - no OAuth, no
consent screen, no account. Only *creating* an event is gated, because a scheduling link
on a trusted domain would otherwise be a phishing vector. Browsers pass that gate with a
Turnstile widget; agents pass it with `Authorization: Bearer ww_...` and an API token
minted from an account page. Your agent needs credentials; your invitees never do.

## API

- [OpenAPI 3.1 description](https://whenwhen.io/api/openapi.json): the complete machine-readable spec. Start here.
- [Developer & agent guide](https://whenwhen.io/developers): authorization model, worked example, limits.
- [Health check](https://whenwhen.io/api/health): liveness probe, returns epoch seconds.

Conventions: JSON is camelCase; every timestamp is epoch **seconds**; every non-2xx body
is `{"error": "...", "code": "..."}` and you should branch on `code`; every 429 carries a
`Retry-After` header in seconds; request bodies are capped at 64KB.

## Limits

- Anonymous ("Instant"): 10 time slots per event, 100 participants, 10-day lifetime. Cannot edit an event after creating it.
- Free account: 25 time slots, 250 participants, 30-day lifetime, and can add or remove time slots after sharing.
- Pro: 100 time slots, 1000 participants, 365-day lifetime, locking in several slots at once, and password-protecting an event.

Finalizing and the calendar invite (.ics, Google, Outlook) are free on every tier - they
are not a paid upsell here.

## Pages

- [Home](https://whenwhen.io/): what it is, how it works.
- [Pricing](https://whenwhen.io/pricing): plan comparison and FAQ.
- [Privacy](https://whenwhen.io/privacy): what is stored and for how long.
- [Terms](https://whenwhen.io/terms)
- [Refunds](https://whenwhen.io/terms#refunds)

## Optional

- [Sign in](https://whenwhen.io/dashboard): an account raises the limits above and issues API tokens. Participants never need one.
- API tokens: free accounts include 1, Pro includes 5. A token creates events at its account's tier and meters against the account's daily budget rather than a shared IP one.
- Events created anonymously can be moved into an account: POST https://whenwhen.io/api/events/claim with their admin tokens and they join it and gain its lifetime. Lifetimes only ever extend, so moving up a tier lengthens events you already have and cancelling shortens nothing.

## Contact

- support@whenwhen.io