# API 约定

所有接口共用的规则：请求与响应、请求 id、版本、分页、幂等、条件请求、任务、错误、重试和限流。

## 请求与响应

| 项目 | 约定 |
| --- | --- |
| 地址 | `https://api.mirabase.dev`，接口都在 `/v2` 下 |
| 认证 | `Authorization: Bearer <API Key>`，见 [认证](https://mirabase.io/zh/developers/authentication.md) |
| 请求体 | UTF-8 的 JSON，`Content-Type: application/json`。文件内容除外，按文件本身的类型发送原始字节 |
| 字段名 | 小写加下划线，如 `next_cursor` |
| 时间 | RFC 3339，响应一律为 UTC，如 `2026-11-06T08:30:00.000Z`。请求中的时间需带时区偏移 |
| id | 不透明字符串。原样保存和传回，不要解析，也不要依赖前缀 |
| 校验 | 严格。未知字段或查询参数返回 422 `validation_error`，由 `field` 指明字段名 |
| 错误 | 所有错误结构相同，见下文 [错误](https://mirabase.io/zh/developers/conventions.md#errors) |

## 请求 id

每个响应都带 `X-Request-Id`，错误体中的 `request_id` 与之相同。联系支持时请提供该值。你也可以在请求中传入 `X-Request-Id`，服务会原样沿用；若格式无效，则替换为服务生成的值。

## 版本

- 大版本在路径里：`/v2`。
- 每个响应都带 `Mirabase-Contract-Version`，当前为 `1.0`。请求无需携带该请求头；若传入服务不支持的值，返回 400 `unsupported_contract_version`，移除该请求头即可。
- 新增接口、可选参数和响应字段不会升级版本号，因此客户端应忽略未知的响应字段。
- 标有“即将上线”的接口尚未提供，上线前可能调整；标有“需要部署开启”的接口为可选功能。两者均在 [API 参考](https://mirabase.io/zh/developers/api.md) 中标明。
- 机器可读的契约是 OpenAPI 文档。它的地址和这份文档对应的规格版本都在 [API 概览](https://mirabase.io/zh/developers/api.md)。

## 行为变更

最近一次更新改变了下列已有行为。新增的参数和字段不在此列，见各指南页和 [API 参考](https://mirabase.io/zh/developers/api.md)。

- [`POST /v2/retrieval/answer`](https://mirabase.io/zh/developers/api/retrieval.md#retrieval-answer) 不传 `weights` 时不再使用 `changes` 和 `skills` 两个来源。找不到相关证据的问题返回 `abstained`，`reason` 为 `no_evidence`。要恢复原来的行为，请传 `weights`，见 [带引用回答](https://mirabase.io/zh/developers/retrieval.md#answer)。
- 每个主体同时运行的回答从 1 个改为 3 个。
- 429 `rate_limited` 的错误信封多了一个 `limit`。并发限制的 429 不再带 `RateLimit-*` 响应头，见 [限流与限额](https://mirabase.io/zh/developers/conventions.md#rate-limits)。
- [`POST /v2/memories`](https://mirabase.io/zh/developers/api/memories.md#memories-create) 写入与现行记忆相同的 `project` 或 `agent` 记忆时，返回 200 和已有的那条记忆，不再新建一条并返回 201。
- 处理完成前读取 `view=table`，现在返回 404 `content_not_ready`，不再返回 404 `not_found`。
- MCP 的 `tools/list` 多了 8 个工具；带元数据范围的 Key 只看到它能调用的工具，见 [连接 Agent（MCP）](https://mirabase.io/zh/developers/agents.md#tools)。
- MCP 工具调用成功时，结果的 JSON 位于 `content` 的文本中；仅当协商的协议版本为 `2025-06-18` 或更高版本时，九个只读工具的结果才会在 `structuredContent` 中另含同一对象，见 [协议版本](https://mirabase.io/zh/developers/agents.md#protocol-versions)。Key 缺少工具所需能力时，返回含 `isError: true` 的工具结果（错误码 `forbidden`），不再返回 JSON-RPC 错误 `-32003`。
- 失败的 MCP 工具结果不再带 `structuredContent`，各协议版本都是如此：错误说明在 `content` 的文本中，错误信封在 `_meta["dev.mirabase/error"]` 中。见 [工具](https://mirabase.io/zh/developers/agents.md#tools)。
- [`GET /v2/openapi.yaml`](https://mirabase.io/zh/developers/api/discovery.md#discovery-openapi) 只描述 API Key 能调用的操作，并带有示例；控制台、运营方和尚未上线的操作不再出现在其中。它的 `ETag` 随之改变。
- `stated_date` 不再取句子中间提到的日期，仅取带“截至”“as of”等标记的日期、小节标题中的日期、行首或分句开头的日期，以及文档开头的日期，见 [检索](https://mirabase.io/zh/developers/retrieval.md#search)。
- 表格汇总只在完整理解问题时才计算，命中表格的旧版本时也不计算；此前会计算的部分问题现在返回 `table_aggregate:not_computed:<reason>`，见 [上下文](https://mirabase.io/zh/developers/retrieval.md#context)。
- 问题询问当前状态时，从新到旧的排序只作用于关于同一事物的证据：同一个 Entry、多次保存的同一个网页，或 `metadata.subject_key` 取值相同的几个 Entry。路径或标题相似、位于同一文件夹都不算同一事物。分数相近但主题不同的证据不再因日期较新而排在前面，见 [带引用回答](https://mirabase.io/zh/developers/retrieval.md#answer)。
- MCP 的 `initialize` 现按客户端请求的协议版本响应（支持 `2024-11-05` 至 `2025-11-25` 的四个版本），不再固定返回 `2024-11-05`；服务名改为 `mirabase-developer`。见 [协议版本](https://mirabase.io/zh/developers/agents.md#protocol-versions)。
- 当部署不提炼记忆或 Entry 带有 `memory_exclude` 时，对话的 `memory.state` 初始即为 `skipped`，并在 `reason` 中说明原因，不再先显示为 `pending`。见 [跳过提炼的原因](https://mirabase.io/zh/developers/memory.md#skip-reasons)。
- 已经提炼完成的版本，在部署关闭提炼或移除模型后仍为 `ready`，不再变为 `skipped`。`distill_disabled`、`model_not_configured` 和 `distill_paused` 只对属于 `tenant_admin` 或持有 `knowledge:manage`、且未收窄的 Key 显示，其他 Key 看到的是 `distill_unavailable`（替代前两个）；`distill_paused` 不返回原因，状态仍为 `pending`。见 [提炼被跳过的原因](https://mirabase.io/zh/developers/memory.md#skip-reasons)。
- 在有团队的账户中，Admin 不能再为他人创建的 Agent 或最终用户签发 Key，也不能再吊销 Owner 或其他 Admin 的 Key。见 [用 API 创建](https://mirabase.io/zh/developers/authentication.md#api)。
- 写入请求返回 429 `ingest_backlog` 时，`Retry-After` 为 30 到 600 秒，不再固定为 30 秒。`Retry-After` 超过 `maxRetryAfterMs`（Python 为 `max_retry_after`，默认 60 秒）时，SDK 不自动重试，直接抛出 `MirabaseRateLimitError`。见 [处理队列已满时](https://mirabase.io/zh/developers/processing.md#backlog)。
- SDK 在创建客户端时校验 API Key：去除首尾的空白字符；Key 中含有换行、空格、控制字符或非 ASCII 字符时，抛出 `MirabaseConfigError`，代码为 `invalid_api_key`，不再等到发出请求时才报错。见 [处理错误](https://mirabase.io/zh/developers/sdks.md#errors)。
- 导入对话时带 `redact_secrets`，现对每条消息分别替换，标题单独替换；`secrets_redacted` 为消息和标题中实际替换的数量。跨两条消息的凭据不再作为一处识别。导入文本的行为不变。
- 检索结果的 `score`、排序和 `explain` 中的候选数，仅依据调用方可读取的内容计算。读取范围受限的调用方（例如设有 `read_root` 的成员）得到的 `score` 可能变化；候选内容全部可读取的调用方，结果不变。
- [`GET /v2/retrieval/traces/{trace_id}`](https://mirabase.io/zh/developers/api/request-logs.md#requestlogs-trace) 对本次更新之前记录的轨迹不再返回 `summary.candidates` 和 `summary.fused_count`。
- 账户待审批期间，控制台登录会话仅可管理 API Key、查看账户信息和只读列表；检索、重新处理、删除以及创建或修改 Space 等请求返回 403 `account_pending_approval`，此前 [`POST /v2/spaces`](https://mirabase.io/zh/developers/api/spaces.md#spaces-create) 返回 201。见 [在控制台创建 API Key](https://mirabase.io/zh/developers/authentication.md#console)。
- 未能发出的模型调用（在连接阶段失败）不再计入每月模型配额。模型调用因配额被拒绝时，429 `quota_exceeded` 的 `message` 不再包含本次调用所需的用量和账户的剩余额度，请通过 [`GET /v2/usage`](https://mirabase.io/zh/developers/api/usage.md#usage-usage) 查看。
- 同一账户内，各 Space 的记忆提炼任务轮流执行，一个 Space 的积压不再延后其他 Space 的提炼；导入对话不再延后文本的记忆提炼。

## 分页

列表返回 `{data, next_cursor}`。将 `next_cursor` 原样作为 `cursor` 传回以获取下一页；最后一页不含 `next_cursor`。游标为不透明字符串，不要解析或自行构造。

| 参数 | 说明 |
| --- | --- |
| `limit` | 每页条数，默认 20，最大 100 |
| `cursor` | 上一页返回的 `next_cursor`。翻页时其他参数保持不变 |

curl:

```bash
# 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"
```

TypeScript:

```ts
// Iterating fetches pages as needed.
for await (const entry of mirabase.entries.list({ limit: 100 })) {
  console.log(entry.id);
}
```

Python:

```python
# Iterating fetches pages as needed.
for entry in mb.entries.list(limit=100):
    print(entry["id"])
```

各列表的排序规则见 [API 参考](https://mirabase.io/zh/developers/api.md) 中对应接口的说明。变更流除外：返回 `{data, cursor, has_more}`，且始终包含 `cursor` 以便继续读取，见 [同步](https://mirabase.io/zh/developers/sync.md#loop)。检索不分页，通过 `limit` 控制返回条数。

## 幂等

网络中断时，无法确认写入是否已生效。携带 `Idempotency-Key` 重发请求是安全的：幂等键、主体、API Key、操作和输入均相同时，服务在 24 小时内直接返回首次结果，不会重复执行。

| 项目 | 规则 |
| --- | --- |
| 格式 | 1 到 512 个可见 ASCII 字符，建议用 UUID。每个逻辑请求一个新键 |
| 保留 | 24 小时 |
| 同一个键、不同输入 | 返回 409 `conflict`，`remediation.action` 是 `use_new_idempotency_key` |
| 作用范围 | 按 API Key 隔开：两个 Key 用同一个键互不影响 |

```bash
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 参考](https://mirabase.io/zh/developers/api.md) 中的参数表。
- 不接受的接口重发也是安全的：`GET` 不改数据；上传的 `parts`、`complete`、`abort` 按上传 id 判重；[`PATCH /v2/entries/{entry_id}`](https://mirabase.io/zh/developers/api/entries.md#entries-update) 重发返回相同的结果。
- 单条 `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` 可直接使用，无需再次读取。完整示例见 [文件](https://mirabase.io/zh/developers/files.md#conditional)。

## 任务

无法在单次请求内完成的操作会转为任务：返回 202，携带 `job_id` 和指向该任务的 `Location`。每隔 1 到 2 秒轮询一次 [`GET /v2/jobs/{job_id}`](https://mirabase.io/zh/developers/api/jobs.md#jobs-read)，直至状态变为终态。

每种状态的含义见 [DevJobStatus](https://mirabase.io/zh/developers/api/schemas.md#DevJobStatus)，任务的种类见 [DevJobKind](https://mirabase.io/zh/developers/api/schemas.md#DevJobKind)。

| 请求 | 说明 |
| --- | --- |
| 写入内容之后的处理（解析、索引、提炼） | 写入本身已提交，处理在后台运行。`Prefer: wait=N`（最多 10 秒）可使响应等待至处理完成，见 [文件](https://mirabase.io/zh/developers/files.md#processing) |
| 大的目录操作和分支合并 | 超过同步上限时带 `Prefer: respond-async`，见 [文件](https://mirabase.io/zh/developers/files.md#jobs) 和 [分支](https://mirabase.io/zh/developers/branches.md#async-merge) |
| 导出和导入 | 总是任务，见 [同步](https://mirabase.io/zh/developers/sync.md#export) |

```bash
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](https://mirabase.io/zh/developers/api/schemas.md#DevErrorBody)，`type` 与 HTTP 状态码的对应关系见 [DevErrorType](https://mirabase.io/zh/developers/api/schemas.md#DevErrorType)，全部错误码见 [错误码](https://mirabase.io/zh/developers/errors.md#codes)。

### 一次列出全部出错字段

请求体校验失败时，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](https://mirabase.io/zh/developers/sdks.md#errors)。

## 重试

- 检查 `retryable`。若有 `Retry-After`，按其指定的时间等待后再重试；否则使用带抖动的指数退避。
- 重试写操作时请携带 `Idempotency-Key`，否则可能产生多余版本。

每个错误码给出的 `Retry-After` 秒数见 [错误码](https://mirabase.io/zh/developers/errors.md#codes)。

## 限流与限额

通过认证的响应都带 `RateLimit-Limit`、`RateLimit-Remaining` 和 `RateLimit-Reset`。每个 Key 有两个令牌桶：`GET`、`HEAD` 一个，其他方法一个。桶容量等于每分钟额度，所以允许一分钟额度的突发。账户另有所有 Key 合计的总额度；因总额度受限的请求，响应头报告的是总额度的令牌桶。限流按服务进程执行，这些数字只作参考，不是精确额度。

```bash
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 参考](https://mirabase.io/zh/developers/api/schemas.md#DevLimit)。默认值是暂定的：以 [`GET /v2/limits`](https://mirabase.io/zh/developers/api/usage.md#usage-limits) 返回的部署实际值为准，用 [`GET /v2/usage`](https://mirabase.io/zh/developers/api/usage.md#usage-usage) 查看当前用量。并发限额占满时，请求先在服务端等待名额，因此短时间的并发突发只会变慢，不会被拒绝。

429 `rate_limited` 的错误信封带 `limit`，说明触发的是哪一种限制。`request_rate` 是每分钟的请求额度：按 `Retry-After` 等待后重试。`concurrency` 是对进行中的调用数量的限制：请求已经在服务端等过名额，响应不带 `RateLimit-*` 响应头。这时应减少同时发出的调用，延长等待的作用不大。

单个接口自己的上限，例如文件大小、批量条数和取值范围，写在 [API 参考](https://mirabase.io/zh/developers/api.md) 中该接口的说明和参数里。

### 套餐

每个账户有一个套餐，见 [`GET /v2/limits`](https://mirabase.io/zh/developers/api/usage.md#usage-limits) 和 [`GET /v2/usage`](https://mirabase.io/zh/developers/api/usage.md#usage-usage) 响应中的 [plan](https://mirabase.io/zh/developers/api/schemas.md#DevPlan)。套餐决定适用哪些限额，具体数值以 [`GET /v2/limits`](https://mirabase.io/zh/developers/api/usage.md#usage-limits) 的返回为准。

| 套餐 | 说明 |
| --- | --- |
| `standard` | 使用当前部署的限额。 |
| `free` | 自助注册账户的初始套餐。除当前部署的限额外，还限制存储空间、每月写入量、每月模型 token 数、每月模型费用和请求速率。持久配额用尽时返回 429 `quota_exceeded`，并由 `quota` 字段指明耗尽的配额项。 |
| `legacy` | 在推出套餐之前开通的账户。与 `standard` 一样使用当前部署的限额。 |

## 下一步

- [错误码](https://mirabase.io/zh/developers/errors.md)：每个错误码的含义和 `remediation.action`。
- [SDK](https://mirabase.io/zh/developers/sdks.md)：客户端已内置这些规则。
- [API 参考](https://mirabase.io/zh/developers/api.md)：每个接口的参数和响应。
