ValkDB — Docs

Authentication

All endpoints require a Bearer token:

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

Get your key via POST /v1/auth/register or the dashboard.

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/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, Cursor, or Kiro. See mcp-server/README.md for setup.

API Reference