Keeper.sh REST API 完全参考:/api/v1 的 13 个端点与 API Token(kpr_)认证实战指南
Keeper.sh REST API 完全参考:/api/v1 的 13 个端点与 API Token(kpr_)认证实战指南
Keeper.sh 是一款日历同步工具(Calendar sync tool & universal calendar MCP server),可以把 Google、Outlook、iCloud、CalDAV、ICS 等日历聚合到一个平台。它的 REST API 暴露在 /api/v1 路径下,提供 13 个端点方法,配合 kpr_ 前缀的 API Token 即可完成日历读取、事件创建、空闲时段查询等自动化操作,是编写脚本和接入 AI Agent 的理想入口。
为什么需要 Keeper.sh REST API
传统方式里,想跨多个日历系统查询"我下周哪天有空",需要分别对接 Google Calendar API、Microsoft Graph、CalDAV 协议,鉴权方式各不相同。Keeper.sh 把这些差异屏蔽了:
- 统一读模型:所有提供商的事件归一化为同一 JSON 结构
- 统一鉴权:一个 API Token 访问你名下所有日历
- 空闲时段计算:
free-time端点直接返回可预约的时间段,无需自己写冲突检测
下面按"先拿 Token → 再调端点"的顺序实战。
第一步:创建 API Token(kpr_)
在 Keeper.sh 网页端登录状态下,调用 Token 管理路由即可生成新令牌:
| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/api/tokens |
创建 Token,请求体 {"name": "my-bot"} |
GET |
/api/tokens |
列出当前所有 Token |
DELETE |
/api/tokens/{id} |
吊销指定 Token |
创建成功后,响应体中会一次性返回完整令牌:
{
"id": "clx8...",
"name": "my-bot",
"tokenPrefix": "kpr_ab12cd34ef56",
"token": "kpr_ab12cd34ef56...",
"createdAt": "2026-10-01T08:00:00.000Z"
}
请注意:
- 令牌以
kpr_开头,后接 32 字节随机数的十六进制串,生成逻辑见 api-tokens.ts - 服务端只存储 SHA-256 哈希值,不保存明文,因此
token字段丢失后只能删除重建 - Token 列表接口只会回显前 12 位
tokenPrefix,用于在控制台辨认令牌
认证方式:Bearer Token 实战
所有 /api/v1 端点统一走 withV1Auth 中间件(见 middleware.ts),支持三种凭证,优先级从高到低:
- API Token:
Authorization: Bearer kpr_... - MCP 会话:由 MCP 服务签发的会话令牌
- 浏览器 Session:网页端的登录 Cookie
用 curl 调用时的标准写法:
curl -H "Authorization: Bearer kpr_ab12cd34ef56..." \
"https://api.keeper.sh/api/v1/events?from=2026-10-12T00:00:00Z&to=2026-10-19T00:00:00Z"
认证流程内部会做三件事:
- 将 Bearer Token 做 SHA-256 哈希后与数据库比对,并校验
expiresAt是否过期 - 命中后更新该 Token 的
lastUsedAt时间戳,方便排查"这个 Token 最近有没有被调用" - 执行每日调用量限流
💡 限流规则:免费用户每日 25 次 API 调用,超出返回
429 Too Many Requests;Pro 用户不限量。实现见 api-rate-limit.ts。
核心查询端点详解
GET /api/v1/accounts — 查看已连接的日历账户
返回所有已授权账户(Google、Outlook、iCloud、CalDAV 等),支持 provider 参数过滤:
GET /api/v1/accounts?provider=google
每个账户包含 email、calendarCount(日历数)、needsReauthentication(是否需要重新授权)等字段,适合在脚本中做健康检查。路由源码:accounts/index.ts。
GET /api/v1/calendars — 列出所有日历
GET /api/v1/calendars?provider=google,icloud
返回结构极简,每条日历只有 id、name、provider、account 四个字段,id 会在后续所有端点中作为 calendarId 使用。
GET /api/v1/events — 按时间范围查询事件 ⭐
最常用的端点,源码见 events/index.ts。完整查询参数:
| 参数 | 说明 |
|---|---|
from / to |
ISO 时间,缺省为"现在起一周",最大跨度 732 天 |
calendarId |
逗号分隔的日历 ID,可多选 |
availability |
按 busy / free 过滤 |
isAllDay |
true/false 过滤全天事件 |
count=true |
只返回 { "count": N },不拉取事件体 |
# 只统计未来两周的忙碌事件数量
curl -H "Authorization: Bearer kpr_..." \
"https://api.keeper.sh/api/v1/events?from=2026-10-12T00:00:00Z&to=2026-10-26T00:00:00Z&count=true"
日期范围校验逻辑在 date-range.ts:from 必须早于 to,否则返回 400。
GET /api/v1/events/free-time — 自动找空闲时段
预约场景的核心端点,参数见 free-time.ts:
| 参数 | 必填 | 说明 |
|---|---|---|
from / to |
是 | 搜索窗口 |
durationMinutes |
是 | 需要的连续空闲分钟数 |
timezone |
是 | 时区,如 Asia/Shanghai |
workingHoursStart / workingHoursEnd |
否 | 工作时间,如 09:00 / 18:00 |
workingDays |
否 | 工作日,如 1,2,3,4,5 |
limit |
否 | 最多返回几个时段 |
calendarId |
否 | 只在指定日历上计算冲突 |
ignoreAllDayEvents |
否 | 全天事件是否算作占用 |
其他日历级端点
| 方法 | 路径 | 用途 |
|---|---|---|
PATCH |
/api/v1/calendars/{calendarId} |
暂停/恢复某个日历同步,请求体 {"paused": true} |
GET |
/api/v1/calendars/{calendarId}/invites |
查询指定时间范围内待处理的会议邀请 |
GET |
/api/v1/ical |
获取该用户的 ICS 订阅地址,可直接喂给任意日历客户端 |
POST |
/api/v1/sync |
手动触发一次全量同步;有冷却时间,节流时返回 Retry-After 头 |
日历暂停与会议邀请端点分别见 calendars/[calendarId]/index.ts](services/api/src/routes/api/v1/calendars/%5BcalendarId%5D/index.ts) 与 [invites.ts。
事件写入端点:创建、修改、删除
POST /api/v1/events — 创建事件
必填字段为 calendarId、title、startTime、endTime,可选 description、location、isAllDay、availability、timezone。成功返回 201 Created。
curl -X POST -H "Authorization: Bearer kpr_..." -H "Content-Type: application/json" \
-d '{
"calendarId": "cal_abc123",
"title": "产品评审会",
"startTime": "2026-10-15T10:00:00+08:00",
"endTime": "2026-10-15T11:00:00+08:00",
"timezone": "Asia/Shanghai",
"availability": "busy"
}' \
https://api.keeper.sh/api/v1/events
GET / PATCH / DELETE /api/v1/events/{id}
单事件端点提供完整的 CRUD(源码见 events/[id].ts):
- GET:按 ID 取单个事件详情
- PATCH:更新标题、时间、地点等字段;特别地,传
{"rsvpStatus": "yes"}可直接回复会议邀请 - DELETE:删除事件,成功返回
204 No Content
⚠️ 对支持双向同步的日历(如 Google、Outlook),通过 API 写入的变更会在下次同步时推送回源端,请谨慎使用删除操作。
常见错误码速查
| 状态码 | 场景 | 处理建议 |
|---|---|---|
400 |
缺少必填字段 / 日期范围非法 / 跨度超 732 天 | 检查请求体与时间参数 |
401 |
Token 无效、已删除或已过期 | 重新创建 API Token |
404 |
日历/事件 ID 不存在 | 先用 GET /api/v1/calendars 核对 ID |
429 |
超出免费额度(25 次/日)或同步冷却 | 读取 Retry-After 头后重试,或升级 Pro |
小结与实战建议
- 脚本/CI 场景:用
kpr_Token 走 Bearer 认证,避免依赖浏览器 Cookie - AI Agent 场景:Keeper.sh 本身还提供 universal calendar MCP server,
withV1Auth对 MCP 会话令牌同样放行,两种接入方式可并存 - 先
GET /api/v1/accounts做健康检查,再按"列日历 → 查事件 → 找空档 → 建事件"的链路编排自动化 - 关注 429 响应头,把重试策略写进你的客户端
至此,/api/v1 的 13 个端点方法与 kpr_ Token 的完整生命周期(创建 → 调用 → 限流 → 吊销)都已覆盖,可以开始搭建你自己的日历自动化流水线了。


