REST API

Call ZizkaDB from any language with HTTP. Use this for Go, Rust, Java, Ruby, mobile, or custom integrations.

Base URL & auth

Managed: https://db.zizka.ai
Self-host: http://localhost:8000

Every request (except /health) needs:

httpAuthorization: Bearer zizkadb_live_xxxx Content-Type: application/json

API routes are under /v1/ — not /api/v1/ when calling directly. Interactive reference: /swagger

Health check (no auth)

bashcurl https://db.zizka.ai/health
# {"status":"ok","version":"0.1.0"}

Log an event

bashcurl -X POST https://db.zizka.ai/v1/events \
  -H "Authorization: Bearer zizkadb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "support-bot",
    "event": "tool_call",
    "data": { "tool": "get_billing" },
    "session_id": "sess_abc123",
    "parent_id": null
  }'
# → { "event_id": "...", "timestamp": "...", "sequence_no": 1 }

Query events

bashcurl "https://db.zizka.ai/v1/events?agent=support-bot&limit=20" \
  -H "Authorization: Bearer zizkadb_live_xxxx"

Causal chain (why)

bashcurl "https://db.zizka.ai/v1/events/EVENT_UUID_HERE/why" \
  -H "Authorization: Bearer zizkadb_live_xxxx"

Time travel (state at timestamp)

bashcurl "https://db.zizka.ai/v1/events/at?agent=support-bot&timestamp=2026-05-01T15:00:00Z" \
  -H "Authorization: Bearer zizkadb_live_xxxx"

Search (keyword, semantic or hybrid)

bashcurl -X POST https://db.zizka.ai/v1/search \
  -H "Authorization: Bearer zizkadb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "customer frustrated about billing",
    "agent": "support-bot",
    "limit": 10,
    "mode": "auto"
  }'
# mode: auto (hybrid with embeddings, keyword without), keyword, semantic, hybrid

Context for prompts

bashcurl -X POST https://db.zizka.ai/v1/memory/context \
  -H "Authorization: Bearer zizkadb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "support-bot",
    "task": "user asking about refund policy",
    "max_tokens": 2000
  }'

Agents, baseline, session diff, forget

bash# List agents
curl https://db.zizka.ai/v1/agents -H "Authorization: Bearer zizkadb_live_xxxx"

# Behavioral baseline / drift
curl "https://db.zizka.ai/v1/agents/support-bot/baseline?recent_window=50" \
  -H "Authorization: Bearer zizkadb_live_xxxx"

# Session summary
curl https://db.zizka.ai/v1/memory/diff/sess_abc123 \
  -H "Authorization: Bearer zizkadb_live_xxxx"

# GDPR erasure by metadata
curl -X DELETE https://db.zizka.ai/v1/memory/forget \
  -H "Authorization: Bearer zizkadb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"filter_key": "user_id", "filter_value": "user_123"}'

Endpoint reference

Method	Path	Purpose
POST	/v1/events	Log event (Idempotency-Key header for safe retries)
POST	/v1/events/batch	Log up to 500 events
GET	/v1/events	Query events (cursor via X-Next-Cursor)
GET	/v1/events/{id}/why	Causal chain
GET	/v1/events/at	State at timestamp
GET	/v1/events/verify	Recheck event checksums
GET	/v1/events/chain	Verify the per-agent hash chain
GET	/v1/events/export	NDJSON export
POST	/v1/events/import	Import an NDJSON export
GET	/v1/sessions/{id}/events	Session timeline across agents
POST	/v1/a2a/messages	Agent-to-agent message (agent-scoped key)
POST	/v1/search	Search (keyword, semantic, hybrid)
POST	/v1/memory/context	Prompt context
GET	/v1/memory/diff/{session_id}	Session diff
DELETE	/v1/memory/forget	GDPR erasure
GET	/v1/agents	List agents
GET	/v1/agents/{id}/baseline	Drift baseline
GET	/v1/agents/{id}/sessions	List sessions
PUT	/v1/agents/{id}/retention	Keep events N days (JWT)
POST	/v1/agents/{id}/api-keys	Create key: scope read_only, expires_in_days (JWT)
GET	/v1/settings/embeddings	Embedding config
PUT	/v1/settings/embeddings	Update embeddings (JWT)

Common errors

401 Unauthorized

Missing or invalid Bearer token. Use zizkadb_live_ key from Settings.

404 on /api/v1/...

Use /v1/ directly: https://db.zizka.ai/v1/events

403 "This API key is read-only"

Read-only keys can query, search and verify but not write. Use a read-write key for logging and forget.

413 Payload Too Large

One event's data + metadata is limited to 256 KB and a request to 10 MB. Store large blobs elsewhere and log a reference.

409 on log with a subscription notice

Your subscription is not active (past due or canceled). Update billing in Settings to continue logging.