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

把一个最终用户或一个项目的数据隔开的 Space,以及 Space 的成员。

列出 Space

GET/v2/spaces

调用方可见的 Space,按 id 倒序排列。需要 knowledge:read。每个 Space 带有调用方自己的 write_root 和 read_root(仅在设置时返回)。带 external_id 时,结果只有带这个 id 的那一个 Space;没有这个 Space 或调用方看不到它时,结果为空。

需要的能力 knowledge:read

指南:核心概念

参数

名称位置类型说明
cursor查询DevCursor上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024
limit查询integer每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20
external_id查询string只返回带有该 external_id(你为该 Space 设定的 id)的 Space:零个或一个。长度 1 到 256

响应

  • 200 application/json
字段类型说明
data必填DevSpace[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

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

请求示例

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

响应结构示例

json
{
  "data": [
    {
      "id": "<id>",
      "name": "research",
      "is_default": false,
      "access_role": "owner",
      "created_at": "2026-11-06T00:00:00Z",
      "updated_at": "2026-11-06T00:00:00Z"
    }
  ]
}

创建 Space

POST/v2/spaces

创建 Space。一个账户最多可创建 tenant_spaces 个 Space(见 GET /v2/limits),达到上限时返回 409 tenant_limit_reached;删除 Space 会释放名额。每个最终用户或项目各用一个 Space,以隔离数据。需要 knowledge:manage。

需要的能力 knowledge:manage

指南:核心概念

参数

名称位置类型说明
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevCreateSpaceRequest

字段类型说明
name必填stringSpace 的名称,1 到 512 个字符。长度 1 到 512
descriptionstringSpace 的用途,1 到 4096 个字符。长度 1 到 4096
external_idstring你为这个 Space 设定的 id,1 到 256 个字符,例如其数据所属最终用户的 id。之后用 GET /v2/spaces?external_id= 或路径 ext:<external_id> 查找该 Space,无需保存 Mirabase 生成的 id。在账户的所有 Space 中唯一:已被占用时返回 409 space_external_id_taken(field: external_id)。删除该 Space 后可再次使用。长度 1 到 256

响应

错误状态

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

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/spaces" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace","external_id":"user-42"}'

响应结构示例

json
{
  "id": "col_01JD2M7QK3",
  "name": "Ada Lovelace",
  "external_id": "user-42",
  "is_default": false,
  "access_role": "owner",
  "created_at": "2026-11-17T08:00:00Z",
  "updated_at": "2026-11-17T08:00:00Z"
}

读取 Space

GET/v2/spaces/{space_id}

读取一个 Space。Space 不存在或调用方不可见时返回 404 not_found。需要 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

响应

错误状态

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

请求示例

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

响应结构示例

json
{
  "id": "col_01JD2M7QK3",
  "name": "Ada Lovelace",
  "external_id": "user-42",
  "is_default": false,
  "access_role": "owner",
  "created_at": "2026-11-17T08:00:00Z",
  "updated_at": "2026-11-17T08:00:00Z"
}

按你自己的 id 获取或创建 Space

PUT/v2/spaces/{space_id}

返回带有你为它设定的 id 的 Space,没有时创建一个。路径必须是 ext:<external_id>,例如 PUT /v2/spaces/ext:user-42;其他值返回 422。为新的最终用户首次写入之前调用一次即可,不需要先创建、捕获 409 再查找。你能看到的某个 Space 带有这个 external_id 时,返回 200 和这个 Space,请求体被忽略,这时需要 knowledge:read。没有这样的 Space 时,创建它并返回 201,这时需要 knowledge:manage,并且和 POST /v2/spaces 一样计入 tenant_spaces。两个请求同时到达时只创建一个 Space,两个请求都得到它。这个 id 被一个你看不到的 Space 占用时,返回 409 space_external_id_taken。请求体可以省略。重复发送这个请求是安全的。

需要的能力 视请求而定,见上面的说明。

指南:核心概念

参数

名称位置类型说明
space_id必填路径DevSpaceRef必须是 ext:<external_id>,例如 ext:user-42;其他值返回 422 validation_error。长度 1 到 256

请求体

application/json DevEnsureSpaceRequest 只在创建 Space 时使用;已有的 Space 原样返回。

字段类型说明
namestring新建 Space 的名称,默认为 external_id。长度 1 到 512
descriptionstring新建 Space 的描述。长度 1 到 4096

响应

错误状态

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

请求示例

curl
curl -X PUT "https://api.mirabase.dev/v2/spaces/ext:user-42" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace"}'

响应结构示例

json
{
  "id": "col_01JD2M7QK3",
  "name": "Ada Lovelace",
  "external_id": "user-42",
  "is_default": false,
  "access_role": "owner",
  "created_at": "2026-11-17T08:00:00Z",
  "updated_at": "2026-11-17T08:00:00Z"
}

修改 Space

PATCH/v2/spaces/{space_id}

修改 Space 的名称、描述或 external_id,至少传一项,传 null 清空 description 或 external_id。external_id 已被占用时返回 409 space_external_id_taken。需要 knowledge:manage。变更会写入审计日志。

需要的能力 knowledge:manage

参数

名称位置类型说明
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
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevUpdateSpaceRequest 至少传一个字段。null 清空描述或 external_id。

字段类型说明
namestring新名字,1 到 512 个字符。长度 1 到 512
descriptionstring | null新的描述;传 null 清空。长度 1 到 4096
external_idstring | null新的 external_id,1 到 256 个字符;传入 null 清空。已被占用时返回 409 space_external_id_taken。长度 1 到 256

响应

错误状态

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

请求示例

curl
curl -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

响应结构示例

json
{
  "id": "col_01JD2M7QK3",
  "name": "Ada Lovelace",
  "external_id": "user-42",
  "is_default": false,
  "access_role": "owner",
  "created_at": "2026-11-17T08:00:00Z",
  "updated_at": "2026-11-17T08:00:00Z"
}

删除 Space

DELETE/v2/spaces/{space_id}

删除一个 Space 及其中的全部内容:文件及其全部版本、写入的 Entry、记忆、分支、快照、Webhook 和成员关系。不可撤销。仅限 Space 所有者操作,且需要 knowledge:manage。 Space 立即移除:任何读取都不再返回它,不再占用 tenant_spaces 配额,其占用的存储也会从账户总量中扣除。内容本身在后台彻底删除,每个 Entry 的清除方式与 POST /v2/entries/{id}/purge 相同;entries 为删除时其中的 Entry 数量。 默认 Space 不可删除,否则返回 409 default_space_protected。Space 中有任务(目录树任务、导出、导入或合并)排队或运行时返回 409 job_in_flight 并附带 job_id,请等待该任务完成。传入 Idempotency-Key 时重复请求会获得首次请求的结果;不传时第二次删除返回 404。

需要的能力 knowledge:manage

指南:核心概念

参数

名称位置类型说明
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
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

响应

错误状态

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

请求示例

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

响应结构示例

json
{
  "space_id": "<space_id>",
  "deleted": true,
  "entries": 1
}

列出成员

GET/v2/spaces/{space_id}/members

Space 的成员及其角色、write_mode、write_root 和 read_root,按主体 id 排序。需要 knowledge:read,且调用方能看到这个 Space。只能读某个 read_root 的调用方,看不到其他成员落在它之外的根路径。

需要的能力 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
cursor查询DevCursor上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024
limit查询integer每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20

响应

  • 200 application/json
字段类型说明
data必填DevSpaceMember[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

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

请求示例

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

响应结构示例

json
{
  "data": [
    {
      "principal_id": "<principal_id>",
      "role": "owner",
      "write_mode": "proposal"
    }
  ]
}

设置成员

PUT/v2/spaces/{space_id}/members/{principal_id}

授予 Space 角色、写入模式、写入根路径和读取根路径。只有 Space 所有者能操作;所有者自己的成员关系不能改(409 owner_membership_immutable)。需要 knowledge:manage。

需要的能力 knowledge:manage

指南:权限

参数

名称位置类型说明
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
principal_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevSetSpaceMemberRequest

字段类型说明
role必填editor | viewereditor 可以写,viewer 只能读。所有者身份不在这里授予。
write_modeDevWriteMode新成员默认 proposal;已有成员不传时保留现值。
write_rootstring | null将该成员的写入范围限制在某个已有目录及其子树下。权限只会收窄:角色、能力和 Key 的限制照常生效,读取不受影响,且成员不能重命名、移动或删除该目录本身。不传时保持现值;传入 null 或 / 取消限制。目录不存在时返回 404 not_found,路径指向文件时返回 409 not_a_directory,两者均带 field: write_root。范围外的写入返回 403 outside_write_root,写入没有路径的 Entry 同样返回该错误(成员自己的 Agent 记忆除外)。长度 1 到 8192
read_rootstring | null把这个成员能读取的内容限制在一个已有目录及其下的所有内容。范围只会收窄:角色、能力和 Key 的限制照常生效。不传时保持现值;null 或 / 取消限制。目录不存在时,接口返回 404 not_found;路径指向文件时,接口返回 409 not_a_directory,两者都带 field: read_root。访问范围外的内容时,这个成员收到 404,如同内容不存在;没有路径的 Entry 也在范围外,成员自己的 Agent 记忆除外;访问这个 Space 的分支时,接口返回 403 outside_read_root。没有 write_root 时,成员在 read_root 下写入;write_root 必须是 read_root 或它下面的目录,否则接口返回 422 write_root_outside_read_root(field: write_root),新的 read_root 让现有的 write_root 落到范围外时也一样。长度 1 到 8192

响应

错误状态

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

请求示例

curl
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members/$PRINCIPAL_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"editor"}'

响应结构示例

json
{
  "principal_id": "<principal_id>",
  "role": "owner",
  "write_mode": "proposal"
}

移除成员

DELETE/v2/spaces/{space_id}/members/{principal_id}

移除成员。只有 Space 所有者能操作。移除非成员返回 404 not_found。所有者自己的成员关系不能移除:这时返回 409 owner_membership_immutable。需要 knowledge:manage。

需要的能力 knowledge:manage

参数

名称位置类型说明
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
principal_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

  • 204 无响应体

错误状态

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

请求示例

curl
curl -X DELETE "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members/$PRINCIPAL_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

读取 Space 的处理进度

GET/v2/spaces/{space_id}/processing

Space 的处理进度:正在排队、正在处理、可检索、已就绪和已失败的 Entry 数量,Entry 变为可检索的速率,以及其余 Entry 预计何时可检索。批量导入期间可轮询此接口,无需逐个读取 Entry。只统计调用方可见的 Entry。需要 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

响应

错误状态

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

请求示例

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

响应结构示例

json
{
  "space_id": "col_01JD2M7QK3",
  "counts": {
    "queued": 48,
    "processing": 4,
    "searchable": 60,
    "ready": 8,
    "failed": 0
  },
  "stages": {
    "queued": 48,
    "extracting": 1,
    "indexing": 3,
    "enriching": 60
  },
  "searchable_per_minute": 42.5,
  "eta_seconds": 74,
  "oldest_queued_seconds": 21,
  "waiting_for_capacity": true,
  "queue_position": 0,
  "memory": {
    "pending": 60,
    "eta_seconds": 90,
    "files": "index_only"
  },
  "as_of": "2026-11-17T08:00:00Z"
}