API 参考总览：56 端点、鉴权三态与错误契约

把本站内容层当积木用的第一步是读懂它的接口地图：56 个 API 端点、三态鉴权、一套错误契约——全部在 /docs 调试台可交互验证（每个端点带在线试跑）。本篇是读文档前的总览：结构怎么分、鉴权怎么选、错误怎么读、速率与缓存有什么规矩。本文属于开发者中心栏目；端点数与版本随时可查：GET /api/health。

端点地图：五个分区

总数口径：56 是注册表实测数（/docs 调试台的端点注册表与文案由同一来源注入，永不漂移——v4.9.0 起的机制）。矩阵类文档里的旧数字（73）是历史版本文案，已废弃。

鉴权三态：什么场景用什么钥匙

• 主密钥（master key）：全权限、环境级——只该出现在你的服务器环境变量里，适合服务端批处理与运维脚本；泄露影响面最大，轮换纪律见 /docs 调试台的令牌管理章节；
• 控制台会话（axs_*）：密码换取、HMAC 签名、12 小时有效、权限 *——人类在控制台操作与雷达页共享的就是它（v4.9.0 起雷达免二次登录）；
• 作用域令牌（axn_*）：按 scope 授权（articles/markets/courses/settings/tokens/ops/ugc 等词表）、可单独吊销——给程序与 Agent 用的正确钥匙，最小权限实践全文见Agent 集成。

# 三态各试一发（令牌用环境变量，别写进命令行历史）：
curl -s https://axionserve-portal.aeronest-global.workers.dev/api/health | head -3                     # 公开探针
curl -s -H "Authorization: Bearer $AXN_TOKEN" https://axionserve-portal.aeronest-global.workers.dev/api/admin/articles?limit=1   # 作用域令牌
# 无鉴权访问管理端 → 标准 401 错误信封（见下节）

错误契约：统一信封

所有非 2xx 响应共用一个 JSON 信封：{ "error": 人类可读信息, "code": 机器可读错误码, "requestId": 请求追踪 ID }——错误码分族（40xxx 参数/校验、401xx/403xx 鉴权、404xx 不存在、409xx 冲突、429xx 限速），字段级错误附 field 提示。对接建议：程序按 code 分支、人类按 error 阅读、工单必带 requestId——三件套让跨系统排障从「猜」变成「查」。

速率与缓存：规矩写在响应头里

• 写入限速：管理端写操作限速 60 req/min 量级（批量导入按此设计节流，间隔 ≥2 秒稳妥）；触发限速返回 429 + Retry-After 语义；
• 读取缓存：公开列表/详情走边缘缓存（maxAge 15–60s + SWR 语义）——刚写入的数据在缓存窗口内可能读到旧值，对账用管理端（直读库）或等待窗口过期；
• 可观测响应头：每个响应带 x-axion-latency-ms（本次耗时）、x-axion-d1（本次数据库成本 q/r/w/ms）、x-request-id、x-axion-version/build——性能与成本按请求可核，这是「证据文化」在 API 层的延伸。

读文档的顺序建议：一小时对接法

第一次对接本站 API，建议按这个顺序花一小时：前 10 分钟读本篇（结构地图）+ 打开 /docs 浏览五个分区，建立端点面的整体感；中间 20 分钟在调试台试跑三个只读端点（health、articles 列表、taxonomy），观察响应结构与 x-axion-d1 成本头的真实形状；再 20 分钟用你的语言写一个 40 行客户端骨架（模板在SDK 与库），跑通「列表→详情」链路；最后 10 分钟故意触发三类错误（无令牌 401、坏参数 40xxx、不存在 404xx），确认你的错误分支都能接住。一小时后你就具备了生产对接的全部认知——这比通读端点文档快，因为接口面的一致性让你只需要学会一个端点就能推断其余。

调试台：/docs 的正确打开方式

• 按分区浏览：56 端点按 GET/POST/PUT/DELETE 与方法色标排列，每个端点有参数说明与响应示例；
• 在线试跑：填入令牌即可真实调用（读操作放心跑，写操作对着自己的测试条目跑）；
• 错误契约对照：故意传错参数看 40xxx 信封的真实形状——对接前把错误路径也调通，上线后才不慌。

三个典型集成场景的端点组合

• 内容镜像/聚合站：GET /api/articles（分页拉列表）+ GET /api/articles/{slug}（详情）+ sitemap 数据端点对账——注意尊重内容授权与来源标注，镜像前先读服务条款；增量同步用 published_at 游标（模板在Webhook 与事件）；
• 监控与拨测：GET /api/health（版本/构建翻转检测）+ 关键内容页的 200 断言 + x-axion-latency-ms 响应头采样——三条线组成最小拨测面，节奏每分钟一轮足够；
• Agent 工具面：管理端 CRUD 按任务包成工具（起稿/体检/修订三个动作覆盖内容助理场景），作用域与护栏设计照Agent 集成的五步走——工具描述里写明端点的速率与缓存口径，Agent 的规划质量直接受益。

版本与兼容承诺

公开 API 的 v1 字段契约保持稳定（增量字段只加不改，历史实践：stats/体检字段即以增量方式加入）；破坏性变更走更新日志显式公告并给迁移指引。你的对接代码该做的两件事：忽略未知字段（向前兼容）、校验必备字段（防御性解析）——两条做到，契约演进对你无感。

相关文档：Agent 集成 · SDK 与库 · 更新日志。调试台入口 /docs；内容与测量数据的机器消费背景见未来 Web 与 Agent；栏目首页回开发者中心。