跳到主要内容
开发者文档
文档目录

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。请求无需携带该请求头;若传入服务不支持的值,返回 400 unsupported_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,现在返回 404 content_not_ready,不再返回 404 not_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。翻页时其他参数保持不变
curl
# 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
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 不支持该请求头:第二次调用返回 404 not_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
curl "https://api.mirabase.dev/v2/jobs/$JOB_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

目录、合并、导出、导入这类任务只有发起人和 Space 所有者能读,完成后保留 7 天。任务没有长轮询。

错误

所有错误结构相同。type 表示错误大类,适合按类别统一处理;具体情况按稳定的 code 和 remediation.action 分支处理;message 供人工阅读,内容可能变更。

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

json
{
  "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
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 一样使用当前部署的限额。

下一步

  • 错误码:每个错误码的含义和 remediation.action。
  • SDK:客户端已内置这些规则。
  • API 参考:每个接口的参数和响应。