账户中的人和 Agent,以及各自可持有的能力。
列出主体
GET/v2/principals
本租户的主体,按 id 排序。需要 tenant_admin,且 Key 不受 Space 限制。不需要任何能力。
需要的能力 不检查能力。
指南:权限
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
cursor | 查询 | DevCursor | 上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024 |
limit | 查询 | integer | 每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevPrincipal[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/principals" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"data": [
{
"id": "<id>",
"kind": "human",
"roles": [
"<roles>"
],
"capabilities": [
"knowledge:read"
],
"created_at": "2026-11-06T00:00:00Z"
}
]
}创建主体
POST/v2/principals
创建主体。Agent 有自己的 ACL、记忆和审计身份。需要 tenant_admin。一个账户最多有 tenant_principals 个主体(见 GET /v2/limits),超出返回 409 tenant_limit_reached。不需要任何能力。
需要的能力 不检查能力。
指南:权限
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevCreatePrincipalRequest
| 字段 | 类型 | 说明 |
|---|---|---|
kind必填 | DevPrincipalKind | 主体类型:人(human)或 Agent(agent)。 |
grant_capabilities | DevCapability[] | 要授予的能力,不能超过你持有的能力。不传时 Agent 获得 knowledge:read,人没有任何能力。 |
响应
201application/jsonDevPrincipal
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X POST "https://api.mirabase.dev/v2/principals" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind":"human"}'响应结构示例
{
"id": "<id>",
"kind": "human",
"roles": [
"<roles>"
],
"capabilities": [
"knowledge:read"
],
"created_at": "2026-11-06T00:00:00Z"
}读取主体
GET/v2/principals/{principal_id}
读取一个主体。需要 tenant_admin,且 Key 不受 Space 限制。本租户没有的 id 返回 404 not_found。不需要任何能力。
需要的能力 不检查能力。
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
principal_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
响应
200application/jsonDevPrincipal
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/principals/$PRINCIPAL_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"id": "<id>",
"kind": "human",
"roles": [
"<roles>"
],
"capabilities": [
"knowledge:read"
],
"created_at": "2026-11-06T00:00:00Z"
}修改主体能力
PATCH/v2/principals/{principal_id}
用 grant_capabilities 整体替换主体的能力:列表中没有的能力会被收回。受 Space 限制的 Key 不能调用。变更会写入审计日志。在有团队的账户中,Admin 的权限取决于归属关系:不能对 Owner 或其他 Admin 执行这些操作;对其他成员只能修改能力或吊销 Key,不能签发或轮换 Key;只能管理自己创建的 Agent 和最终用户。其他操作返回 403 forbidden;已移除的成员不能执行任何此类操作。需要 tenant_admin 角色,不需要任何能力。
需要的能力 不检查能力。
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
principal_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevUpdatePrincipalRequest
| 字段 | 类型 | 说明 |
|---|---|---|
grant_capabilities必填 | DevCapability[] | 替换该主体的能力。你必须持有此列表中的全部能力,以及该主体现有的全部能力。 |
响应
200application/jsonDevPrincipal
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X PATCH "https://api.mirabase.dev/v2/principals/$PRINCIPAL_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"grant_capabilities":["knowledge:read"]}'响应结构示例
{
"id": "<id>",
"kind": "human",
"roles": [
"<roles>"
],
"capabilities": [
"knowledge:read"
],
"created_at": "2026-11-06T00:00:00Z"
}