WhenToMeet LogoWhenToMeet
Sign In

API-first scheduling: your calendar is a database, not an app

Most scheduling tools treat the UI as the product. The calendar lives inside the app, and the only way to get at it is to log in and click. If you want to do something the designer didn't imagine — pull next week's meetings into a weekly review, auto-create office hours from a CSV, have a coworker's Raycast extension book something for you — you're stuck.

WhenToMeet takes the other view. The calendar is a database. The UI is one view of it. If you want another view, write one.

That's what the v1 REST API is for.

What's in the API

The v1 surface at /api/v1/ is small on purpose. It covers the things people actually automate:

  • Events — list, read, and create scheduling polls and direct events. /api/v1/polls
  • Bookings — read the appointments that came in through your booking pages. /api/v1/bookings
  • Calendar events — a unified view across every calendar you've connected, plus your own scheduling events and bookings. /api/v1/calendar/events
  • Conflict checks — ask whether a proposed time range collides with anything you already have
  • Profile — fetch your own user profile, timezone, tier, and settings

Authentication is a Bearer token. You generate an sk_… key from your account settings, send it as Authorization: Bearer sk_…, and you're in. Every endpoint is scoped so a key only sees what it's permitted to.

There's an OpenAPI spec. The docs at docs.whentomeet.io list every endpoint with request and response shapes, so you can point a code generator at it and get a typed client in the language you already use.

Why Pro-gated

API access is a Pro feature. The honest reason is that an API is a support surface — keys leak, scripts loop, rate limits get hit — and we'd rather support that carefully for the people who actually need it than spread it thin across free accounts. Rate limits are per-key and intentionally relaxed for normal automation. You will not hit them by building a weekly digest.

What this changes

Once the calendar is a real endpoint, the work it used to cause disappears into scripts:

  • The intern no longer copies next week's meetings into the team wiki. A cron job does.
  • You don't forward booking notifications to your CRM. A webhook-style poll writes them.
  • The engineering lead isn't the scheduling PM anymore. A shared script creates the weekly standup with one command.

None of this is new in spirit — developers have been gluing SaaS together with APIs for fifteen years. The new part is that scheduling tools historically refused to be in that pile. You had Calendly the product and nothing else. With a real API, the product becomes one client among many.

If you're building something

Start at docs.whentomeet.io, generate a key, call GET /api/v1/polls with it, and you'll see your own scheduling polls come back as JSON. Everything else is composition from there.

If you want to hand the keys to an agent instead of writing the script yourself — Claude, ChatGPT, Cursor — the MCP server at /api/mcp wraps the same endpoints in a protocol those clients already speak. Same auth, same rate limits. We'll cover that in the next post.