API Reference

Authentication

All endpoints require a Bearer token:

Authorization: Bearer sk-supersonic-your-key-here

In the local preview the key is printed by scripts/init_local_preview.sh as demo_api_key.

POST /v1/query

Execute a SQL query with cumulative budget tracking.

{
  "sql": "SELECT id, name FROM users LIMIT 20",
  "connection_id": "your-connection-uuid",
  "agent_id": "my-analytics-agent",
  "session_id": "session-001",
  "task_id": "daily-report"
}

Identity fields (optional, recommended):

• agent_id — stable identifier for the agent
• session_id — identifier for the current session
• task_id — identifier for the current task

When provided, budget is scoped to agent+session. Different sessions get separate budgets.

Success response

{
  "ok": true,
  "data": { "rows": [...], "row_count": 20 },
  "request_id": "dal-abc123"
}

Budget exhausted response

{
  "ok": false,
  "error": {
    "code": "BUDGET_EXHAUSTED",
    "message": "Agent session budget exhausted: row limit reached",
    "hint": "Budget resets after the time window expires.",
    "retryable": false
  },
  "request_id": "dal-xyz789"
}

GET /v1/budget

Check current budget consumption for an agent session.

GET /v1/budget?agent_id=my-agent&session_id=session-001

Response

{
  "status": "warning",
  "agent_id": "my-agent",
  "session_id": "session-001",
  "rows": { "used": 420, "limit": 500, "remaining": 80, "percent_used": 84 },
  "queries": { "used": 7, "limit": 10, "remaining": 3, "percent_used": 70 },
  "window": { "seconds": 60, "remaining_seconds": 34 },
  "tables_touched": ["users", "orders"],
  "columns_touched": ["users.email", "users.name", "orders.total"]
}

Status values: active → warning (≥80%) → exhausted

GET /v1/schema

List tables and columns visible to the caller. Read-only. Used by the MCP valk_schema tool. Sensitive columns (password, token, secret, api_key, card_number, and similar) are stripped server-side.

GET /v1/schema?agent_id=my-agent&database=main

Query parameters (both optional):

• agent_id — captured for audit only. Authorization is enforced by the API key, never by this value.
• database — connection name or UUID owned by the API key's user. Defaults to main; in single-tenant mode it is only echoed back.

Response

{
  "database": "main",
  "tables": [
    { "name": "users",
      "schema": "public",
      "columns": [
        { "name": "id",         "type": "integer" },
        { "name": "email",      "type": "text" },
        { "name": "created_at", "type": "timestamp with time zone" }
      ] },
    { "name": "orders",
      "schema": "public",
      "columns": [
        { "name": "id",      "type": "integer" },
        { "name": "user_id", "type": "integer" },
        { "name": "total",   "type": "numeric" }
      ] }
  ]
}

System schemas (pg_catalog, information_schema, pg_toast, pg_internal) are never returned. The MCP server runs an additional scrub pass on the response, so a column that slips through upstream still cannot reach the agent.

GET /v1/logs

Query audit logs with optional filters.

GET /v1/logs?limit=10&session_id=session-001&decision=blocked

Filters (all optional):

• limit — max results (default 50, max 1000)
• agent_id — filter by agent
• session_id — filter by session
• decision — filter by decision (allowed/blocked)

In hash-only mode, raw SQL is not returned. Logs contain query_hash and decision metadata.

Other endpoints

• POST /v1/connections — register a Postgres database
• GET /v1/connections — list your connections
• DELETE /v1/connections/{id} — remove a connection
• POST /v1/agents — register an agent
• GET /v1/agents — list your agents
• POST /v1/auth/register — create account, get API key
• GET /v1/billing — usage counters (queries, connections, agents). No active pricing during the preview.
• GET /health — health check (no auth required)

Configuration

Variable	Default	Description
BUDGET_MAX_ROWS	5000	Max rows per session per window
BUDGET_MAX_QUERIES	0 (unlimited)	Max queries per window
BUDGET_WINDOW_SECS	60	Time window in seconds
BUDGET_MAX_ROWS_PER_QUERY	100	Max rows per single query

MCP Server

Use ValkDB as an MCP server with Claude Desktop, Cursor, or Kiro. The MCP server connects MCP-compatible agents to PostgreSQL through Supersonic without giving the agent database credentials. See the dedicated MCP page for tools, security model, and client configs.

During the controlled preview the source is distributed as a downloadable tarball: valkdb-mcp-server-0.1.0.tar.gz. The legacy Python server is deprecated.