Keeper.sh REST API 完全参考:/api/v1 的 13 个端点与 API Token(kpr_)认证实战指南

原创2026-10-11 17:23:011,702 阅读

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 日历同步与聚合平台概览

为什么需要 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),支持三种凭证,优先级从高到低:

  1. API Token:Authorization: Bearer kpr_...
  2. MCP 会话:由 MCP 服务签发的会话令牌
  3. 浏览器 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"

认证流程内部会做三件事:

  1. 将 Bearer Token 做 SHA-256 哈希后与数据库比对,并校验 expiresAt 是否过期
  2. 命中后更新该 Token 的 lastUsedAt 时间戳,方便排查"这个 Token 最近有没有被调用"
  3. 执行每日调用量限流

💡 限流规则:免费用户每日 25 次 API 调用,超出返回 429 Too Many Requests;Pro 用户不限量。实现见 api-rate-limit.ts。

Keeper.sh 仪表盘界面展示

核心查询端点详解

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。

Keeper.sh 日历同步功能界面

事件写入端点:创建、修改、删除

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 的完整生命周期(创建 → 调用 → 限流 → 吊销)都已覆盖,可以开始搭建你自己的日历自动化流水线了。

登录后查看全文
keeper.sh