跳到主要内容
开发者文档
文档目录

变更流

Markdown 版

Space 的有序变更流,以及近期活动的汇总。

查看近期由谁做了哪些修改

GET/v2/spaces/{space_id}/activity

将最近 days 天的变更流按主体和 Entry 汇总。在共享 Space 中开始工作前可先读取此接口,了解其他成员的近期修改,避免同时编辑同一文件。最多回看最近 1000 条变更(若该时段内变更超过 1000 条,truncated 为 true),每个主体最多列出 50 个 Entry。可见范围与 changes 一致:设有 read_root 的成员仅能看到该目录下的变更。仅支持主线。需要 knowledge:read。

需要的能力 knowledge:read

指南:同步、快照与导出

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
days查询integer回看的天数,1 到 30。1 到 30,默认 7

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/activity" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "since": "2026-11-06T00:00:00Z",
  "truncated": false,
  "data": [
    {
      "last_changed_at": "2026-11-06T00:00:00Z",
      "change_count": 1,
      "files": [
        {
          "entry_id": "<entry_id>",
          "op": "create",
          "changed_at": "2026-11-06T00:00:00Z",
          "change_count": 1
        }
      ]
    }
  ]
}

读取变更流

GET/v2/spaces/{space_id}/changes

读取按顺序排列的变更流,保留 90 天。过期的游标返回 410 cursor_expired,请使用 tree 重新同步。传入 branch 时响应为 DevBranchChangeFeed,仅接受从 tree?branch= 获取的该分支游标。设有 read_root 的成员仅能看到该范围内的事件:移入该范围的文件记为 create,移出的文件记为不含 path 的 delete。单页先读取最多 limit 条事件再过滤,因此 has_more 为 true 时 data 也可能少于 limit 条甚至为空;传入 wait 时,过滤后为空的页面会继续等待。需要 knowledge:read。

需要的能力 knowledge:read

指南:同步、快照与导出

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
branch查询DevBranchRef代替主线使用的分支:分支 id,或活跃分支的名称。在这个 Space 设有 read_root 的成员,对任何分支都返回 403 outside_read_root。
cursor查询DevCursor起始游标:上一次响应的 cursor,或 tree、快照返回的 changes_cursor。不传则从当前时刻开始。长度 1 到 1024
wait查询integer没有事件时长轮询等待的秒数。一个 Key 最多同时保持 4 个长轮询请求,超出时返回 429 too_many_waiters。0 到 30
limit查询integer单次最多读取的事件数:1 到 100,默认 100。1 到 100,默认 100

响应

错误状态

400 401 403 404 410 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/changes" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "data": [
    {
      "seq": 1,
      "op": "create",
      "entry_id": "<entry_id>",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ],
  "cursor": "<cursor>",
  "has_more": false
}