SaveSlot 文档

开发者

HTTP API 参考

基础地址与版本

https://api.saveslot.ai/v1

版本写在路径里。不兼容的改动升新版本；只增不改的改动（新字段、新接口）不升版本。

鉴权

每个请求都带 Bearer 令牌：

Authorization: Bearer <token>
令牌谁用能访问
API Key（ss_ro_…、ss_rw_…）你自己的后端一个 Slot，只读或读写
OAuth 访问令牌用户授权过的应用用户批准的 Slot 和权限。见 OAuth 应用

请求超出令牌范围时：看不到的 Slot 返回 404，不允许的操作返回 403。这样令牌不会探知它没被授权的 Slot。

错误

错误统一用一种格式：

{
  "error": {
    "code": "read_only",
    "message": "This key can only read slot “Health”.",
    "request_id": "req_8f2c…",
    "retry_after": null
  }
}
状态码code什么时候
400invalid_request请求体或参数格式不对；message 写明是哪个字段
401unauthenticated令牌缺失、过期或已吊销
403read_only、forbidden_scope令牌不能在这里写，或没有「新建表」「删除数据」权限
404not_found对这个令牌来说，Slot、表或记录不存在
409conflict、version_mismatch你读取之后记录被改过，或记录处在未解决的冲突中
422official_table试图修改官方表的结构
429rate_limited请求太多，等 retry_after 秒再试
5xxserver_error退避后重试；联系支持时附上 request_id

工作台把每个错误码映射成用户能照着做的提示，失败时总会显示 request_id。

分页

列表接口返回一页内容和总数：

{ "items": [ … ], "page": 1, "page_size": 20, "total": 255 }

查询参数：page（从 1 开始）和 page_size。记录按时间倒序。

并发与重试

  • 每条记录都有 version。纠正时带上 If-Match: <version>；版本过期返回 409 version_mismatch。
  • 所有 POST 请求带 Idempotency-Key: <uuid>。用同一个 key 重复请求，返回第一次的结果，不会重复创建。

时间与金额

  • 时间用带时区偏移的 ISO 8601（2026-11-15T07:40:00-08:00）。工作台按用户的时区和语言格式化；API 从不返回「1 小时前」这类展示文字。
  • 金额是最小货币单位的整数加币种：{ "amount": 800, "currency": "usd" }。

资源

Slot

方法与路径用途
GET /slots令牌能访问的 Slot
GET /slots/{slot}单个 Slot，含它的表和扩展

表

方法与路径用途
GET /slots/{slot}/tables表的字段、类型（官方、Agent 建、派生）和记录数
POST /slots/{slot}/tables新建表（需要「新建表」权限）
POST /slots/{slot}/tables/{table}/recompute重算派生表

记录

方法与路径用途
GET /slots/{slot}/tables/{table}/records?q=&trust=&page=搜索、按可信度筛选、翻页
POST /slots/{slot}/tables/{table}/records新增记录
PATCH /slots/{slot}/tables/{table}/records/{id}纠正记录，新增一个版本
GET …/records/{id}/history全部版本
POST …/records/{id}/restore恢复第 n 个版本，新增一个版本
POST …/records/{id}/resolve用选定的选项处理冲突
DELETE …/records/{id}删除（需要「删除数据」权限）；不带 confirm=true 时先返回预览

一条记录长这样：

{
  "id": "rec_m2",
  "values": { "time": "2026-11-12T19:30:00-08:00", "what": "Beef noodles", "calories": 650 },
  "trust": "inferred",
  "sources": [{ "kind": "agent", "name": "Claude · Web" }],
  "version": 3,
  "written_at": "2026-11-12T19:31:04-08:00",
  "conflict": null
}

trust 取 confirmed、inferred、unknown、conflicted 之一。trust 为 conflicted 时，conflict.options 列出每个候选值及其来源和时间。

页面

方法与路径用途
GET /slots/{slot}/pagesSlot 里的页面
GET /pages/{page}页面本身、声明的查询和版本
DELETE /pages/{page}删除 Agent 页面；默认页面不能删

活动与用量

方法与路径用途
GET /slots/{slot}/activity?range=&actor=&kind=&failures_only=活动事件
GET /usage本周期的调用量，按天、按连接

给研发的待定问题 草案