Scout API 與整合參考
人工決策應使用產品介面；受控自動化可以使用 REST API。部署環境的 OpenAPI 是欄位與請求格式的正式參考。
認證與範圍
- 使用平台認證，確認 account 位於目標租戶。
- Scout endpoint 需要對應
scout.*權限。 - 直接 Harness read 需要
platform.harness.read。 - 不可用不受信任的 tenant ID 作授權判斷。
- Service-account credential 必須放入平台 secret system。
Scout API
| 方法 | Endpoint | 權限 | 用途 |
|---|---|---|---|
POST/GET | /api/v1/scout/missions | scout.write / scout.read | 建立或查詢 Mission |
GET | /api/v1/scout/missions/{missionId} | scout.read | Mission summary 與 next action |
POST | /api/v1/scout/missions/{missionId}/snapshot | scout.write | 新增 refreshed snapshot binding |
POST | /api/v1/scout/missions/{missionId}/discovery | scout.write | 啟動 discovery |
GET | /api/v1/scout/missions/{missionId}/coverage[/{rowKey}] | scout.read | Coverage 清單或單列 |
GET/POST | /api/v1/scout/missions/{missionId}/workbench[/candidates] | scout.read / scout.write | 查詢或建立 candidate |
POST | /api/v1/scout/missions/{missionId}/workbench/candidates/{candidateId}/decision | scout.write | 帶 reason/version 接受或拒絕 |
GET | /api/v1/scout/contracts[/{contractId}] | scout.read | Contract registry/detail |
POST | /api/v1/scout/contracts/{contractId}/versions/{version}/shadow | scout.write | DRAFT 到 SHADOW |
POST | /api/v1/scout/contracts/{contractId}/versions/{version}/approve | scout.approve | SHADOW 到 APPROVED |
POST | /api/v1/scout/contracts/{contractId}/versions/{version}/deploy | scout.deploy | APPROVED 到 DEPLOYED |
GET | /api/v1/scout/missions/{missionId}/runtime-evidence | scout.read | 對帳執行證據 |
Platform Harness Endpoints
| 方法 | Endpoint | 用途 |
|---|---|---|
GET | /api/v1/platform/harness/v1/capabilities | 查詢 snapshot components 與 limits |
POST | /api/v1/platform/harness/v1/snapshots | 建立或解析授權的 immutable snapshot |
GET | /api/v1/platform/harness/v1/snapshots/{snapshotId} | 讀取 frozen manifest |
GET | /api/v1/platform/harness/v1/snapshots/{snapshotId}/components/{component} | 分頁讀取一個 frozen component |
Scout 使用平台 Harness，不可建立 Scout-private context assembler。
自動化順序
create Mission -> read snapshot -> read Coverage -> create/decide candidate
-> read contract -> Shadow -> approve -> deploy -> read Runtime Evidence
路由成功不是完成證據；必須對帳相同 Mission、snapshot、row、candidate、contract/version、source、Twin、binding、installation、consumption evidence 與 result ID。
冪等、並行與錯誤
建立不可變 workflow receipt 的 mutation 使用 UUID Idempotency-Key；只在重試同一邏輯請求時重用。Decision 與 transition 也帶 expectedVersion，衝突後應 reload/review。
401 重新認證；403 檢查 entitlement/module/tenant/permission；404 核對 tenant-scoped ID；409 重新載入狀態；429 依 server window backoff；5xx 保存 trace ID 並只重試安全且冪等的操作。
目前版本不提供公開的 Scout MCP 工具或簽名外部快照匯出。請只使用目前環境 OpenAPI 中正式發布的介面。