hs-sql-agent
2.0.2
文件 2.0.2
文件版本
2.0.2 最新
2.0.2 最新
文件 參考

Admin HTTP API Reference

Bundled Admin UI 使用的 hs-sql-agent 2.0.1 source-backed HTTP controller surface。

Auth & identity Sign-in、refresh、OIDC、MFA、password recovery、account、sessions、members、roles。
Runtime control Databases、MCP keys、semantic metadata、custom tools、security policy、audit、operability。
MCP is separate /mcp Streamable HTTP transport 不屬於這份 Admin REST reference。

這頁記錄 hs-sql-agent 2.0.1 source 真正存在的 controller routes；bundled Admin UI 使用的就是這個 surface。

Authentication 與 authorization

大部分 Admin route 需要 authenticated Admin identity；受保護 runtime action 還會檢查 path/action permission，例如 /runtime/db-management → view、/auth/role → edit。

First-run/sign-in/sign-up、部分 OIDC、password recovery、MFA challenge completion 等必須在 session 建立前開始的流程有 anonymous exceptions。

請見 Permissions。

Auth — /api/Auth

MethodRoutePurpose
GET/api/Auth/first-run檢查 initial-setup state
POST/api/Auth/sign-inAdmin sign-in
POST/api/Auth/sign-upallowed first-run flow 建立第一個 Admin
POST/api/Auth/refresh-tokenrefresh credential exchange
POST/api/Auth/sign-out結束 current session
GET/api/Auth/sessions列出 current user sessions
DELETE/api/Auth/sessions/{sessionId}revoke 一個 session
DELETE/api/Auth/sessionsrevoke 其他 sessions
GET/api/Auth/oidc/status檢查 OIDC availability
GET/api/Auth/oidc/login開始 OIDC login
GET/api/Auth/oidc/callbackexternal-login callback
POST/api/Auth/oidc/exchangeexchange short-lived OIDC login code
GET/api/Auth/mfa/status檢查 MFA state
POST/api/Auth/mfa/setup開始 TOTP setup
POST/api/Auth/mfa/confirmconfirm TOTP setup
POST/api/Auth/mfa/disable驗證後 disable TOTP
POST/api/Auth/mfa/verify完成 MFA sign-in challenge
POST/api/Auth/forgot-passwordrequest password reset
POST/api/Auth/reset-passwordconsume reset token
GET/api/Auth/account讀 current account
PUT/api/Auth/accountupdate username/email
PUT/api/Auth/account/passwordchange password

Members — /api/Member

MethodRoutePermission
POST/api/Member/auth/user → create
GET/api/Member/auth/user → view
PUT/api/Member/{id}/roles/auth/user → edit
PUT/api/Member/{id}/status/auth/user → edit
DELETE/api/Member/{id}/sessions/auth/user → edit
PUT/api/Member/{id}/password-change-required/auth/user → edit
DELETE/api/Member/{id}/auth/user → delete

Self-lockout guardrail 請見 Members 與 Roles。

Roles — /api/Role

MethodRoutePermission
GET/api/Role/auth/role → view
POST/api/Role/auth/role → create
PUT/api/Role/{id}/auth/role → edit
DELETE/api/Role/{id}?force=false/auth/role → delete
GET/api/Role/{id}/dependencies/auth/role → view
GET/api/Role/permission-action-templates/auth/role → view

Database Management — /api/DbManagement

MethodRoutePermission
GET/api/DbManagementDB management view
GET/api/DbManagement/{id}DB management view
POST/api/DbManagementDB management create
PUT/api/DbManagement/{id}DB management edit
DELETE/api/DbManagement/{id}DB management delete
GET/api/DbManagement/{id}/schemasDB management view
GET/api/DbManagement/{id}/tables?schema=...DB management view
GET/api/DbManagement/{id}/columns?schema=...&table=...DB management view

這裡 DB management 代表 /runtime/db-management。

Semantic metadata — /api/DbSemantic

MethodRoutePermission
GET/api/DbSemantic/{dbManagementId}semantic view
GET/api/DbSemantic/{dbManagementId}/modelsemantic view
POST/api/DbSemanticsemantic edit
DELETE/api/DbSemantic/{id}semantic edit
POST/api/DbSemantic/relationshipsemantic edit
DELETE/api/DbSemantic/relationship/{id}semantic edit
POST/api/DbSemantic/metricsemantic edit
DELETE/api/DbSemantic/metric/{id}semantic edit

semantic 代表 /runtime/db-management/semantic。

MCP-key runtime — /api/runtime

MethodRoutePermission
GET/api/runtime/mcp-keysMCP keys view
GET/api/runtime/mcp-keys/available-tools?dbManagementId=...MCP keys view
POST/api/runtime/mcp-keysMCP keys create
PUT/api/runtime/mcp-keys/{id}MCP keys edit
POST/api/runtime/mcp-keys/{id}/rotateMCP keys edit
POST/api/runtime/mcp-keys/{id}/cloneMCP keys create
POST/api/runtime/mcp-keys/{id}/revokeMCP keys revoke
POST/api/runtime/mcp-keys/test-db-connectionconfigured MCP-key/DB create-edit permissions 之一
GET/api/runtime/client-configMCP keys view

Client-config route 回傳產生 MCP client setup 使用的 configured public endpoint。

Custom Tools — /api/CustomSqlTool

MethodRoutePurpose
GET/api/CustomSqlToollist
GET/api/CustomSqlTool/{id}get one
POST/api/CustomSqlToolcreate draft
PUT/api/CustomSqlTool/{id}edit draft
DELETE/api/CustomSqlTool/{id}delete
GET/api/CustomSqlTool/{id}/revisionsrevisions
GET/api/CustomSqlTool/{id}/impactimpact/dependencies
POST/api/CustomSqlTool/{id}/publishvalidate + publish
POST/api/CustomSqlTool/{id}/disabledisable
POST/api/CustomSqlTool/{id}/rollback/{revisionId}validate + rollback
POST/api/CustomSqlTool/test-executetest；DML 只 preview、不 commit

這些 route 依操作使用 /runtime/custom-tools 的 view、create、edit、delete。

Audit / Operability — /api/runtime

AreaRoutes
Audit/audit, /audit/daily-summary, /audit/export, /audit/retention, /audit/retention/dry-run, /audit/retention/execute
Operability/operability/metrics, /operability/db-health, /operability/key-usage, /operability/deliveries, /operability/deliveries/{id}/retry

Filter、response fields、permissions 請見 Audit 與 Operability。

Security Policy — /api/runtime/security

MethodRoutePermission
GET/api/runtime/security/runtime/security → view
PUT/api/runtime/security/runtime/security → edit

Credential status

2.0.1 有 GET /api/Credential/status，只回傳簡單 Credential API running status；controller 本身沒有 [Authorize] attribute。把它視為 narrow status endpoint，不是 authenticated credential-management API。

Errors 與 compatibility

Controllers 使用一般 HTTP status code：例如 validation 400、authentication/authorization 401/403、resource missing 404、conflict 409、oversized audit export 413，以及某些 bounded SQL pressure path 的 429。

外部 automation 若直接依賴這套 API，請 pin 2.0.1 並驗證自己實際消費的 response model。這份文件刻意記錄 routes 與重要 contract，不把所有 Admin view model 假裝成永久 versioned external SDK。