# 主体

账户中的人和 Agent，以及各自可持有的能力。

API 参考。Base URL：`https://api.mirabase.dev`

## 列出主体

`GET /v2/principals`

本租户的主体，按 id 排序。需要 `tenant_admin`，且 Key 不受 Space 限制。不需要任何能力。

**需要的能力** 不检查能力。

指南：[权限](https://mirabase.io/zh/developers/permissions.md#narrowing)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevPrincipal[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

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

### 响应结构示例

```json
{
  "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`](https://mirabase.io/zh/developers/api/usage.md#usage-limits)），超出返回 409 `tenant_limit_reached`。不需要任何能力。

**需要的能力** 不检查能力。

指南：[权限](https://mirabase.io/zh/developers/permissions.md#principals)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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`，人没有任何能力。 |

### 响应

- `201` `application/json` `DevPrincipal`

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl -X POST "https://api.mirabase.dev/v2/principals" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"human"}'
```

### 响应结构示例

```json
{
  "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 |

### 响应

- `200` `application/json` `DevPrincipal`

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
curl "https://api.mirabase.dev/v2/principals/$PRINCIPAL_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "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[]` | 必填 | 替换该主体的能力。你必须持有此列表中的全部能力，以及该主体现有的全部能力。 |

### 响应

- `200` `application/json` `DevPrincipal`

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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"]}'
```

### 响应结构示例

```json
{
  "id": "<id>",
  "kind": "human",
  "roles": [
    "<roles>"
  ],
  "capabilities": [
    "knowledge:read"
  ],
  "created_at": "2026-11-06T00:00:00Z"
}
```
