HTTP API Reference

Every endpoint Vanzik exposes, with auth requirements, request/response shapes, and status codes. Source: pkg/proxy/server.go, pkg/proxy/auth.go, pkg/proxy/tenant.go.

Base URL: http(s)://<host>:<port>
Default:  http://localhost:8080

---

URL families: legacy vs tenant-aware (v0.5+)#

Every operational endpoint is exposed at both of these paths:

{tenant} is validated against the policy registry: local is always recognised (the bundled file policy), and additional tenants are registered with vanzik tenant put <id> --policy <yaml> (requires --persist). An unregistered tenant returns 404 with body {"error":"tenant not found"}; a store infrastructure failure during tenant resolution returns 500 {"error":"policy provider error"}. /v1/check and /v1/t/local/check remain identical in responses, audit entries, and headers.

Tenant ID format constraints:

• Non-empty after URL-decoding.
• URL-safe characters only — SDKs URL-encode the value before building the path, so reserved characters (/, spaces, etc.) are escaped to %XX.
• Must be registered (or local) — unknown tenants 404.

Runtime state is partitioned by tenant. Each tenant gets isolated approvals (no cross-tenant existence oracle), rate-limit buckets (scope:tenant:agent keys), session-cost accumulators, SSE feeds, and tenant-scoped audit reads — /v1/t/<tenant>/audit only returns that tenant's entries.

The wire format (docs/WIRE_PROTOCOL.md) does not change between families: the same request body and response shape (schema_version: "v1") flow through both.

The legacy paths are not deprecated; both families are supported.

---

Auth model#

Vanzik uses two orthogonal auth schemes:

1. Bearer token (Authorization: Bearer <key>) — for machine-to-machine access. Comes from the --api-key flag on the server.
2. Session cookie + CSRF — for browser (/dashboard) access. POST /auth/login with the same API key sets an HttpOnly vanzik_session cookie and a JS-readable vanzik_csrf cookie (double-submit). State-changing endpoints additionally require X-CSRF-Token: <vanzik_csrf value>.

When the server is started without --api-key, auth middleware is a pass-through and the server binds to 127.0.0.1 only.

Auth posture is identical across both URL families — the middleware is URL-agnostic, so a token / session that works against /v1/audit works against /v1/t/local/audit and vice versa.

/v1/check is intentionally unauthenticated so local agents can call it with zero setup. Gate it at the network layer (reverse proxy allowlist, firewall, service mesh) if your threat model requires.

/api/pending, /api/stream, /api/stats and their /v1/t/{tenant}/… mirrors are registered only when the server runs --dashboard; without it they return 404.

---

POST /v1/check · POST /v1/t/{tenant}/check#

The core policy query. The SDKs wrap this. Both URL families produce identical responses; pick whichever matches your deployment topology.

Request#

POST /v1/check HTTP/1.1
Content-Type: application/json

{
  "schema_version": "v1",
  "agent_id": "my-agent",
  "scope": "shell",
  "command": "rm -rf ./old_data",
  "session_id": "sess-abc",
  "est_cost": 0.12,
  "meta": {"run_id": "123"}
}

The tenant-aware variant is exactly the same body sent to a different path:

POST /v1/t/local/check HTTP/1.1
Content-Type: application/json

{ "schema_version": "v1", "scope": "shell", "command": "ls -la" }

schema_version may be omitted (the server defaults to "v1"); any other value is rejected with 400 and an error body {"error":"unsupported schema_version; expected v1","received":"..."}. See docs/WIRE_PROTOCOL.md for the full versioning contract.

Body is limited to MaxRequestBodyBytes (default 1 MB; configurable via proxy.request.max_body_bytes). Exceeded → 413.

Response#

{
  "schema_version": "v1",
  "decision": "ALLOW",
  "reason": "Allowed by shell rule",
  "matched_rule": "allow:shell:ls *"
}

Response headers#

Status codes#

Rate-limit denials return 200 with decision: "DENY" and matched_rule: "deny:ratelimit:<scope>" — clients should treat that as a logical deny, not a transport error.

---

POST /v1/approve/{id} · POST /v1/deny/{id} · tenant-aware mirrors#

Tenant-aware mirrors live at POST /v1/t/{tenant}/approve/{id} and POST /v1/t/{tenant}/deny/{id}. Auth posture and request body are identical.

Resolve a pending approval. Resolution is write-once: the first decision stands forever. Re-sending the same decision returns 200 (idempotent no-op, safe for retried requests); sending the opposite decision returns 409 with {"error":"already resolved","id":"ap_…","status":"approved"|"denied"} and mutates nothing. A wrong decision is corrected by re-running the action through /v1/check (fresh approval id) — never by editing history. Each resolution also records how it arrived (resolved_via: bearer / session / open, plus the peer host) for incident reconstruction, and the first one writes an audit entry with matched_rule: approval:resolved:<via>.

Request (Bearer)#

POST /v1/approve/ap_1a2b…890 HTTP/1.1
Authorization: Bearer $KEY

Request (session + CSRF)#

POST /v1/approve/ap_1a2b…890 HTTP/1.1
Cookie: vanzik_session=…; vanzik_csrf=xyz…
X-CSRF-Token: xyz…

Response#

{ "id": "ap_1a2b…", "status": "approved" }    // or "denied"

Status codes#

---

GET /v1/status/{id} · tenant-aware mirror#

Tenant-aware mirror: GET /v1/t/{tenant}/status/{id}. Auth posture and response body are identical.

Poll for approval resolution. This is what guard.wait_for_approval / guard.waitForApproval hits.

Response#

{ "id": "ap_1a2b…", "status": "pending" }                              // still pending

{ "id": "ap_1a2b…", "status": "resolved", "decision": "ALLOW" }        // resolved

status: "pending" → still pending. Poll every 2 s (SDK default). The original approval request and created_at are not returned here — use GET /api/pending for those.

Status codes#

---

GET /v1/audit · tenant-aware mirror#

Tenant-aware mirror: GET /v1/t/{tenant}/audit. Auth posture and query parameters are identical. The tenant-aware URL is scoped to its tenant's entries; the legacy /v1/audit serves the local tenant.

Query the audit log.

Query parameters#

Response#

Array of entries (JSON Lines rows as JSON objects). A query that matches nothing returns null, not []; treat both as an empty result. On a sealed log the entries also carry seq, prev_hash and hash (FILE_FORMATS):

[
  {
    "timestamp": "2026-04-19T12:03:44Z",
    "agent_id": "researcher-01",
    "request": {"scope":"shell","command":"rm -rf /","agent_id":"researcher-01"},
    "result":  {"decision":"DENY","reason":"…","matched_rule":"deny:shell:…"}
  }
]

Pagination#

Use limit + offset for pagination. The default order is oldest first; add order=desc for the most recent entries:

# the 100 most recent decisions
curl -s -H "Authorization: Bearer $K" "http://localhost:8080/v1/audit?order=desc&limit=100"

# stable export pages, oldest first
curl -s -H "Authorization: Bearer $K" "http://localhost:8080/v1/audit?limit=100&offset=200"

For large exports, prefer curl over the CLI subcommand — the CLI doesn't expose offset. With order=desc, pages shift as new entries arrive; use the default order for exports.

To page by time, use since and until. since is inclusive and until is exclusive, so back-to-back windows such as [09:00, 10:00) and [10:00, 11:00) return every entry once. Both compare to the nanosecond, on both audit backends:

# one hour of decisions, oldest first
curl -s -H "Authorization: Bearer $K" \
  "http://localhost:8080/v1/audit?since=2026-10-14T09:00:00Z&until=2026-10-14T10:00:00Z&limit=1000"

If a window holds more than limit entries, page inside it with offset, or start the next request at the last entry's timestamp plus one nanosecond.

---

GET /v1/audit/head · tenant-aware mirror#

Tenant-aware mirror: GET /v1/t/{tenant}/audit/head. Same auth as GET /v1/audit: Bearer or session.

Returns the head of the sealed audit log (vanzik server --audit-seal): the newest sealed entry's seq and hash, the segment_id of the file that holds it, and when the head was read. Copy it somewhere the audit host can't rewrite; vanzik audit verify --anchor <seq>:<hash> checks it later. See OPERATIONS § Sealing and anchoring.

{"segment_id":"5f3d3bd62a0c92261d2c7de09991f4c0","seq":1200,"hash":"3f9a…","at":"2026-10-13T17:20:00Z"}

seq is 0 and hash empty until the first entry is sealed. With the buffered audit logger (the default), entries still in its queue are not in the head yet. The chain covers the whole audit file, every tenant included, so the tenant mirror returns the same head.

---

GET /v1/sessions · tenant-aware mirror#

Tenant-aware mirror: GET /v1/t/{tenant}/sessions. Same auth as GET /v1/audit: Bearer or session.

Lists the tenant's sessions: the audit entries grouped by session_id, newest first. Entries without a session_id are not part of any session. The dashboard's Sessions view is built on this route.

A session's summary covers its entries in the window. agent_id and parent_session_id pick sessions; they don't trim them.

{
  "since": "2026-10-13T10:00:00Z",
  "sessions": [
    {
      "session_id": "sub-7",
      "parent_session_id": "orch-1",
      "agents": [{"agent_id": "claude-code", "subagent": "Explore"}],
      "transports": ["claude_code"],
      "first_seen": "2026-10-14T09:12:03.5Z",
      "last_seen": "2026-10-14T09:14:40Z",
      "counts": {"total": 12, "allow": 10, "deny": 1, "require_approval": 1}
    }
  ],
  "truncated": false
}

• since and until echo the window that was searched (until is omitted when open).
• truncated is true when the window held more sessions than the file backend keeps in memory while it scans (50,000, or ten times limit if that is more). The list then has the sessions most recently written to, each counted in full; older sessions, and with agent_id or parent_session_id some matching ones, may be missing. Ask for a narrower since/until. Session ids come from /v1/check callers, so a client can make this happen by sending a new id on every call. The store backend never truncates.
• agents holds at most 32 entries and transports at most 16, the first ones seen; lists_truncated: true says some were left out. The counts always cover every entry.
• agents lists each distinct agent_id and meta.subagent pair (the Claude Code hook sets meta.subagent for calls made by a sub-agent).
• parent_session_id is the parent named by the session's first entry that names one.
• Entries with no transport count as sdk.

The file audit backend scans the live audit file (not rotated archives), like GET /v1/audit: one pass, or two with agent_id or parent_session_id, plus one more when it truncated. The store backend aggregates in SQL. Neither runs on the /v1/check path.

---

GET /v1/sessions/{id} · tenant-aware mirror#

Tenant-aware mirror: GET /v1/t/{tenant}/sessions/{id}. Same auth as GET /v1/audit.

Returns one session: its summary (same shape as in the list), the sessions it started, and its entries oldest first. URL-encode the id: session ids are chosen by the caller and may contain / or spaces (sub%2F1). The ids . and .. can't be read this way, because clients and the server collapse them as path segments; read such a session with GET /v1/audit?session_id=..

{
  "session": {"session_id": "orch-1", "agents": [...], "transports": ["sdk"], "first_seen": "...", "last_seen": "...", "counts": {...}},
  "children": [{"session_id": "sub-7", "parent_session_id": "orch-1", ...}],
  "children_truncated": false,
  "entries": [{"timestamp": "...", "session_id": "orch-1", "request": {...}, "result": {...}}],
  "truncated": false
}

truncated is true when the session has more entries than limit. Fetch the rest with since set to the last entry's timestamp plus one nanosecond, or with GET /v1/audit?session_id=…&offset=…. children holds at most 1000 sessions, newest first; children_truncated is true when there are more, or when the file backend stopped tracking them (as truncated on the list). The file backend reads the live audit file once, and a second time only when the session has children.

---

POST /v1/audit · POST /v1/t/{tenant}/audit#

Records a DENY that was decided outside the policy engine, without running the engine. vanzik-llm-proxy uses it when it refuses a tool call on its own — for example deny:llm_api_proxy:malformed_tool_call — so the central audit log records the verdict the client actually received.

Request#

POST /v1/audit HTTP/1.1
Authorization: Bearer $KEY
Content-Type: application/json

{
  "schema_version": "v1",
  "rule": "deny:llm_api_proxy:malformed_tool_call",
  "reason": "malformed tool call arguments — refused",
  "request": {"scope": "shell", "command": "bash", "agent_id": "llm-proxy", "meta": {"transport": "llm_api_proxy"}}
}

The decision is always DENY: the endpoint never takes a decision from the caller (a "decision" field in the body is ignored), so it cannot write an ALLOW into the trail.

Response#

Same shape as /v1/check. The entry goes through the same audit-write path, so it also appears on /api/stream as a check event and counts toward the decision metrics.

{"schema_version":"v1","decision":"DENY","reason":"malformed tool call arguments — refused","matched_rule":"deny:llm_api_proxy:malformed_tool_call"}

Status codes#

---

POST /auth/login#

Exchange an API key for a browser session.

Request#

{ "api_key": "<key>" }

Response#

{
  "csrf_token": "xyz…",
  "expires_at": "2026-04-19T13:00:00Z"
}

Sets cookies:

Status codes#

Constant-time compare is used on the submitted key (subtle.ConstantTimeCompare).

---

POST /auth/logout#

Destroys the current session and expires both cookies.

POST /auth/logout HTTP/1.1
Cookie: vanzik_session=…

Returns 204 No Content. Safe to call with no session (no-op).

---

GET /health#

{ "status": "ok", "version": "2.0.0" }

Always 200 once the HTTP server is accepting connections. Use for liveness probes (see DEPLOYMENT.md). For the richer operator probe see /v1/health below.

---

GET /v1/health · GET /v1/t/{tenant}/health#

Operator-grade health endpoint. Richer than /health: includes the resolved tenant, uptime, last-request and last-policy-load timestamps, and a warnings array.

Response#

{
  "status": "ok",
  "version": "2.0.0",
  "tenant": "local",
  "last_request_at": "2026-05-05T19:04:54.646Z",
  "last_policy_load_at": "2026-05-05T19:04:53.549Z",
  "uptime_seconds": 1,
  "warnings": []
}

Status codes#

---

GET /metrics#

Prometheus text exposition format. Unauthenticated. Full metric catalog in OBSERVABILITY.md.

curl -s http://localhost:8080/metrics | head
# HELP vanzik_checks_total Total number of /v1/check requests processed.
# TYPE vanzik_checks_total counter
# vanzik_checks_total 12034
# ...

---

GET /api/pending#

JSON array of unresolved approvals. Same auth as other dashboard endpoints.

[
  {
    "id": "ap_1a2b…",
    "request": {"scope":"shell","command":"rm -rf /","agent_id":"researcher-01"},
    "created_at": "2026-04-19T12:03:44Z",
    "resolved": false
  }
]

---

GET /api/stats#

O(1) atomic counter snapshot. Cheap; safe for per-page-load polling.

{
  "total": 12034,
  "allowed": 10998,
  "denied": 842,
  "approvals": 194
}

For the pending-approval count, use the length of GET /api/pending.

Prefer /api/stream (SSE) for real-time deltas — only call /api/stats on page load and on SSE reconnect.

---

GET /api/stream#

Server-Sent Events. Used by the dashboard for live updates.

GET /api/stream HTTP/1.1
Authorization: Bearer $KEY
Accept: text/event-stream

Response headers set:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no

Events:

data: {"type":"check","timestamp":"2026-04-19T12:03:44Z","request":{…},"result":{…}}\n\n

Events are unnamed SSE messages (no event: field), so an EventSource receives them through onmessage. Each carries transport (sdk, mcp_gateway, llm_api_proxy, or a coding-agent hook's claude_code, cursor, gemini_cli, codex_cli) and, for tenants other than local, tenant, alongside request and result. approval_required and denied are notifier event types (webhook / Slack / console), not stream events — see APPROVAL_WORKFLOW.md.

Subscriber channel buffer is 64 (SSEChannelBufferSize). Slow consumers drop events — counted in vanzik_sse_events_dropped_total{reason="slow_consumer"}.

The client must handle disconnects. There is no server-side auto-reconnect; use EventSource in the browser (which auto-reconnects) or handle io.EOF in a custom consumer and refetch /api/stats on reconnect.

---

GET /dashboard#

Renders loginHTML if no valid session, else dashboardHTML. Sets security headers:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: no-referrer
Cache-Control: no-store

The dashboard JS loads /api/stats, /api/pending, /v1/audit?order=desc&limit=200 (the newest 200 entries), and subscribes to /api/stream. CSRF token is read from document.cookie['vanzik_csrf'] and echoed as X-CSRF-Token on approve/deny.

---

CORS#

withCORS middleware reflects Origin:

• Strict mode (--allowed-origin https://app.example): only the exact origin is reflected.
• Permissive-localhost mode (default, --allowed-origin unset): reflects any http://localhost:* / http://127.0.0.1:* origin. The trailing : is mandatory — localhost.evil.com does not match.

Vary: Origin is always set. OPTIONS preflight short-circuits 204.

Safe because session cookies are SameSite=Strict and state-changing endpoints require X-CSRF-Token.

---

Error envelope#

Most error responses are text/plain from http.Error (e.g. "Method not allowed\n"). The structured JSON envelope is used by:

• Tenant-routing 404 (/v1/t/<unknown>/<any>): {"error":"tenant not found"}
• Tenant-routing 500 (provider infrastructure failure): {"error":"policy provider error"}
• Health 404 (/v1/t/<unknown>/health): {"error":"tenant not found"}
• Recovered panic 500: {"error":"internal server error"}
• /v1/check and POST /v1/audit schema mismatch 400: {"error":"unsupported schema_version; expected v1","received":"v2"}

Other error responses (auth 401/403, /v1/check 400 for bad JSON, audit 400 for bad ?limit) are plain-text and may differ between releases — programmatic clients should rely on the HTTP status code rather than message-text matching.

---

Common error patterns#

See TROUBLESHOOTING.md for the full symptom-keyed catalog.

---

SDK tenant_id (v0.5+)#

Both SDKs accept an optional tenant identifier that switches every HTTP call to the tenant-aware URL family.

Python:

from vanzik import Guard

# Default — legacy /v1/... URLs.
g = Guard("http://localhost:8080", agent_id="my-agent")

# Tenant-aware — /v1/t/acme/... URLs.
g = Guard("http://localhost:8080", agent_id="my-agent", tenant_id="acme")

# Env var fallback. Empty string explicitly suppresses the env var.
# Env: VANZIK_TENANT_ID=acme
g = Guard("http://localhost:8080", agent_id="my-agent")  # → /v1/t/acme/...
g = Guard("http://localhost:8080", agent_id="my-agent", tenant_id="")  # → /v1/...

tenant_id="local" is treated as an alias for the legacy URL family.

TypeScript:

import { Vanzik } from "@lictorate/vanzik";

// Default — legacy /v1/... URLs.
const local = new Vanzik({ baseUrl: "http://localhost:8080", agentId: "my-agent" });

// Tenant-aware — /v1/t/acme/... URLs.
const acme = new Vanzik({
  baseUrl: "http://localhost:8080",
  agentId: "my-agent",
  tenantId: "acme",
});

Same env-var fallback (VANZIK_TENANT_ID) and same "local" alias semantics as Python.

---

Related docs#

• docs/CLI.md — the CLI subcommands that wrap these endpoints.
• docs/DEPLOYMENT.md — reverse proxy / TLS / CORS.
• docs/OBSERVABILITY.md — full /metrics reference.
• docs/POLICY_REFERENCE.md — schema for policy evaluation behind /v1/check.
• docs/WIRE_PROTOCOL.md — schema_version contract and JSON-Schema source of truth.