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 # productionAuthentication
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.
/healthzpublicLiveness probe. Returns 200 if the process is up.
200 OK
{ "status": "ok" }/readyzpublicReadiness. Returns 200 only after WAL replay completes.
200 OK
{ "ready": true, "log_seq": 1234 }/metricspublicPrometheus metrics: per-route p50/p95/p99, write tput, SLO breaches.
/openapi.jsonpublicOpenAPI 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).
/v1/auth/signuppublicCreate 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"}'/v1/auth/loginpublicExchange 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"}'/v1/auth/mejwtReturn the authenticated user.
200 OK
{ "id": "...", "email": "...", "role": "admin", "display_name": "..." }/v1/auth/usersadminList all users. Admin only.
/v1/auth/usersadminCreate a user with an explicit role. Admin only.
{ "email": "...", "password": "...", "role": "editor", "display_name": "..." }/v1/auth/users/:idadminDelete a user. Admin only.
Entities
Lowest-level write API. Schema-free JSON keyed by a free-form kind tag.
/v1/entitiesjwtUpsert 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}}'/v1/entities/:idjwtFetch a single entity by id.
200 OK
{ "id": "...", "kind": "product", "attrs": {...}, "updated_at": 1717... }/v1/entities/:idjwtTombstone delete. Entity is removed from all indexes; tombstone persists in WAL.
/v1/filterjwtJSON 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.
Search & vector
BM25 full-text plus exact cosine vector search. Both are described against the same entity state as KV. The HNSW and SPANN vector indexes are implemented in the engine but are not yet enabled by the server.
/v1/searchjwtBM25 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": {...} },
...
]
}/v1/vectorjwtExact cosine search over the embedding stored on each entity.
{
"vector": [0.012, -0.34, ...],
"top_k": 10,
"kind": "product"
}Dimensionality is fixed by the first vector inserted; mismatched dims are rejected.
Products (ecommerce shortcut)
Convenience routes for the ecommerce shape — they wrap /v1/entities with kind="product".
/v1/productsjwtUpsert a product entity.
/v1/products/:idjwtFetch a product by id.
/v1/products/searchjwtBM25 search constrained to kind="product".
Collections
Typed schemas with field validation and per-operation role rules.
/v1/collectionsjwtList all collections.
/v1/collectionsadminCreate 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"]
},
"created_at": 0,
"updated_at": 0
}/v1/collections/:namejwtFetch one collection definition.
/v1/collections/:nameadminDelete a collection and all its records.
/v1/collections/:name/recordsjwtList records (rule-gated by `list`).
/v1/collections/:name/recordsjwtCreate a record. Rule-gated by `create`.
/v1/collections/:name/records/:idjwtFetch a record. Rule-gated by `view`.
/v1/collections/:name/records/:idjwtPartial update. Rule-gated by `update`.
/v1/collections/:name/records/:idjwtDelete 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.
/v1/filesjwtList files visible to the caller.
/v1/filesjwtMultipart upload. Returns file id + sha256.
curl -X POST $BASE/v1/files \
-H "Authorization: Bearer $TOKEN" \
-F file=@image.png/v1/files/:idjwtDownload raw file bytes.
/v1/files/:id/metajwtFetch file metadata: name, size, sha256, content type, uploader.
/v1/files/:idjwtDelete 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.
/v1/realtimejwtSubscribe 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.
LLM runtime
Unified completion API in front of Ollama, Anthropic, and OpenAI.
/v1/llm/providersjwtList configured LLM providers and their models.
/v1/llm/completejwtProvider-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
}GDPR
Right-to-export and right-to-be-forgotten endpoints.
/v1/gdpr/exportadminAdmin only. Export the data held for one user as JSON. The user is named by user_id in the request body.
{ "user_id": "01K3..." }The export is refused above 100,000 entities.
/v1/gdpr/user/:idadminHard-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.
/v1/statsjwtHigh-level engine stats: entity count, log_seq, index sizes, uptime.
/v1/connectorsjwtList the names of the e-commerce connector adapters in the engine repository. They are not wired to the server yet.
/v1/connectors/:name/webhookadminE-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.
/admin/db/overviewadminStat cards: entity count, write rate, storage on disk.
/admin/db/metricsadmin24h rolling read/write counters for the live dashboard.
/admin/db/console/executeadminRun a typed admin query from the embedded REPL.
/admin/db/time-traveladminList snapshot points for point-in-time restore.
/admin/db/restoreadminRestore to a snapshot. Creates a backup of current state first.
/admin/db/restore-backupsadminList backups produced by prior restores.
/admin/db/restore-undoadminRoll back the most recent restore using its safety backup.
/admin/db/delete-alladminWipe everything. Irreversible; requires explicit confirmation token.
/admin/db/settingsadminBoot-time settings snapshot.
/admin/db/sloadminPer-route p50/p95/p99 SLO tracker.
/admin/db/collectionsadminPer-collection row counts + write rate.
/admin/db/cost-per-writeadminEstimated $/MM writes by storage + sink fanout.
Admin — Agents
Author, run, schedule, and approve LLM tool-use agents.
/admin/actionsadminList the 18 registered actions agents can call, with their effect and whether approval is required.
/admin/agentsadminList all agents.
/admin/agentsadminCreate or update an agent definition.
/admin/agents/:id/runadminRun an agent synchronously and return the full transcript.
/admin/agents/:id/run/streamadminRun an agent with SSE streaming of tokens + tool calls.
/admin/agents/:id/runsadminList historical runs for one agent.
/admin/runsadminGlobal run log across all agents.
/admin/agents/runs/summaryadminAggregate token + cost totals.
/admin/agents/schedulesadminSchedule an agent to run on a cron expression.
/admin/agents/schedulesadminList schedules.
/admin/agents/schedules/:idadminDelete a schedule.
/admin/agents/approvalsadminPending approval requests from agent runs.
/admin/agents/approvals/:id/approveadminApprove a paused action; agent resumes.
/admin/agents/approvals/:id/rejectadminReject; agent terminates with reason.
Admin — Sinks, providers, integrations
Outbound DB mirroring, multi-cloud control plane, and inbound integrations.
/admin/sinksadminList configured outbound DB sinks.
/admin/sinks/pingadminSmoke-test every sink concurrently.
/admin/providersadminList cloud providers configured for deploys.
/admin/providersadminAdd a provider (credentials AES-256-GCM encrypted in the WAL).
/admin/providers/catalogadminList the 15 provider adapters + required fields.
/admin/providers/:idadminFetch one provider.
/admin/providers/:idadminRemove a provider.
/admin/providers/:id/testadminVerify credentials by calling the provider's health/list API.
/admin/providers/:id/instancesadminList deployed instances under this provider.
/admin/providers/:id/deployadminCreate a service or virtual machine from an image you supply. Not a tested installer.
/admin/providers/:id/instances/:instance_idadminDestroy an instance.
/admin/connect/optionsadminSnippets for the 12 frameworks shown in the Connect tab.
/admin/connect/agent-promptadminCopy-ready system prompt for connecting an LLM agent.
/admin/connect/connection-stringadminCanonical kynetra:// connection string.
/admin/integrationsadminList inbound integrations (Shopify, Stripe, etc.).
/admin/integrations/:name/testadminVerify an integration's credentials.