API reference

kynetradb speaks JSON over HTTP. Every endpoint, auth requirement, and payload shape is listed below. A hand-written, partial OpenAPI document is served at /openapi.jsonon a running instance; it does not describe every route listed here. See the OpenAPI document page for what it covers.

Base URL

http://localhost:8080      # local
https://your-deploy.fly.dev # production

Authentication

Send your JWT as a bearer token on every request except /v1/auth/signup,/v1/auth/login, the health endpoints, and connector webhooks:

Authorization: Bearer eyJhbGciOi...

Content type

JSON requests use Content-Type: application/json. File uploads use multipart/form-data.

Errors

Non-2xx responses return a JSON envelope:

{
  "error": "validation_failed",
  "message": "field 'title' is required",
  "status": 400
}

Rate limits

Default request budgets apply by class (authentication, administration, writes, everything else) and per project, and are set by KYNETRA_RATE_LIMIT_* environment variables at start-up. Per-project quota overrides exist in the data model, but nothing in this edition sets them. See request protection.

Health & metrics

Unauthenticated probes for orchestrators. Use these in liveness/readiness checks.

GET/healthzpublic

Liveness probe. Returns 200 if the process is up.

Response
200 OK
{ "status": "ok" }
GET/readyzpublic

Readiness. Returns 200 only after WAL replay completes.

Response
200 OK
{ "ready": true, "log_seq": 1234 }
GET/metricspublic

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

GET/openapi.jsonpublic

OpenAPI 3.1 document written by hand inside the server. It is partial: it does not describe the /rest/v1, /auth/v1, /storage/v1 and /functions/v1 mounts, the WebSocket realtime endpoint, outbound webhooks, cluster provisioning, the Postgres migration job or /metrics, and it can drift from the route table.

See /capabilities/openapi-document/ for what it covers and what it leaves out.

Auth

Bcrypt-hashed passwords (cost 12) + stateless HS256 JWT. Access tokens last one hour and refresh tokens thirty days by default; both lifetimes are settings (KYNETRA_ACCESS_TTL_SECS, KYNETRA_REFRESH_TTL_SECS).

POST/v1/auth/signuppublic

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

Request
{
  "email": "you@example.com",
  "password": "strong-pw",
  "display_name": "You"
}
Response
201 Created
{ "id": "01K3...", "role": "admin" }
curl
curl -X POST $BASE/v1/auth/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"strong-pw","display_name":"You"}'
POST/v1/auth/loginpublic

Exchange credentials for a JWT.

Request
{ "email": "you@example.com", "password": "strong-pw" }
Response
200 OK
{ "token": "eyJhbGciOi...", "user": { "id": "...", "role": "admin" } }
curl
curl -X POST $BASE/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"strong-pw"}'
GET/v1/auth/mejwt

Return the authenticated user.

Response
200 OK
{ "id": "...", "email": "...", "role": "admin", "display_name": "..." }
GET/v1/auth/usersadmin

List all users. Admin only.

POST/v1/auth/usersadmin

Create a user with an explicit role. Admin only.

Request
{ "email": "...", "password": "...", "role": "editor", "display_name": "..." }
DELETE/v1/auth/users/:idadmin

Delete a user. Admin only.

Entities

Lowest-level write API. Schema-free JSON keyed by a free-form kind tag.

POST/v1/entitiesjwt

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

Request
{
  "id": "01K3...",            // optional
  "kind": "product",
  "attrs": {
    "title": "Aurora Espresso",
    "price": 2200,
    "tags": ["coffee", "espresso"]
  }
}
Response
200 OK
{ "id": "01K3...", "log_seq": 42 }
curl
curl -X POST $BASE/v1/entities \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"kind":"product","attrs":{"title":"Aurora Espresso","price":2200}}'
GET/v1/entities/:idjwt

Fetch a single entity by id.

Response
200 OK
{ "id": "...", "kind": "product", "attrs": {...}, "updated_at": 1717... }
DELETE/v1/entities/:idjwt

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

POST/v1/filterjwt

JSON predicate filter over attrs.

Request
{
  "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.

Products (ecommerce shortcut)

Convenience routes for the ecommerce shape — they wrap /v1/entities with kind="product".

POST/v1/productsjwt

Upsert a product entity.

GET/v1/products/:idjwt

Fetch a product by id.

POST/v1/products/searchjwt

BM25 search constrained to kind="product".

Collections

Typed schemas with field validation and per-operation role rules.

GET/v1/collectionsjwt

List all collections.

POST/v1/collectionsadmin

Create or update a collection definition.

Request
{
  "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"]
  },
  "created_at": 0,
  "updated_at": 0
}
GET/v1/collections/:namejwt

Fetch one collection definition.

DELETE/v1/collections/:nameadmin

Delete a collection and all its records.

GET/v1/collections/:name/recordsjwt

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

POST/v1/collections/:name/recordsjwt

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

GET/v1/collections/:name/records/:idjwt

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

PATCH/v1/collections/:name/records/:idjwt

Partial update. Rule-gated by `update`.

DELETE/v1/collections/:name/records/:idjwt

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

Files

Local filesystem or any S3-compatible backend. Object keys combine a content-hash prefix with a unique id, so identical uploads are stored separately.

GET/v1/filesjwt

List files visible to the caller.

POST/v1/filesjwt

Multipart upload. Returns file id + sha256.

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

Download raw file bytes.

GET/v1/files/:id/metajwt

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

DELETE/v1/files/:idjwt

Delete file (gated by ownership or admin role).

Realtime (SSE)

Server-Sent Events stream of writes matching the filter. This stream and the change feed are operator interfaces, not client APIs, and their events are not filtered per row. Client applications subscribe through the realtime WebSocket at /realtime/v1, which applies row-level policy per subscriber.

GET/v1/realtimejwt

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

Request
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
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.

LLM runtime

Unified completion API in front of Ollama, Anthropic, and OpenAI.

GET/v1/llm/providersjwt

List configured LLM providers and their models.

POST/v1/llm/completejwt

Provider-agnostic completion. Cost tracked per call.

Request
{
  "provider": "anthropic",
  "model": "claude-opus-4-7",
  "messages": [{ "role": "user", "content": "Hello" }],
  "max_tokens": 256,
  "temperature": 0.2
}
Response
200 OK
{
  "content": "...",
  "input_tokens": 12,
  "output_tokens": 34,
  "cost_usd": 0.00021
}

GDPR

Right-to-export and right-to-be-forgotten endpoints.

POST/v1/gdpr/exportadmin

Admin only. Export the data held for one user as JSON. The user is named by user_id in the request body.

Request
{ "user_id": "01K3..." }

The export is refused above 100,000 entities.

DELETE/v1/gdpr/user/:idadmin

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

Stats & connectors

Engine introspection. E-commerce connector webhooks are not available yet; the connectors are a roadmap item.

GET/v1/statsjwt

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

GET/v1/connectorsjwt

List the names of the e-commerce connector adapters in the engine repository. They are not wired to the server yet.

POST/v1/connectors/:name/webhookadmin

E-commerce connector webhooks are not available yet (roadmap). The route acknowledges a request and imports nothing.

See /capabilities/ecommerce-connectors/. Do not point a platform at this route.

Admin — Database

Cloudflare D1-style admin surface. All routes require Admin role.

GET/admin/db/overviewadmin

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

GET/admin/db/metricsadmin

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

POST/admin/db/console/executeadmin

Run a typed admin query from the embedded REPL.

GET/admin/db/time-traveladmin

List snapshot points for point-in-time restore.

POST/admin/db/restoreadmin

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

GET/admin/db/restore-backupsadmin

List backups produced by prior restores.

POST/admin/db/restore-undoadmin

Roll back the most recent restore using its safety backup.

POST/admin/db/delete-alladmin

Wipe everything. Irreversible; requires explicit confirmation token.

GET/admin/db/settingsadmin

Boot-time settings snapshot.

GET/admin/db/sloadmin

Per-route p50/p95/p99 SLO tracker.

GET/admin/db/collectionsadmin

Per-collection row counts + write rate.

GET/admin/db/cost-per-writeadmin

Estimated $/MM writes by storage + sink fanout.

Admin — Agents

Author, run, schedule, and approve LLM tool-use agents.

GET/admin/actionsadmin

List the 18 registered actions agents can call, with their effect and whether approval is required.

GET/admin/agentsadmin

List all agents.

POST/admin/agentsadmin

Create or update an agent definition.

POST/admin/agents/:id/runadmin

Run an agent synchronously and return the full transcript.

POST/admin/agents/:id/run/streamadmin

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

GET/admin/agents/:id/runsadmin

List historical runs for one agent.

GET/admin/runsadmin

Global run log across all agents.

GET/admin/agents/runs/summaryadmin

Aggregate token + cost totals.

POST/admin/agents/schedulesadmin

Schedule an agent to run on a cron expression.

GET/admin/agents/schedulesadmin

List schedules.

DELETE/admin/agents/schedules/:idadmin

Delete a schedule.

GET/admin/agents/approvalsadmin

Pending approval requests from agent runs.

POST/admin/agents/approvals/:id/approveadmin

Approve a paused action; agent resumes.

POST/admin/agents/approvals/:id/rejectadmin

Reject; agent terminates with reason.

Admin — Sinks, providers, integrations

Outbound DB mirroring, multi-cloud control plane, and inbound integrations.

GET/admin/sinksadmin

List configured outbound DB sinks.

POST/admin/sinks/pingadmin

Smoke-test every sink concurrently.

GET/admin/providersadmin

List cloud providers configured for deploys.

POST/admin/providersadmin

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

GET/admin/providers/catalogadmin

List the 15 provider adapters + required fields.

GET/admin/providers/:idadmin

Fetch one provider.

DELETE/admin/providers/:idadmin

Remove a provider.

POST/admin/providers/:id/testadmin

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

GET/admin/providers/:id/instancesadmin

List deployed instances under this provider.

POST/admin/providers/:id/deployadmin

Create a service or virtual machine from an image you supply. Not a tested installer.

DELETE/admin/providers/:id/instances/:instance_idadmin

Destroy an instance.

GET/admin/connect/optionsadmin

Snippets for the 12 frameworks shown in the Connect tab.

GET/admin/connect/agent-promptadmin

Copy-ready system prompt for connecting an LLM agent.

GET/admin/connect/connection-stringadmin

Canonical kynetra:// connection string.

GET/admin/integrationsadmin

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

POST/admin/integrations/:name/testadmin

Verify an integration's credentials.