Quickstart

Endpoints

• DAL (data plane): https://dal.valkdb.dev
• API (control plane): https://api.valkdb.dev

Prefer the raw markdown? Open QUICKSTART.md.

1. Register

Register for a free account:

curl -X POST https://dal.valkdb.dev/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'

Returns an api_key with the prefix sk-valkdb-.

Or register via the dashboard.

2. Save your API key

The API key is shown only once at registration. Copy it now and store it in your secret manager (1Password, AWS Secrets Manager, Vault, etc.).

export VALKDB_API_KEY="sk-valkdb-..."

If you lose the key, register with a different email — there is no recovery yet.

3. Create a connection

curl -X POST https://dal.valkdb.dev/v1/connections \
  -H "Authorization: Bearer $VALKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staging",
    "connection_string": "postgresql://user:pass@host:5432/dbname?sslmode=require"
  }'

Save the returned id (UUID). Credentials are encrypted with AES-256-GCM at rest.

export CONNECTION_ID="<uuid-from-response>"

Need a test database? Use Neon (free tier) or any Postgres you can reach from the internet.

4. Run your first safe SELECT

curl -X POST https://dal.valkdb.dev/v1/query \
  -H "Authorization: Bearer $VALKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"sql\": \"SELECT 1 AS ok\",
    \"connection_id\": \"$CONNECTION_ID\",
    \"agent_id\": \"quickstart-agent\",
    \"session_id\": \"session-001\",
    \"task_id\": \"first-select\"
  }"

Response:

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

Identity fields (optional but recommended):

• agent_id — stable identifier for the agent
• session_id — identifier for the current session (budget scoped here)
• task_id — identifier for the current task (metadata)

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

5. Check budget

curl "https://dal.valkdb.dev/v1/budget?agent_id=quickstart-agent&session_id=session-001" \
  -H "Authorization: Bearer $VALKDB_API_KEY"

Response:

{
  "status": "active",
  "agent_id": "quickstart-agent",
  "session_id": "session-001",
  "rows":    { "used": 1, "limit": 5000, "remaining": 4999, "percent_used": 0 },
  "queries": { "used": 1, "limit": 50,   "remaining": 49,   "percent_used": 2 },
  "window":  { "seconds": 60, "remaining_seconds": 57 },
  "tables_touched":  [],
  "columns_touched": []
}

Status: active → warning (≥80%) → exhausted (blocked).

6. Review logs

curl "https://dal.valkdb.dev/v1/logs?limit=10&session_id=session-001" \
  -H "Authorization: Bearer $VALKDB_API_KEY"

Response (hash-only mode — no raw SQL stored):

[
  {
    "query_hash": "sha256:a1b2c3d4...",
    "status": "ok",
    "latency_ms": 42,
    "timestamp": "2026-05-06T10:30:00Z",
    "agent_id": "quickstart-agent",
    "session_id": "session-001",
    "task_id": "first-select",
    "decision": "allowed",
    "rows_returned": 1,
    "tables_touched": [],
    "columns_touched": []
  }
]

7. Report feedback

This is a controlled preview. Your feedback matters more than your success.

Report to feedback@valkdb.dev (or reply to the invite thread):

• What you were trying to do
• What you expected vs. what happened
• Perceived latency (be specific: "7s on /query", "duplicate register took 3s")
• Queries that got blocked when you didn't expect, or allowed when you expected a block
• Any hang >5s or unclear error

Include if possible: agent_id, session_id, the request_id from the response, and an approximate UTC timestamp.

Trust model

• ValkDB does not store query results
• In production hash-only mode, raw SQL is not stored
• Audit logs store query hashes and decision metadata only
• Connection strings are encrypted with AES-256-GCM
• No AI in the proxy — every decision is deterministic

Use ValkDB alongside RLS, read replicas, scoped DB credentials, and least-privilege access. See the full Trust Model.

Next steps

• API Reference — all endpoints, filters, configuration
• Trust Model — what's stored, what's not
• MCP Server — use with Claude, Cursor, or Kiro