API 优先的日程安排：你的日历是数据库，不是 app

大多数日程安排工具把界面当作产品本身。日历活在 app 里，想要接触到它的唯一办法就是登录然后点击。如果你想做一些设计师没有想到的事情——把下周的会议拉进你的 weekly review、从 CSV 自动生成 office hours、让同事的 Raycast 扩展替你预约——你就会被卡住。

WhenToMeet 的看法刚好相反。日历是一个数据库。界面只是它的一个视图。如果你想要另一个视图，自己写一个。

这就是 v1 REST API 存在的意义。

API 里有什么

/api/v1/ 下的 v1 表面有意做得很小，只覆盖大家真正会去自动化的东西：

• Events —— 列出、读取、创建 scheduling poll 和 direct event。/api/v1/polls
• Bookings —— 读取通过你的 booking page 进来的预约。/api/v1/bookings
• Calendar events —— 跨所有你已连接日历的统一视图，再加上你自己的 scheduling event 和 booking。/api/v1/calendar/events
• 冲突检查 —— 询问一个提议的时段是否和你已有的安排冲突
• Profile —— 获取你自己的用户资料、时区、订阅层级和偏好

认证方式是 Bearer token。你在账户设置里生成一把 sk_… 开头的 key,以 Authorization: Bearer sk_… 发送,就进来了。每个 endpoint 都有 scope,一把 key 只能看到它有权限看到的东西。

我们提供 OpenAPI spec。docs.whentomeet.io 上的文档列出了每个 endpoint 的请求和响应形状,你可以直接把它喂给代码生成器,在你本来就在用的语言里拿到一个 typed client。

为什么要 Pro 才能用

API 访问是 Pro 功能。坦诚的原因是:API 是一个支持面——key 会泄漏、脚本会死循环、rate limit 会被打爆——我们宁愿把这份支持好好地留给真正需要它的人,而不是稀薄地摊给所有免费账户。Rate limit 是按 key 计的,对正常自动化场景刻意放得很宽松。你做一个每周 digest,不会触及它。

它改变了什么

一旦日历是一个真正的 endpoint,它原来制造的工作就消失在脚本里:

• 实习生不用再把下周的会议手动搬进团队 wiki,cron job 帮你做了。
• 你不用再把 booking 通知转发到 CRM,一个 webhook 风格的 poll 把它们写进去。
• Engineering lead 不再是那个 scheduling PM,一个共享脚本一行命令就把每周 standup 建出来。

这些从精神上都不新——开发者用 API 把 SaaS 粘在一起已经十五年了。新的部分是,日程安排工具过去一直拒绝进入这堆里。你只有 Calendly 这个产品,别的都没有。有了真正的 API,产品就变成众多客户端之一。

如果你要构建点什么

从 docs.whentomeet.io 开始,生成一把 key,用它调 GET /api/v1/polls,你会看到自己的 scheduling poll 以 JSON 返回。剩下的一切都是从这里开始组合出来的。

如果你宁愿把钥匙交给一个 agent,而不是自己写脚本——Claude、ChatGPT、Cursor——那么 /api/mcp 下的 MCP 服务器把同样的 endpoint 包装进一个这些客户端已经会讲的协议里。相同的认证,相同的 rate limit。下一篇我们会讲这个。