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

目录树

Markdown 版

列出 Space 的目录树,以及创建、移动、复制、删除和恢复路径。

列出目录

GET/v2/spaces/{space_id}/tree

列出一个目录,或返回一个文件。有 read_root 的成员只能看到该目录及其下属路径:其他路径(包括 / 和 read_root 之上的目录)都返回 404 not_found。GET /v2/spaces/{space_id} 会显示你的 read_root。带 snapshot 时列出快照里的内容:目录是快照里文件所在的目录,changes_cursor 是快照的游标;两种列表的翻页游标不能混用。需要 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
path查询DevPathSpace 内的绝对路径:以 / 开头,名字之间用单个 / 连接,结尾不带 /。最多 64 层、4096 字节,单个名字最多 255 字节。名称按 NFKC 和大小写折叠比较,并保留写入时的拼写。不允许 .、..、控制字符、反斜杠和首尾空白。/.mirabase/ 是保留路径,/.mirabase/skills/<name>/... 除外。路径超出这些限制时返回 422 path_too_long。长度 1 到 4096
recursive查询booleantrue 列出 path 的全部后代,而不是只列直接子节点。
branch查询DevBranchRef代替主线使用的分支:分支 id,或活跃分支的名称。在这个 Space 设有 read_root 的成员,对任何分支都返回 403 outside_read_root。
snapshot查询DevSnapshotRef快照 id 或名称。路径、版本和 read_root 均按创建快照时的状态判断;文件当前也必须对你可见。
cursor查询DevCursor上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024
limit查询integer每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20

响应

错误状态

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

请求示例

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

响应结构示例

json
{
  "data": [
    {
      "path": "/notes/hello.md",
      "name": "research",
      "kind": "dir",
      "updated_at": "2026-11-06T00:00:00Z"
    }
  ],
  "changes_cursor": "<cursor>"
}

执行目录操作

POST/v2/spaces/{space_id}/tree/operations

在一次请求中创建目录,以及移动、复制、删除和恢复路径:1 到 200 个操作,按顺序应用,全部生效或全部不生效。一个请求最多删除、恢复或复制 200 个节点,最多移动 1000 个。子树超过同步上限时返回 409 subtree_too_large。带 Prefer: respond-async 时,只含一条 move、copy、递归 delete 或按 delete_batch_id 的 restore 的请求超过上限,会改为异步任务执行,最多 10000 个节点:返回 202,带 job_id、Location 和 Preference-Applied: respond-async。能提前完成的校验都在任务创建前完成;每一批都会重新校验权限,因此吊销 Key 或移除成员会使任务停止。任务中的 move 在一个事务内完成;delete、restore 和 copy 每批 200 个节点,不是原子操作。一个 Space 同时最多运行 4 个修改目录树的任务,导出另计 4 个,超出时返回 429 too_many_jobs。copy 在 copies 中返回新的 Entry。有 write_root 的成员只能修改其下的节点(403 outside_write_root);删除的目录本身是或包含任何成员的 write_root 时返回 409 directory_is_write_root,Space 所有者也一样。有 read_root 的成员在 from 或 path 位于范围外时返回 404,目标在写入根路径外时返回 403 outside_write_root,无论目标处是否存在内容;删除的目录本身是或包含某个成员的 read_root 时返回 409 directory_is_read_root。需要 knowledge:write。

需要的能力 knowledge:write

指南:文件与版本

参数

名称位置类型说明
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。
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512
Prefer请求头stringrespond-async:只有一条操作、本该返回 409 subtree_too_large 的请求改为异步任务执行,返回 202 DevJobReceipt。没超过上限时照常执行,不带 Preference-Applied;多条操作超过上限返回 422 validation_error,field: "Prefer"。其他偏好会被忽略。

请求体

application/json DevTreeOperationsRequest 原子执行:全部按顺序生效,或全部不生效。一次请求最多删除、恢复或复制 200 个节点,最多移动 1000 个。带 branch 时 restore 和 copy 返回 422(请改为回滚到检查点)。

字段类型说明
operations必填DevTreeOperation[]1 到 200 个操作,按顺序执行。1 到 200 项

响应

响应头

  • Location /v2/jobs/{job_id}:轮询它,直到 status 变成 succeeded 或 failed。
  • Preference-Applied respond-async。

错误状态

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

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/tree/operations" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"op":"mkdir","path":"/notes/drafts"}]}'

响应结构示例

json
{}