Rank meeting times for the participants (per-participant timezones)

Reading another user’s connected calendar is logged for that user (GET /api/me/availability-lookups) and limited per viewer (429 lookup_limit); an owner can block a viewer (POST /api/me/availability-blocks). Merges live free/busy per participant: their own connected calendar (source "self"), hand-marked slots (source "manual": the owner-proven ones, plus those marked through the caller’s own ask-links), or the host’s view (source "host"). Calls without a connected host calendar (anonymous, or signed in but not connected) fall back to hand-marked slots only — participants with none are returned as source "host" (no data, may look free). Never fabricated. Ranking is per-participant timezone-aware (each filtered/scored in their own zone), scores buffer time around existing meetings and prefers sooner slots, and — when there are too few everyone-free slots — appends compromise slots (allFree:false). At most the 16 most-common participant timezones are evaluated per request (rarer zones fall back to the requester tz) to bound worst-case CPU.

post/api/availability

Request

  • Base URL: https://whenmeet.me
  • URL: https://whenmeet.me/api/availability
  • Auth: one of:
    • HTTP bearer
    • API key in cookie __Host-session

Request body

participantsstring[] required

Up to 50 distinct emails (trimmed, lower-cased, deduped).

frominteger required

Window start, unix ms.

tointeger required

Window end, unix ms: after from, at most 366 days after it and at most 60 days from now.

durationMin15 | 30 | 45 | 60

Optional; anything else falls back to 30.

tzstring

Requester IANA zone: fallback for participants whose own zone is unknown, plus the round-hour scoring bonus.

turnstileTokenstring

Cloudflare Turnstile token. Only needed after a 403 turnstile_required (browser sessions past 15 new foreign addresses in the rolling hour); a valid token exempts the session for one hour. PATs and MCP never need it.

Response

availability[] (busy intervals per participant), slots[] (ranked; allFree:true everyone-free first, then allFree:false compromise slots; capped to the first 90 days of the window), participantSources[] (per-participant tz only for authenticated callers; calendarStatus "unavailable" when a connected calendar could not be read — a token that needs re-auth, a provider error, or an owner who blocked you — and that participant is then treated as busy for the whole window, never as free), source: "real", cached.

Changes

No recorded changes to this operation across all 1 revision of this API.