# Mirabase 开发者文档

> 一套接口同时提供文件库、知识库和记忆。同一个 Entry 可以按路径、按 id 或按语义到达，权限和版本链只有一份。

这份文档的每一页都有 Markdown 版，地址是页面地址加 `.md`。下面列的就是这些地址。

- Base URL：`https://api.mirabase.dev`
- 认证：`Authorization: Bearer mb_live_...`
- OpenAPI：https://api.mirabase.dev/v2/openapi.yaml
- 面向 Agent 的说明：https://api.mirabase.dev/llms.txt
- SDK：TypeScript：`npm install https://mirabase.io/sdk/mirabase-sdk-0.3.0-rc.1.tgz`；Python：`pip install https://mirabase.io/sdk/mirabase-0.3.0rc1-py3-none-any.whl`

## 文档目录

- [5 分钟快速开始](https://mirabase.io/zh/developers/quickstart.md): 按路径写入和读取文件，编辑后查看版本，对比并回滚；让 Agent 在分支上修改后合并；获取引用到文件版本的回答；通过 MCP 连接 Agent。
- [认证与 API Key](https://mirabase.io/zh/developers/authentication.md): 发送、创建、限定、轮换和吊销 API Key。
- [SDK](https://mirabase.io/zh/developers/sdks.md): 安装和配置 TypeScript 与 Python 客户端，并了解它们替你处理的 Space 选择、流式回答、错误、重试和分页。
- [核心概念](https://mirabase.io/zh/developers/concepts.md): API 背后的数据模型：Space、Entry 与版本、文件、知识、记忆、分支和访问控制。
- [术语表](https://mirabase.io/zh/developers/glossary.md): 文档中反复出现的术语，每个用一句话定义，并链接到讲解它的页面。
- [文件与版本](https://mirabase.io/zh/developers/files.md): 写入、读取、编辑和整理文件，比较和回滚版本，处理 Agent 的提案。
- [处理进度](https://mirabase.io/zh/developers/processing.md): 文件写入后先变为可检索，记忆随后生成：等待单个文件可检索、跟踪批量导入进度，并识别检索时尚未处理完成的内容。
- [同步、快照与导出](https://mirabase.io/zh/developers/sync.md): 用目录树、变更流和 Webhook 将 Space 同步到其他系统，用快照固定某一时刻，用导出和导入迁移整个 Space。
- [检索与上下文](https://mirabase.io/zh/developers/retrieval.md): 由调用方选择来源的 search、由服务选择来源并分配预算的 context，以及带引用的 answer。
- [记忆](https://mirabase.io/zh/developers/memory.md): 写入、提炼、审核、更正和遗忘记忆，以及离线整理记忆。
- [连接 Agent（MCP）](https://mirabase.io/zh/developers/agents.md): 通过 MCP 将 Claude Code、Codex 等 Agent 接入 Mirabase：连接方式、协议版本、可用的工具及其参数，以及推荐的调用顺序。
- [框架集成（即将上线）](https://mirabase.io/zh/developers/integrations.md): 在 Vercel AI SDK、LangChain、LlamaIndex、OpenAI Agents SDK、Mastra 和 CrewAI 中使用 Mirabase 的工具、记忆和检索。
- [分支与挂载](https://mirabase.io/zh/developers/branches.md): 面向 Agent 的写时复制工作区、FUSE 挂载、同步命令和 Git 工作区。
- [权限](https://mirabase.io/zh/developers/permissions.md): 主体、能力、Space 角色、读写根路径和 API Key 的限制如何共同决定一次请求。
- [API 约定](https://mirabase.io/zh/developers/conventions.md): 所有接口共用的规则：请求与响应、请求 id、版本、分页、幂等、条件请求、任务、错误、重试和限流。
- [错误码](https://mirabase.io/zh/developers/errors.md): API Key 可能收到的每个错误码，及其 HTTP 状态码、remediation.action、含义和 Retry-After。
- [技能（Skills）](https://mirabase.io/zh/developers/skills.md): Mirabase 官方技能：告诉 Agent 何时调用哪个 MCP 工具、按什么顺序、哪些操作先征得用户同意。包括九个按任务划分的技能，以及项目记忆和带引用知识库两个完整场景。
- [基于 Mirabase 开发](https://mirabase.io/zh/developers/build.md): SDK、MCP、技能、Space 中的技能、Webhook 和供应商插件各自的作用与组合方式；一个应用的核心调用流程；如何编写并检查自己的技能。
- [全部指南合成一个文件](https://mirabase.io/zh/developers/llms-full.txt)

## API 参考

- [API 概览](https://mirabase.io/zh/developers/api.md): Mirabase Developer API 的全部接口，从 OpenAPI 规格生成。
- [身份](https://mirabase.io/zh/developers/api/identity.md): 读取当前身份
- [API Key](https://mirabase.io/zh/developers/api/api-keys.md): 列出 API Key、创建 API Key、读取 API Key、吊销 API Key、轮换 API Key
- [主体](https://mirabase.io/zh/developers/api/principals.md): 列出主体、创建主体、读取主体、修改主体能力
- [Space](https://mirabase.io/zh/developers/api/spaces.md): 列出 Space、创建 Space、读取 Space、按你自己的 id 获取或创建 Space、修改 Space、删除 Space、列出成员、设置成员、移除成员、读取 Space 的处理进度
- [文件](https://mirabase.io/zh/developers/api/files.md): 读取文件、读取文件响应头、写入文件、修改文件文本、删除文件、批量写入和删除、获取文件下载地址、按路径比较版本、按路径查看来源、按路径回滚、按路径列出版本
- [目录树](https://mirabase.io/zh/developers/api/tree.md): 列出目录、执行目录操作
- [大文件上传](https://mirabase.io/zh/developers/api/uploads.md): 发起大文件上传、中止上传、完成上传、获取分片上传地址
- [变更流](https://mirabase.io/zh/developers/api/changes.md): 查看近期由谁做了哪些修改、读取变更流
- [提案](https://mirabase.io/zh/developers/api/proposals.md): 读取提案、批准提案、查看提案改动、拒绝提案、撤回提案、列出提案
- [快照](https://mirabase.io/zh/developers/api/snapshots.md): 读取快照、删除快照、列出快照、创建快照
- [Webhook](https://mirabase.io/zh/developers/api/webhooks.md): 列出 Webhook、创建 Webhook、读取 Webhook、修改 Webhook、删除 Webhook、列出推送记录、轮换 Webhook 密钥
- [导出与导入](https://mirabase.io/zh/developers/api/transfers.md): 获取导出归档地址、导出 Space、复刻 Space、导入归档
- [导入](https://mirabase.io/zh/developers/api/ingest.md): 导入网址、文本或对话
- [Entry](https://mirabase.io/zh/developers/api/entries.md): 列出 Entry、读取 Entry、修改 Entry、将 Entry 移入废纸篓、读取 Entry 内容、获取 Entry 下载地址、列出副本、比较版本、查看来源、读取处理状态、彻底删除 Entry、重新处理 Entry、恢复 Entry、回滚到旧版本、列出版本、读取版本、修改版本说明、清空废纸篓
- [任务](https://mirabase.io/zh/developers/api/jobs.md): 读取任务、取消任务
- [检索](https://mirabase.io/zh/developers/api/retrieval.md): 带引用回答、构建上下文、发送上下文反馈、搜索
- [记忆](https://mirabase.io/zh/developers/api/memories.md): 列出记忆、写入记忆、读取记忆、修改记忆、遗忘记忆、更正记忆、查看记忆来源、审核记忆、撤销记忆写入
- [离线整理](https://mirabase.io/zh/developers/api/memory-dreaming.md): 读取整理报告、列出整理动作、列出整理判定、撤销整理、读取整理提案、批准整理提案、驳回整理提案、列出整理、发起整理、列出整理提案、读取整理设置、修改整理设置
- [分支](https://mirabase.io/zh/developers/api/branches.md): 列出分支、创建分支、读取分支、重命名或续期分支、放弃分支、列出检查点、创建检查点、查看分支改动、合并分支、读取分支对象、检查分支对象、写入分支对象、回滚到检查点
- [用量](https://mirabase.io/zh/developers/api/usage.md): 读取限制、读取处理队列、读取用量
- [审计](https://mirabase.io/zh/developers/api/audit.md): 读取审计事件
- [请求日志](https://mirabase.io/zh/developers/api/request-logs.md): 列出请求日志、读取请求日志、读取检索轨迹
- [发现](https://mirabase.io/zh/developers/api/discovery.md): 读取 llms.txt、读取 OpenAPI 文档
- [MCP](https://mirabase.io/zh/developers/api/mcp.md): MCP 握手、调用 MCP
- [数据结构](https://mirabase.io/zh/developers/api/schemas.md): API 请求和响应用到的全部数据结构。
