## 0. 概览

- **Base URL**：`https://fetchpaper.com`
- **鉴权**：`/graph/v1/` 与 `/mcp` 下每个请求都要带请求头 `x-api-key`（区分大小写），或
  `Authorization: Bearer <密钥>`；缺失或写错回 `401 {"error": "Invalid or missing API key"}`。
  `GET /`、`/docs/*`、`/guide.md`、`GET /health` 不需要密钥。
- **MCP 接入**：agent 也可以用 MCP 方式直接调用 `POST /mcp`（Streamable HTTP，
  鉴权同上），客户端配置与工具列表见 §4（`/docs/4`）。
- **论文的两种 id**：
  - `paperId` —— string —— 本 API 中标识论文的主要方式，40 位 sha。
  - `corpusId` —— int64 —— 数据集指代论文时使用的 id。
- **参数**：重复的标量键取第一个，重复的列表键合并；不认识的键忽略。
- **错误**：**400** 表示这条查询按不动（参数写错、值越界、查询宽到算不完），换写法重试有意义；
  **500** 表示数据目录不对（某层没建/半截/各层不是同一次构建），`error` 点名缺哪层和重建命令
  （如 `{"error": "作者表缺失或不完整，运行 python build_authors.py 重建"}`），调用代码不用改。
  响应一律 `application/json; charset=utf-8`。