Space
Markdown 版把一个最终用户或一个项目的数据隔开的 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 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevSpace[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevCreateSpaceRequest
| 字段 | 类型 | 说明 |
|---|---|---|
name必填 | string | Space 的名称,1 到 512 个字符。长度 1 到 512 |
description | string | Space 的用途,1 到 4096 个字符。长度 1 到 4096 |
external_id | string | 你为这个 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 |
响应
201application/jsonDevSpace
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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"}'响应结构示例
{
"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必填 | 路径 | DevSpaceRef | Space id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256 |
响应
200application/jsonDevSpace
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 原样返回。
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 新建 Space 的名称,默认为 external_id。长度 1 到 512 |
description | string | 新建 Space 的描述。长度 1 到 4096 |
响应
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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"}'响应结构示例
{
"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必填 | 路径 | DevSpaceRef | Space 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 | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevUpdateSpaceRequest 至少传一个字段。null 清空描述或 external_id。
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 新名字,1 到 512 个字符。长度 1 到 512 |
description | string | null | 新的描述;传 null 清空。长度 1 到 4096 |
external_id | string | null | 新的 external_id,1 到 256 个字符;传入 null 清空。已被占用时返回 409 space_external_id_taken。长度 1 到 256 |
响应
200application/jsonDevSpace
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'响应结构示例
{
"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必填 | 路径 | DevSpaceRef | Space 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 | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
响应
200application/jsonDevSpaceDeletion
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X DELETE "https://api.mirabase.dev/v2/spaces/$SPACE_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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必填 | 路径 | DevSpaceRef | Space 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 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevSpaceMember[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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必填 | 路径 | DevSpaceRef | Space 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 | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevSetSpaceMemberRequest
| 字段 | 类型 | 说明 |
|---|---|---|
role必填 | editor | viewer | editor 可以写,viewer 只能读。所有者身份不在这里授予。 |
write_mode | DevWriteMode | 新成员默认 proposal;已有成员不传时保留现值。 |
write_root | string | null | 将该成员的写入范围限制在某个已有目录及其子树下。权限只会收窄:角色、能力和 Key 的限制照常生效,读取不受影响,且成员不能重命名、移动或删除该目录本身。不传时保持现值;传入 null 或 / 取消限制。目录不存在时返回 404 not_found,路径指向文件时返回 409 not_a_directory,两者均带 field: write_root。范围外的写入返回 403 outside_write_root,写入没有路径的 Entry 同样返回该错误(成员自己的 Agent 记忆除外)。长度 1 到 8192 |
read_root | string | 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 |
响应
200application/jsonDevSpaceMember
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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"}'响应结构示例
{
"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必填 | 路径 | DevSpaceRef | Space 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 -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必填 | 路径 | DevSpaceRef | Space id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256 |
响应
200application/jsonDevSpaceProcessing
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/processing" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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"
}