Calling existing APIs: Request and Response

After issuing a key in Runtime → Management API Keys, call existing Admin REST APIs with the X-API-Key request header. The examples below describe the endpoints used by integrations.

GET example: list database connections

Required permission: /runtime/db-management.view. Returns HTTP 200 and a JSON array (DbManagementVM). Fields shown below are a subset.

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

200 OK — JSON (selected fields):

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

POST example: create a Custom Tool

Required permission: /runtime/custom-tools.create. Use a valid existing dbManagementId and adapt the SQL template to your database. The request body maps to the backend CustomSqlTool model.

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
  }'

Returns 201 Created and a CustomSqlTool response. Some server-managed properties are shown below.

{
  "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
}

Common response codes

Other endpoints

For all other Admin API paths, refer to the HTTP API route reference. Response schemas for some legacy actions are still being completed in OpenAPI PR #294; do not assume that the route listing alone defines a complete DTO contract.