# ValkDB — Quickstart

**Status:** Controlled technical preview — invited users only.
**Region:** us-west2 / Oregon.
**Latency note:** Infra currently runs in us-west2/Oregon; users from Europe/South America may see 1–2s per request end-to-end (network + TLS + Railway). Measured warm ValkDB overhead is ~3ms.

**Endpoints**

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

---

## 1. Register

```bash
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-`. You can also register from the dashboard at `https://valkdb.dev/dashboard.html`.

## 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 it for the rest of this quickstart:

```bash
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

Point ValkDB at a Postgres database you want the agent to query:

```bash
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) — it is the `connection_id` for queries. Connection strings are encrypted with AES-256-GCM at rest.

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

No Postgres handy? Use Neon (free tier) or any Postgres reachable from the public internet.

## 4. Run your first safe SELECT

```bash
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:

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

The `agent_id` + `session_id` pair is what the budget is scoped to. Different sessions get independent budgets.

## 5. Check budget

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

Response:

```json
{
  "status": "active",
  "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 transitions: `active` → `warning` (≥80%) → `exhausted`. An exhausted session is blocked until the window resets.

## 6. Review logs

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

Returns hash-only audit events. Raw SQL is **not** stored in production. Each entry carries `query_hash`, `decision`, `latency_ms`, `agent_id`, `session_id`, `task_id`, `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:

- Your `agent_id` + `session_id`
- The `request_id` from the response (field `request_id` in any `/query`, `/budget`, `/logs` reply)
- Approximate timestamp (UTC)

---

## Trust model (summary)

- No query results are stored.
- Hash-only audit logs in production (raw SQL not persisted).
- Connection strings encrypted with AES-256-GCM.
- No AI in the control path — every decision is deterministic.
- Full details: `https://valkdb.dev/security.html`

## What ValkDB does not replace

Use ValkDB **alongside** RLS, read replicas, scoped DB credentials, and least-privilege access. ValkDB adds the session budget layer on top; it does not substitute the baseline controls.