# API 参考

这份参考由 OpenAPI 规格生成。标“即将上线”的接口还不存在，不是稳定契约，上线前可能调整。标“需要部署开启”的接口属于部署可选功能，未开启的部署上返回 404。

- Base URL：`https://api.mirabase.dev`
- OpenAPI：https://api.mirabase.dev/v2/openapi.yaml
- 规格版本：`2.0.0`（33c172f77f2c）
- 状态：115 个已实现（默认部署），12 个已实现（部署可选），3 个即将上线

## 通用请求头

所有接口都接受下面的请求头。通过认证的响应都带 `RateLimit-Limit`、`RateLimit-Remaining` 和 `RateLimit-Reset`，见 [限流与限额](https://mirabase.io/zh/developers/conventions.md#rate-limits)。分页、幂等、条件请求、任务和错误的规则见 [API 约定](https://mirabase.io/zh/developers/conventions.md)，全部错误码见 [错误码](https://mirabase.io/zh/developers/errors.md)。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `Mirabase-Contract-Version` | `string` | 可选 | 要协商的契约版本。不传时使用当前兼容的契约。 |
| `X-Request-Id` | `string` | 可选 | 调用方关联 id；取值无效时替换为服务端签发的 id。 |

## 接口分组

### [身份](https://mirabase.io/zh/developers/api/identity.md)

- `GET /v2/whoami` 读取当前身份

### [API Key](https://mirabase.io/zh/developers/api/api-keys.md)

- `GET /v2/api-keys` 列出 API Key
- `POST /v2/api-keys` 创建 API Key
- `GET /v2/api-keys/{key_id}` 读取 API Key
- `DELETE /v2/api-keys/{key_id}` 吊销 API Key
- `POST /v2/api-keys/{key_id}/rotate` 轮换 API Key

### [主体](https://mirabase.io/zh/developers/api/principals.md)

- `GET /v2/principals` 列出主体
- `POST /v2/principals` 创建主体
- `GET /v2/principals/{principal_id}` 读取主体
- `PATCH /v2/principals/{principal_id}` 修改主体能力

### [Space](https://mirabase.io/zh/developers/api/spaces.md)

- `GET /v2/spaces` 列出 Space
- `POST /v2/spaces` 创建 Space
- `GET /v2/spaces/{space_id}` 读取 Space
- `PUT /v2/spaces/{space_id}` 按你自己的 id 获取或创建 Space
- `PATCH /v2/spaces/{space_id}` 修改 Space
- `DELETE /v2/spaces/{space_id}` 删除 Space
- `GET /v2/spaces/{space_id}/members` 列出成员
- `PUT /v2/spaces/{space_id}/members/{principal_id}` 设置成员
- `DELETE /v2/spaces/{space_id}/members/{principal_id}` 移除成员
- `GET /v2/spaces/{space_id}/processing` 读取 Space 的处理进度

### [文件](https://mirabase.io/zh/developers/api/files.md)

- `GET /v2/spaces/{space_id}/files` 读取文件
- `HEAD /v2/spaces/{space_id}/files` 读取文件响应头
- `PUT /v2/spaces/{space_id}/files` 写入文件
- `PATCH /v2/spaces/{space_id}/files` 修改文件文本
- `DELETE /v2/spaces/{space_id}/files` 删除文件
- `POST /v2/spaces/{space_id}/files/batch` 批量写入和删除
- `GET /v2/spaces/{space_id}/files/content-url` 获取文件下载地址
- `GET /v2/spaces/{space_id}/files/diff` 按路径比较版本
- `GET /v2/spaces/{space_id}/files/lineage` 按路径查看来源
- `POST /v2/spaces/{space_id}/files/revert` 按路径回滚
- `GET /v2/spaces/{space_id}/files/versions` 按路径列出版本

### [目录树](https://mirabase.io/zh/developers/api/tree.md)

- `GET /v2/spaces/{space_id}/tree` 列出目录
- `POST /v2/spaces/{space_id}/tree/operations` 执行目录操作

### [大文件上传](https://mirabase.io/zh/developers/api/uploads.md)

- `POST /v2/spaces/{space_id}/uploads` 发起大文件上传
- `POST /v2/uploads/{upload_id}/abort` 中止上传
- `POST /v2/uploads/{upload_id}/complete` 完成上传
- `POST /v2/uploads/{upload_id}/parts` 获取分片上传地址

### [变更流](https://mirabase.io/zh/developers/api/changes.md)

- `GET /v2/spaces/{space_id}/activity` 查看近期由谁做了哪些修改
- `GET /v2/spaces/{space_id}/changes` 读取变更流

### [提案](https://mirabase.io/zh/developers/api/proposals.md)

- `GET /v2/proposals/{proposal_id}` 读取提案
- `POST /v2/proposals/{proposal_id}/approve` 批准提案
- `GET /v2/proposals/{proposal_id}/diff` 查看提案改动
- `POST /v2/proposals/{proposal_id}/reject` 拒绝提案
- `POST /v2/proposals/{proposal_id}/withdraw` 撤回提案
- `GET /v2/spaces/{space_id}/proposals` 列出提案

### [快照](https://mirabase.io/zh/developers/api/snapshots.md)

- `GET /v2/snapshots/{snapshot_id}` 读取快照
- `DELETE /v2/snapshots/{snapshot_id}` 删除快照
- `GET /v2/spaces/{space_id}/snapshots` 列出快照
- `POST /v2/spaces/{space_id}/snapshots` 创建快照

### [Webhook](https://mirabase.io/zh/developers/api/webhooks.md)

- `GET /v2/spaces/{space_id}/webhooks` 列出 Webhook
- `POST /v2/spaces/{space_id}/webhooks` 创建 Webhook
- `GET /v2/webhooks/{webhook_id}` 读取 Webhook
- `PATCH /v2/webhooks/{webhook_id}` 修改 Webhook
- `DELETE /v2/webhooks/{webhook_id}` 删除 Webhook
- `GET /v2/webhooks/{webhook_id}/deliveries` 列出推送记录
- `POST /v2/webhooks/{webhook_id}/rotate-secret` 轮换 Webhook 密钥

### [导出与导入](https://mirabase.io/zh/developers/api/transfers.md)

- `GET /v2/jobs/{job_id}/content-url` 获取导出归档地址
- `POST /v2/spaces/{space_id}/exports` 导出 Space
- `POST /v2/spaces/{space_id}/forks` 复刻 Space（即将上线）
- `POST /v2/spaces/{space_id}/imports` 导入归档

### [导入](https://mirabase.io/zh/developers/api/ingest.md)

- `POST /v2/spaces/{space_id}/ingest` 导入网址、文本或对话

### [Entry](https://mirabase.io/zh/developers/api/entries.md)

- `GET /v2/entries` 列出 Entry
- `GET /v2/entries/{entry_id}` 读取 Entry
- `PATCH /v2/entries/{entry_id}` 修改 Entry
- `DELETE /v2/entries/{entry_id}` 将 Entry 移入废纸篓
- `GET /v2/entries/{entry_id}/content` 读取 Entry 内容
- `GET /v2/entries/{entry_id}/content-url` 获取 Entry 下载地址
- `GET /v2/entries/{entry_id}/copies` 列出副本（即将上线）
- `GET /v2/entries/{entry_id}/diff` 比较版本
- `GET /v2/entries/{entry_id}/lineage` 查看来源
- `GET /v2/entries/{entry_id}/processing` 读取处理状态
- `POST /v2/entries/{entry_id}/purge` 彻底删除 Entry
- `POST /v2/entries/{entry_id}/reprocess` 重新处理 Entry
- `POST /v2/entries/{entry_id}/restore` 恢复 Entry
- `POST /v2/entries/{entry_id}/revert` 回滚到旧版本
- `GET /v2/entries/{entry_id}/versions` 列出版本
- `GET /v2/entries/{entry_id}/versions/{version_id}` 读取版本
- `PATCH /v2/entries/{entry_id}/versions/{version_id}/message` 修改版本说明
- `POST /v2/spaces/{space_id}/trash/purge` 清空废纸篓

### [任务](https://mirabase.io/zh/developers/api/jobs.md)

- `GET /v2/jobs/{job_id}` 读取任务
- `POST /v2/jobs/{job_id}/cancel` 取消任务（即将上线）

### [检索](https://mirabase.io/zh/developers/api/retrieval.md)

- `POST /v2/retrieval/answer` 带引用回答
- `POST /v2/retrieval/context` 构建上下文
- `POST /v2/retrieval/context/{pack_id}/feedback` 发送上下文反馈
- `POST /v2/retrieval/search` 搜索

### [记忆](https://mirabase.io/zh/developers/api/memories.md)

- `GET /v2/memories` 列出记忆
- `POST /v2/memories` 写入记忆
- `GET /v2/memories/{memory_id}` 读取记忆
- `PATCH /v2/memories/{memory_id}` 修改记忆
- `DELETE /v2/memories/{memory_id}` 遗忘记忆
- `POST /v2/memories/{memory_id}/correct` 更正记忆
- `GET /v2/memories/{memory_id}/provenance` 查看记忆来源
- `POST /v2/memories/{memory_id}/review` 审核记忆
- `POST /v2/memories/{memory_id}/undo` 撤销记忆写入

### [离线整理](https://mirabase.io/zh/developers/api/memory-dreaming.md)

- `GET /v2/memory/dreams/{dream_id}` 读取整理报告（需要部署开启）
- `GET /v2/memory/dreams/{dream_id}/actions` 列出整理动作（需要部署开启）
- `GET /v2/memory/dreams/{dream_id}/judgments` 列出整理判定（需要部署开启）
- `POST /v2/memory/dreams/{dream_id}/undo` 撤销整理（需要部署开启）
- `GET /v2/memory/proposals/{proposal_id}` 读取整理提案（需要部署开启）
- `POST /v2/memory/proposals/{proposal_id}/approve` 批准整理提案（需要部署开启）
- `POST /v2/memory/proposals/{proposal_id}/reject` 驳回整理提案（需要部署开启）
- `GET /v2/spaces/{space_id}/memory/dreams` 列出整理（需要部署开启）
- `POST /v2/spaces/{space_id}/memory/dreams` 发起整理（需要部署开启）
- `GET /v2/spaces/{space_id}/memory/proposals` 列出整理提案（需要部署开启）
- `GET /v2/spaces/{space_id}/memory/settings` 读取整理设置（需要部署开启）
- `PATCH /v2/spaces/{space_id}/memory/settings` 修改整理设置（需要部署开启）

### [分支](https://mirabase.io/zh/developers/api/branches.md)

- `GET /v2/spaces/{space_id}/branches` 列出分支
- `POST /v2/spaces/{space_id}/branches` 创建分支
- `GET /v2/spaces/{space_id}/branches/{branch_id}` 读取分支
- `PATCH /v2/spaces/{space_id}/branches/{branch_id}` 重命名或续期分支
- `DELETE /v2/spaces/{space_id}/branches/{branch_id}` 放弃分支
- `GET /v2/spaces/{space_id}/branches/{branch_id}/checkpoints` 列出检查点
- `POST /v2/spaces/{space_id}/branches/{branch_id}/checkpoints` 创建检查点
- `GET /v2/spaces/{space_id}/branches/{branch_id}/diff` 查看分支改动
- `POST /v2/spaces/{space_id}/branches/{branch_id}/merge` 合并分支
- `GET /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256}` 读取分支对象
- `HEAD /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256}` 检查分支对象
- `PUT /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256}` 写入分支对象
- `POST /v2/spaces/{space_id}/branches/{branch_id}/rollback` 回滚到检查点

### [用量](https://mirabase.io/zh/developers/api/usage.md)

- `GET /v2/limits` 读取限制
- `GET /v2/queue` 读取处理队列
- `GET /v2/usage` 读取用量

### [审计](https://mirabase.io/zh/developers/api/audit.md)

- `GET /v2/audit/events` 读取审计事件

### [请求日志](https://mirabase.io/zh/developers/api/request-logs.md)

- `GET /v2/request-logs` 列出请求日志
- `GET /v2/request-logs/{log_id}` 读取请求日志
- `GET /v2/retrieval/traces/{trace_id}` 读取检索轨迹

### [发现](https://mirabase.io/zh/developers/api/discovery.md)

- `GET /llms.txt` 读取 llms.txt
- `GET /v2/openapi.yaml` 读取 OpenAPI 文档

### [MCP](https://mirabase.io/zh/developers/api/mcp.md)

- `GET /mcp` MCP 握手
- `POST /mcp` 调用 MCP

### [数据结构](https://mirabase.io/zh/developers/api/schemas.md)

API 请求和响应用到的全部数据结构。
