使用 Key 呼叫既有 API：Request／Response

管理員先從 Runtime → Management API Keys 簽發 Key；外部服務將 Key 放在 X-API-Key 標頭後，即可直接呼叫現有的管理 API。以下只介紹外部串接方會使用的端點。

GET 範例：列出資料庫連線

需要 /runtime/db-management.view 權限。成功回傳 HTTP 200，Response 為 DbManagementVM 陣列；下方僅列出部分欄位。

curl -X GET "https://agent.example.com/api/DbManagement" \
  -H "X-API-Key: ${HS_MANAGEMENT_API_KEY}"

200 OK — JSON（僅列部分欄位）：

[
  {
    "id": 1,
    "name": "Production DB",
    "sqlProvider": "PostgreSql",
    "host": "db.internal",
    "database": "orders",
    "isBootstrapManaged": false
  }
]

POST 範例：建立 Custom Tool

需要 /runtime/custom-tools.create 權限。請使用實際存在的 dbManagementId，並依照目標資料庫修改 SQL Template。Request JSON 對應後端 CustomSqlTool 模型。

curl -X POST "https://agent.example.com/api/CustomSqlTool" \
  -H "X-API-Key: ${HS_MANAGEMENT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "list_orders",
    "description": "List order identifiers",
    "type": "Query",
    "sqlTemplate": "SELECT id FROM orders",
    "dbManagementId": 1
  }'

成功回傳 201 Created 與 CustomSqlTool 物件；下方展示部分由伺服器產生的欄位。

{
  "id": 42,
  "name": "list_orders",
  "description": "List order identifiers",
  "sqlTemplate": "SELECT id FROM orders",
  "type": "Query",
  "parametersJson": null,
  "dbManagementId": 1,
  "status": "Draft",
  "publishedRevisionId": null,
  "publishedIdentity": null,
  "createdAt": "2026-10-18T09:00:00Z",
  "lastModifiedAt": null
}

常見 HTTP 狀態碼

其他 API 規格

其他端點請查閱管理 HTTP API 路由參考。部分舊端點仍缺完整 Response Schema，正在 OpenAPI PR #294 補齊；不能把只有路由的清單誤認為完整 DTO 契約。