API 约定
Markdown 版所有接口共用的规则:请求与响应、请求 id、版本、分页、幂等、条件请求、任务、错误、重试和限流。
请求与响应
| 项目 | 约定 |
|---|---|
| 地址 | https://api.mirabase.dev,接口都在 /v2 下 |
| 认证 | Authorization: Bearer <API Key>,见 认证 |
| 请求体 | UTF-8 的 JSON,Content-Type: application/json。文件内容除外,按文件本身的类型发送原始字节 |
| 字段名 | 小写加下划线,如 next_cursor |
| 时间 | RFC 3339,响应一律为 UTC,如 2026-11-06T08:30:00.000Z。请求中的时间需带时区偏移 |
| id | 不透明字符串。原样保存和传回,不要解析,也不要依赖前缀 |
| 校验 | 严格。未知字段或查询参数返回 422 validation_error,由 field 指明字段名 |
| 错误 | 所有错误结构相同,见下文 错误 |
请求 id
每个响应都带 X-Request-Id,错误体中的 request_id 与之相同。联系支持时请提供该值。你也可以在请求中传入 X-Request-Id,服务会原样沿用;若格式无效,则替换为服务生成的值。
版本
- 大版本在路径里:
/v2。 - 每个响应都带
Mirabase-Contract-Version,当前为1.0。请求无需携带该请求头;若传入服务不支持的值,返回 400unsupported_contract_version,移除该请求头即可。 - 新增接口、可选参数和响应字段不会升级版本号,因此客户端应忽略未知的响应字段。
- 标有“即将上线”的接口尚未提供,上线前可能调整;标有“需要部署开启”的接口为可选功能。两者均在 API 参考 中标明。
- 机器可读的契约是 OpenAPI 文档。它的地址和这份文档对应的规格版本都在 API 概览。
行为变更
最近一次更新改变了下列已有行为。新增的参数和字段不在此列,见各指南页和 API 参考。
POST /v2/retrieval/answer不传weights时不再使用changes和skills两个来源。找不到相关证据的问题返回abstained,reason为no_evidence。要恢复原来的行为,请传weights,见 带引用回答。- 每个主体同时运行的回答从 1 个改为 3 个。
- 429
rate_limited的错误信封多了一个limit。并发限制的 429 不再带RateLimit-*响应头,见 限流与限额。 POST /v2/memories写入与现行记忆相同的project或agent记忆时,返回 200 和已有的那条记忆,不再新建一条并返回 201。- 处理完成前读取
view=table,现在返回 404content_not_ready,不再返回 404not_found。 - MCP 的
tools/list多了 8 个工具;带元数据范围的 Key 只看到它能调用的工具,见 连接 Agent(MCP)。 - MCP 工具调用成功时,结果的 JSON 位于
content的文本中;仅当协商的协议版本为2025-06-18或更高版本时,九个只读工具的结果才会在structuredContent中另含同一对象,见 协议版本。Key 缺少工具所需能力时,返回含isError: true的工具结果(错误码forbidden),不再返回 JSON-RPC 错误-32003。 - 失败的 MCP 工具结果不再带
structuredContent,各协议版本都是如此:错误说明在content的文本中,错误信封在_meta["dev.mirabase/error"]中。见 工具。 GET /v2/openapi.yaml只描述 API Key 能调用的操作,并带有示例;控制台、运营方和尚未上线的操作不再出现在其中。它的ETag随之改变。stated_date不再取句子中间提到的日期,仅取带“截至”“as of”等标记的日期、小节标题中的日期、行首或分句开头的日期,以及文档开头的日期,见 检索。- 表格汇总只在完整理解问题时才计算,命中表格的旧版本时也不计算;此前会计算的部分问题现在返回
table_aggregate:not_computed:<reason>,见 上下文。 - 问题询问当前状态时,从新到旧的排序只作用于关于同一事物的证据:同一个 Entry、多次保存的同一个网页,或
metadata.subject_key取值相同的几个 Entry。路径或标题相似、位于同一文件夹都不算同一事物。分数相近但主题不同的证据不再因日期较新而排在前面,见 带引用回答。 - MCP 的
initialize现按客户端请求的协议版本响应(支持2024-11-05至2025-11-25的四个版本),不再固定返回2024-11-05;服务名改为mirabase-developer。见 协议版本。 - 当部署不提炼记忆或 Entry 带有
memory_exclude时,对话的memory.state初始即为skipped,并在reason中说明原因,不再先显示为pending。见 跳过提炼的原因。 - 已经提炼完成的版本,在部署关闭提炼或移除模型后仍为
ready,不再变为skipped。distill_disabled、model_not_configured和distill_paused只对属于tenant_admin或持有knowledge:manage、且未收窄的 Key 显示,其他 Key 看到的是distill_unavailable(替代前两个);distill_paused不返回原因,状态仍为pending。见 提炼被跳过的原因。 - 在有团队的账户中,Admin 不能再为他人创建的 Agent 或最终用户签发 Key,也不能再吊销 Owner 或其他 Admin 的 Key。见 用 API 创建。
- 写入请求返回 429
ingest_backlog时,Retry-After为 30 到 600 秒,不再固定为 30 秒。Retry-After超过maxRetryAfterMs(Python 为max_retry_after,默认 60 秒)时,SDK 不自动重试,直接抛出MirabaseRateLimitError。见 处理队列已满时。 - SDK 在创建客户端时校验 API Key:去除首尾的空白字符;Key 中含有换行、空格、控制字符或非 ASCII 字符时,抛出
MirabaseConfigError,代码为invalid_api_key,不再等到发出请求时才报错。见 处理错误。 - 导入对话时带
redact_secrets,现对每条消息分别替换,标题单独替换;secrets_redacted为消息和标题中实际替换的数量。跨两条消息的凭据不再作为一处识别。导入文本的行为不变。 - 检索结果的
score、排序和explain中的候选数,仅依据调用方可读取的内容计算。读取范围受限的调用方(例如设有read_root的成员)得到的score可能变化;候选内容全部可读取的调用方,结果不变。 GET /v2/retrieval/traces/{trace_id}对本次更新之前记录的轨迹不再返回summary.candidates和summary.fused_count。- 账户待审批期间,控制台登录会话仅可管理 API Key、查看账户信息和只读列表;检索、重新处理、删除以及创建或修改 Space 等请求返回 403
account_pending_approval,此前POST /v2/spaces返回 201。见 在控制台创建 API Key。 - 未能发出的模型调用(在连接阶段失败)不再计入每月模型配额。模型调用因配额被拒绝时,429
quota_exceeded的message不再包含本次调用所需的用量和账户的剩余额度,请通过GET /v2/usage查看。 - 同一账户内,各 Space 的记忆提炼任务轮流执行,一个 Space 的积压不再延后其他 Space 的提炼;导入对话不再延后文本的记忆提炼。
分页
列表返回 {data, next_cursor}。将 next_cursor 原样作为 cursor 传回以获取下一页;最后一页不含 next_cursor。游标为不透明字符串,不要解析或自行构造。
| 参数 | 说明 |
|---|---|
limit | 每页条数,默认 20,最大 100 |
cursor | 上一页返回的 next_cursor。翻页时其他参数保持不变 |
# First page
curl "https://api.mirabase.dev/v2/entries?limit=100" \
-H "Authorization: Bearer $MIRABASE_API_KEY"
# Next page: pass next_cursor back as cursor.
curl "https://api.mirabase.dev/v2/entries?limit=100&cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer $MIRABASE_API_KEY"各列表的排序规则见 API 参考 中对应接口的说明。变更流除外:返回 {data, cursor, has_more},且始终包含 cursor 以便继续读取,见 同步。检索不分页,通过 limit 控制返回条数。
幂等
网络中断时,无法确认写入是否已生效。携带 Idempotency-Key 重发请求是安全的:幂等键、主体、API Key、操作和输入均相同时,服务在 24 小时内直接返回首次结果,不会重复执行。
| 项目 | 规则 |
|---|---|
| 格式 | 1 到 512 个可见 ASCII 字符,建议用 UUID。每个逻辑请求一个新键 |
| 保留 | 24 小时 |
| 同一个键、不同输入 | 返回 409 conflict,remediation.action 是 use_new_idempotency_key |
| 作用范围 | 按 API Key 隔开:两个 Key 用同一个键互不影响 |
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/ingest" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Idempotency-Key: 7d3f4c0e-5b1a-4f6e-9c2d-1a2b3c4d5e6f" \
-H "Content-Type: application/json" \
-d '{"kind":"text","text":"The launch moved to March 14."}'- 大多数
POST、PUT、PATCH接口支持该请求头,合并分支则必须携带。各接口是否支持见 API 参考 中的参数表。 - 不接受的接口重发也是安全的:
GET不改数据;上传的parts、complete、abort按上传 id 判重;PATCH /v2/entries/{entry_id}重发返回相同的结果。 - 单条
DELETE不支持该请求头:第二次调用返回 404not_found,同样可以确认结果。如需可重放的删除,请使用带幂等键的files/batch。 - SDK 会自动给接受这个头的调用生成键,重试用的是同一个。
条件请求
文件的 ETag 是它最新版本的 id,版本不可变,所以它是强校验器。用它避免覆盖他人的改动,也避免重复下载。
| 请求头 | 用在 | 效果 |
|---|---|---|
If-Match: "<etag>" | 写入、修改、删除、回滚 | 仅当文件仍为该版本时执行;否则返回 412 precondition_failed,错误体中的 current_version_id 为当前版本 |
If-None-Match: * | 写入 | 仅当路径下尚无文件时写入;已有文件则返回 412 precondition_failed |
If-None-Match: "<etag>" | 读取 | 内容未变更时返回 304,无响应体 |
Range, If-Range | 读取原件 | 返回 206 和请求的字节段;范围在文件之外返回 416 range_not_satisfiable |
写入成功的响应包含新版本的 ETag,下一次 If-Match 可直接使用,无需再次读取。完整示例见 文件。
任务
无法在单次请求内完成的操作会转为任务:返回 202,携带 job_id 和指向该任务的 Location。每隔 1 到 2 秒轮询一次 GET /v2/jobs/{job_id},直至状态变为终态。
每种状态的含义见 DevJobStatus,任务的种类见 DevJobKind。
| 请求 | 说明 |
|---|---|
| 写入内容之后的处理(解析、索引、提炼) | 写入本身已提交,处理在后台运行。Prefer: wait=N(最多 10 秒)可使响应等待至处理完成,见 文件 |
| 大的目录操作和分支合并 | 超过同步上限时带 Prefer: respond-async,见 文件 和 分支 |
| 导出和导入 | 总是任务,见 同步 |
curl "https://api.mirabase.dev/v2/jobs/$JOB_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"目录、合并、导出、导入这类任务只有发起人和 Space 所有者能读,完成后保留 7 天。任务没有长轮询。
错误
所有错误结构相同。type 表示错误大类,适合按类别统一处理;具体情况按稳定的 code 和 remediation.action 分支处理;message 供人工阅读,内容可能变更。
{
"error": {
"code": "precondition_failed",
"type": "conflict",
"status": 412,
"message": "the file has moved on",
"request_id": "req_a18f",
"retryable": false,
"current_version_id": "ver_3c44",
"remediation": {
"action": "reread_and_retry",
"doc_url": "https://api.mirabase.dev/llms.txt"
}
}
}每个字段的含义见 DevErrorBody,type 与 HTTP 状态码的对应关系见 DevErrorType,全部错误码见 错误码。
一次列出全部出错字段
请求体校验失败时,422 validation_error 的 errors 会列出发现的全部问题,便于一次修正。字段路径用点号分隔,例如 messages.0.role。
{
"error": {
"code": "validation_error",
"type": "invalid_request",
"status": 422,
"message": "query is required",
"request_id": "req_b27c",
"retryable": false,
"field": "query",
"errors": [
{
"field": "query",
"code": "validation_error",
"message": "query is required"
},
{
"field": "colour",
"code": "validation_error",
"message": "unknown field: colour"
}
],
"remediation": {
"action": "fix_request",
"doc_url": "https://api.mirabase.dev/llms.txt"
}
}
}各 SDK 按 HTTP 状态码抛出 MirabaseError 的子类,例如 MirabaseNotFoundError、MirabaseRateLimitError,错误对象上也有 type 和 errors,见 SDK。
重试
- 检查
retryable。若有Retry-After,按其指定的时间等待后再重试;否则使用带抖动的指数退避。 - 重试写操作时请携带
Idempotency-Key,否则可能产生多余版本。
每个错误码给出的 Retry-After 秒数见 错误码。
限流与限额
通过认证的响应都带 RateLimit-Limit、RateLimit-Remaining 和 RateLimit-Reset。每个 Key 有两个令牌桶:GET、HEAD 一个,其他方法一个。桶容量等于每分钟额度,所以允许一分钟额度的突发。账户另有所有 Key 合计的总额度;因总额度受限的请求,响应头报告的是总额度的令牌桶。限流按服务进程执行,这些数字只作参考,不是精确额度。
curl https://api.mirabase.dev/v2/limits \
-H "Authorization: Bearer $MIRABASE_API_KEY"
curl https://api.mirabase.dev/v2/usage \
-H "Authorization: Bearer $MIRABASE_API_KEY"每项限额的名称、默认值、范围和超出时的返回见 API 参考。默认值是暂定的:以 GET /v2/limits 返回的部署实际值为准,用 GET /v2/usage 查看当前用量。并发限额占满时,请求先在服务端等待名额,因此短时间的并发突发只会变慢,不会被拒绝。
429 rate_limited 的错误信封带 limit,说明触发的是哪一种限制。request_rate 是每分钟的请求额度:按 Retry-After 等待后重试。concurrency 是对进行中的调用数量的限制:请求已经在服务端等过名额,响应不带 RateLimit-* 响应头。这时应减少同时发出的调用,延长等待的作用不大。
单个接口自己的上限,例如文件大小、批量条数和取值范围,写在 API 参考 中该接口的说明和参数里。
套餐
每个账户有一个套餐,见 GET /v2/limits 和 GET /v2/usage 响应中的 plan。套餐决定适用哪些限额,具体数值以 GET /v2/limits 的返回为准。
| 套餐 | 说明 |
|---|---|
standard | 使用当前部署的限额。 |
free | 自助注册账户的初始套餐。除当前部署的限额外,还限制存储空间、每月写入量、每月模型 token 数、每月模型费用和请求速率。持久配额用尽时返回 429 quota_exceeded,并由 quota 字段指明耗尽的配额项。 |
legacy | 在推出套餐之前开通的账户。与 standard 一样使用当前部署的限额。 |
