API 參考總覽

• API 端點目錄：所有前端端點，依資源分組（方法、路徑、認證、請求、回應）。
• 請求與回應欄位：完整請求／回應模型。
• Agent toolkit：五個 LangGraph 工具（不是 REST）。
• 狀態列舉值：前端會渲染的所有狀態字串。
• 錯誤碼對照表：HTTP 狀態碼與 sandbox 錯誤語意。

通則

• Base：{BASE}/private/module/sandbox。
• 認證：TeamSync JWT 或 API key（見 認證）。受限 Sandbox scope key 只能動自己的 run 與 menu/提交。
• 請求 body：extra="forbid"（未知欄位 → 422）。
• 分頁：page_size（ge=1 le=100）、page_token（≤512）。
• 列表：lifecycle 查詢參數（active / retired / all，多數預設 active）。
• 未授權：404（不洩漏存在性）。例外：不能擁有的 department／company 建立是 403 owner_scope_forbidden；owner_scope=chatroom 是 422。Kill switch 下的變更：503 sandbox_disabled。
• 確認目錄：GET /public/info/sandbox/regions 與 /profiles（不必登入）。
• 提交/輪替類：必帶 Idempotency-Key（1..128 字元，禁 NUL）。
• OpenAPI 雙 tag：總 tag Module: Sandbox（來自 src/routers/private/modules/server.py）加上分區 Module: Sandbox - Settings／Environments／Tasks／Bindings／Secrets／Runs。Codegen 兩種分組都會看到。

本手冊對照後端 origin/master 撰寫（見 變更紀錄）。欄位以租戶 router 與 src/schemas/sandbox.py 為準。