跳至主要内容

REST 與 WebSocket

範圍是一台車：它的任務佇列、地圖、安全指令、網路與更新。

認證​

POST /v1/auth/login 取得 Bearer token，之後帶 Authorization: Bearer <token>。

  • 401 = token 不存在或無效
  • 403 = 這個 session 沒有該權限

角色有 amoe8a_admin、customer_admin、task_operator、engineer。部分工程權限 （建圖、改參數、校正）在啟用時需要 WebAuthn 第二因子。

錯誤處理​

錯誤回應帶一個機器可讀的 code，以及給人看的英文 detail：

{ "detail": "mapping in progress", "code": "error.mapping_active" }

一律用 code 分支，不要比對 detail。 detail 是散文，會隨文案調整而變。這件事在 409 上最要緊——好幾個互不相關的狀況共用同一個狀態碼，只有 code 分得出來。

沒有 code 的錯誤表示「還沒有機器可讀的原因」，不是錯誤本身。

WebSocket​

/v1/stream?token=<access_token>

信封是 {channel, ts, payload}，channel 有 position、status、alert。

WebSocket 不在 OpenAPI 裡（那份規格只描述 HTTP 請求／回應），信封的契約另附一份 JSON Schema。

完整端點參考​

導覽列的 REST API 參考是一份可互動的 OpenAPI 文件：方法、參數、request／response 形狀 與狀態碼都在那裡，以它為準。

規格本身也可以直接下載，餵給你自己的 client generator：

/rest-api/openapi.json