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；欄目首頁回開發者中心。