API reference

Liveness probe. Returns 200 if the process is up.

200 OK
{ "status": "ok" }

Readiness. Returns 200 only after WAL replay completes.

200 OK
{ "ready": true, "log_seq": 1234 }

Prometheus metrics: per-route p50/p95/p99, write tput, SLO breaches.

Full OpenAPI 3.1 spec generated from the route table.

Create a user. The first signup becomes Admin; subsequent users are Editor.

{
  "email": "you@example.com",
  "password": "strong-pw",
  "display_name": "You"
}

201 Created
{ "id": "01K3...", "role": "admin" }

curl -X POST $BASE/v1/auth/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"strong-pw","display_name":"You"}'

Exchange credentials for a JWT.

{ "email": "you@example.com", "password": "strong-pw" }

200 OK
{ "token": "eyJhbGciOi...", "user": { "id": "...", "role": "admin" } }

curl -X POST $BASE/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"strong-pw"}'

Return the authenticated user.

200 OK
{ "id": "...", "email": "...", "role": "admin", "display_name": "..." }

List all users. Admin only.

Create a user with an explicit role. Admin only.

{ "email": "...", "password": "...", "role": "editor", "display_name": "..." }

Delete a user. Admin only.

Upsert an entity. Omit id to auto-assign a ULID.

{
  "id": "01K3...",            // optional
  "kind": "product",
  "attrs": {
    "title": "Aurora Espresso",
    "price": 2200,
    "tags": ["coffee", "espresso"]
  }
}

200 OK
{ "id": "01K3...", "log_seq": 42 }

curl -X POST $BASE/v1/entities \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"kind":"product","attrs":{"title":"Aurora Espresso","price":2200}}'

Fetch a single entity by id.

200 OK
{ "id": "...", "kind": "product", "attrs": {...}, "updated_at": 1717... }

Tombstone delete. Entity is removed from all indexes; tombstone persists in WAL.

JSON predicate filter over attrs.

{
  "kind": "product",
  "where": {
    "and": [
      { "field": "price", "op": "lt",  "value": 5000 },
      { "field": "vendor", "op": "eq", "value": "Aurora" }
    ]
  },
  "limit": 50
}

Ops: eq, neq, gt, gte, lt, lte, in, nin, contains, starts_with. Logical: and, or, not.

BM25 full-text search over indexed text fields in attrs.

{
  "q": "espresso colombian",
  "top_k": 10,
  "kind": "product"        // optional filter
}

200 OK
{
  "hits": [
    { "id": "01K3...", "score": 4.21, "kind": "product", "attrs": {...} },
    ...
  ]
}

Cosine ANN search over attrs.vector embeddings.

{
  "vector": [0.012, -0.34, ...],
  "top_k": 10,
  "kind": "product"
}

Dimensionality is fixed by the first vector inserted; mismatched dims are rejected.

Upsert a product entity.

Fetch a product by id.

BM25 search constrained to kind="product".

List all collections.

Create or update a collection definition.

{
  "name": "posts",
  "fields": [
    { "name": "title", "type": "text", "required": true },
    { "name": "body",  "type": "long_text" },
    { "name": "tags",  "type": "json" }
  ],
  "rules": {
    "list":   ["admin", "editor"],
    "view":   ["admin", "editor"],
    "create": ["admin", "editor"],
    "update": ["admin", "editor"],
    "delete": ["admin"]
  }
}

Fetch one collection definition.

Delete a collection and all its records.

List records (rule-gated by `list`).

Create a record. Rule-gated by `create`.

Fetch a record. Rule-gated by `view`.

Partial update. Rule-gated by `update`.

Delete a record. Rule-gated by `delete`.

List files visible to the caller.

Multipart upload. Returns file id + sha256.

curl -X POST $BASE/v1/files \
  -H "Authorization: Bearer $TOKEN" \
  -F file=@image.png

Download raw file bytes.

Fetch file metadata: name, size, sha256, content type, uploader.

Delete file (gated by ownership or admin role).

Subscribe to live writes. Filter by topics and kinds via query params.

Query params:
  topics=entities,files,collections     (comma-sep)
  kinds=product,article                 (comma-sep)

Event format:
  event: change
  data:  { "op":"put", "kind":"product", "id":"01K...", "log_seq":42 }

curl -N -H "Authorization: Bearer $TOKEN" \
  "$BASE/v1/realtime?topics=entities&kinds=product"

Uses tokio::broadcast under the hood. Slow consumers see dropped-message SSE comments rather than blocking writers.

List configured LLM providers and their models.

Provider-agnostic completion. Cost tracked per call.

{
  "provider": "anthropic",
  "model": "claude-opus-4-7",
  "messages": [{ "role": "user", "content": "Hello" }],
  "max_tokens": 256,
  "temperature": 0.2
}

200 OK
{
  "content": "...",
  "input_tokens": 12,
  "output_tokens": 34,
  "cost_usd": 0.00021
}

Stream every entity, record, and file owned by the authenticated user as JSON.

Hard-erase a user and tombstone everything they ever wrote. Append-only audit entry remains.

High-level engine stats: entity count, log_seq, index sizes, uptime.

List configured inbound connectors (Shopify, Stripe, etc.).

Receive a webhook payload. HMAC-verified per-connector secret.

Public route — auth is via per-connector webhook secret, not JWT.

Stat cards: entity count, write rate, storage on disk.

24h rolling read/write counters for the live dashboard.

Run a typed admin query from the embedded REPL.

List snapshot points for point-in-time restore.

Restore to a snapshot. Creates a backup of current state first.

List backups produced by prior restores.

Roll back the most recent restore using its safety backup.

Wipe everything. Irreversible; requires explicit confirmation token.

Boot-time settings snapshot.

Per-route p50/p95/p99 SLO tracker.

Per-collection row counts + write rate.

Estimated $/MM writes by storage + sink fanout.

List the 10 typed actions agents can call.

List all agents.

Create or update an agent definition.

Run an agent synchronously and return the full transcript.

Run an agent with SSE streaming of tokens + tool calls.

List historical runs for one agent.

Global run log across all agents.

Aggregate token + cost totals.

Schedule an agent to run on a cron expression.

List schedules.

Delete a schedule.

Pending approval requests from agent runs.

Approve a paused action; agent resumes.

Reject; agent terminates with reason.

List configured outbound DB sinks.

Smoke-test every sink concurrently.

List cloud providers configured for deploys.

Add a provider (credentials AES-256-GCM encrypted in the WAL).

List the 10 supported providers + required fields.

Fetch one provider.

Remove a provider.

Verify credentials by calling the provider's health/list API.

List deployed instances under this provider.

Provision a new kynetradb instance on this provider.

Destroy an instance.

Snippets for the 12 frameworks shown in the Connect tab.

Copy-ready system prompt for connecting an LLM agent.

Canonical kynetra:// connection string.

List inbound integrations (Shopify, Stripe, etc.).

Verify an integration's credentials.