KyroDB docs

Runtime API

HTTP routes, auth planes, request bodies, and response contracts.

KyroDB Runtime exposes a small HTTP API for scoped retrieval, change ingestion, traceability, and proof workflows. The Python and TypeScript SDKs wrap these routes, but understanding the planes helps you deploy safely.

Auth planes

Plane	Token policy	Purpose	Examples
Data plane	Use a dedicated data-plane bearer token.	Agent retrieval and scoped mutations.	retrieve, invalidate, change events, write-through upsert/delete, feedback
Observability plane	Use a separate read-only observability token.	Scoped evidence reads.	trace lookup, diagnosis, feedback lookup, context proof reports
Admin evidence plane	Use an observability-admin principal/token, passed as `KYRODB_OBSERVABILITY_TOKEN` or explicit `observabilityToken`.	Operational proof and replay workflows.	health, proof bundles, root-cause reports, replay capture, shadow sessions

Production deployments should keep observability-admin credentials behind a protected Backend for Frontend (BFF), backend job, or CLI workflow. Never expose runtime tokens to browsers or client-side agents.

All authenticated calls use:

Authorization: Bearer <plane-specific-token>

Usage-metered retrievals, manual invalidations, and write-through document mutations should also send:

Idempotency-Key: <stable-operation-id>

Use one key for one logical retryable operation. Do not reuse the same key for a different request body or scope. Change events use the request field source_event_id for idempotency instead of an Idempotency-Key header.

Shadow replay sessions use kyro-shadow-session-id on retrieve, record feedback, trace lookup, feedback lookup, and trace diagnosis routes. Proof, health, replay artifact, and root-cause routes do not use the shadow serving header. SDK users normally provide this with KYRODB_SHADOW_SESSION_ID or the explicit client option.

Retrieve

POST /v1/context/retrieve returns a ContextPacket: the context items plus proof of how fresh and scope-safe they are. Embedding arrays in examples are shortened for readability. Real vectors must match the connector dimension configured for the runtime.

Request

{
  "query_embedding": [0.92, 0.08, 0.02, 0.01],
  "scope": {
    "tenant_id": "acme",
    "namespace": "kb"
  },
  "filters": {
    "type": "exact",
    "key": "category",
    "value": "billing"
  },
  "top_k": 3,
  "freshness_mode": "strict",
  "include_content": true
}

Field	Required	Meaning
`query_embedding`	Yes	Numeric embedding vector for the current user task. It must match the connector collection/table dimension.
`scope.tenant_id`	Yes	Tenant isolation boundary. Runtime reuse and connector reads are partitioned by this value.
`scope.namespace`	Yes	Knowledge namespace inside the tenant, such as `kb`, `policies`, or `tickets`.
`scope.app_id`	No	Optional agent/application partition when different apps should not share reuse.
`scope.locale`	No	Optional locale partition when language changes visibility or interpretation.
`scope.auth_scope`	No	Optional permission boundary. Must be non-empty when provided.
`scope.entitlement_boundary`	No	Optional entitlement boundary. Use this canonical field name.
`scope.embedding_model_id`	No	Optional embedding model partition. Use when vector semantics or dimensions differ.
`scope.reranker_version`	No	Optional reranker partition.
`scope.prompt_template_version`	No	Optional prompt/template partition.
`filters`	No	Metadata filter applied inside the connector and reuse partition.
`top_k`	No	Number of items requested. If omitted, the runtime default is used.
`freshness_mode`	No	`strict`, `balanced`, or `eventual`. Strict blocks unsafe stale context instead of serving it.
`include_content`	No	When false, connectors should avoid returning document text where projection is supported.

Supported filter types:

Type	Shape	Semantics
`exact`	`{ "type": "exact", "key": "category", "value": "billing" }`	Match one metadata key to one string value.
`in`	`{ "type": "in", "key": "category", "values": ["billing", "refunds"] }`	Match one metadata key against a non-empty set of strings.
`range`	`{ "type": "range", "key": "updated_at_epoch", "min": 1777520000, "max": 1777523600 }`	Numeric range. At least `min` or `max` must be present.
`and`	`{ "type": "and", "filters": [...] }`	All child filters must match.
`or`	`{ "type": "or", "filters": [...] }`	At least one child filter must match.
`not`	`{ "type": "not", "filter": {...} }`	Negates a child filter.

Filter keys must be connector-executable ASCII identifiers. Values are parameterized by the runtime/connector adapters; do not concatenate user input into connector-specific query strings.

Response

{
  "packet_id": "pkt_01",
  "trace_id": "trc_01",
  "status": "complete",
  "freshness": {
    "requested_mode": "strict",
    "served_mode": "strict",
    "ownership": "event_feed",
    "generation": 184,
    "safe_as_of": "2026-05-01T10:00:03Z",
    "watermarks": [
      {
        "scope": { "type": "namespace", "tenant_id": "acme", "namespace": "kb" },
        "source": "runtime_generation",
        "token": "gen_184",
        "generation": 184,
        "observed_at": "2026-05-01T10:00:03Z"
      }
    ]
  },
  "items": [
    {
      "id": "billing-refunds-2026",
      "content": "Refunds require approval after 30 days.",
      "score": 0.87,
      "source": "backend",
      "provenance": {
        "connector": "pgvector-main",
        "namespace": "kb",
        "retrieved_at": "2026-05-01T10:00:03Z",
        "metadata": { "category": "billing" }
      }
    }
  ],
  "meta": {
    "latency_ms": 31,
    "execution_path": "backend_fetch",
    "cache_hit": false,
    "stale_pruned": 0,
    "partial": false,
    "scope_fingerprint": "scope_7d4a",
    "freshness_generation": 184
  }
}

status is one of complete, partial, degraded, or stale_blocked. freshness explains what was requested, what was actually served, the ownership mode (write_through, event_feed, snapshot_bundle, or best_effort), the generation, and any connector/runtime watermarks. items contain scored context plus provenance. omissions and warnings are omitted when empty. When present, omissions explain why candidate context was withheld, for example stale_pruned, scope_filtered, or context_budget_exceeded. meta captures execution path, cache behavior, latency, and the scope/freshness partition used for traceability.

Errors

Common failures:

HTTP	Code	Meaning
`400`	`INVALID_REQUEST`	Missing required fields, malformed scope, invalid filters, or unsupported dimensions.
`401`	`UNAUTHORIZED`	Missing or invalid bearer token for the data plane.
`402`	`PLAN_LIMIT_EXCEEDED`	Usage metering rejected the request because a plan limit was exhausted.
`403`	`SCOPE_AUTHORIZATION_FAILED`	Token claims do not allow the requested tenant, namespace, trace, connector, or operation.
`429`	`GATEWAY_RATE_LIMITED` or `RATE_LIMITED`	Gateway admission or connector rate limit rejected the request.
`503`	`CONNECTOR_UNAVAILABLE`	Connector or evidence dependency is unavailable.
`504`	`GATEWAY_TIMEOUT`	Runtime or connector exceeded its configured deadline.

Raw runtime errors include a public-safe code and error. SDKs normalize those into typed exceptions/errors:

{
  "code": "SCOPE_AUTHORIZATION_FAILED",
  "error": "request scope is not authorized by token claims"
}

Mutations and events

Use these routes to keep KyroDB aligned with changing business knowledge.

Route	Plane	Use when
`POST /v1/events/change`	Data	A source system emits durable scoped events.
`POST /v1/context/invalidate`	Data	A developer backend or integration manually invalidates a boundary.
`POST /v1/documents/upsert`	Data	KyroDB owns a certified write-through ACK.
`POST /v1/documents/delete`	Data	KyroDB owns a certified scoped delete ACK.
`POST /v1/context/feedback`	Data	A user, evaluator, or workflow reports useful, stale, irrelevant, or wrong-scope context.

A certified write-through ACK means the connector confirmed the mutation and KyroDB verified the ACK matches the requested document and storage scope. A certified scoped delete ACK applies the same guarantee to deletion: the runtime must verify the connector ACK before advancing freshness and admitting reuse.

Change event

{
  "target": {
    "type": "namespace",
    "namespace": "kb"
  },
  "change_type": "content_updated",
  "scope": {
    "tenant_id": "acme",
    "namespace": "kb"
  },
  "source_event_id": "cms-evt-2026-05-01-001",
  "timestamp": "2026-05-01T10:00:00Z"
}

Success:

{
  "accepted": true,
  "generation": 185,
  "entries_invalidated": 14,
  "detail": "namespace invalidated"
}

Manual invalidation

{
  "tenant_id": "acme",
  "target": {
    "type": "namespace",
    "namespace": "kb"
  },
  "reason": "backend forced refresh after CRM backfill"
}

Success uses the same ChangeEventResult shape as change events.

Write-through upsert

{
  "scope": {
    "tenant_id": "acme",
    "namespace": "kb"
  },
  "document": {
    "id": "billing-refunds-2026",
    "embedding": [0.92, 0.08, 0.02, 0.01],
    "content": "Refunds require approval after 30 days.",
    "metadata": {
      "category": "billing"
    }
  }
}

Success:

{
  "id": "billing-refunds-2026",
  "outcome": "updated",
  "generation": 186,
  "entries_invalidated": 3,
  "invalidated_scope": {
    "type": "document",
    "doc_id": "billing-refunds-2026"
  },
  "revision": "rev_186",
  "mutation_ack": {
    "id": "billing-refunds-2026",
    "scope": {
      "tenant_id": "acme",
      "namespace": "kb"
    },
    "verified": true
  }
}

Write-through delete

{
  "scope": {
    "tenant_id": "acme",
    "namespace": "kb"
  },
  "id": "billing-refunds-2026"
}

Success uses DocumentMutationResult with outcome set to deleted or not_found.

Feedback

{
  "trace_id": "trc_01",
  "signal": "stale",
  "item_ids": ["billing-refunds-2026"],
  "comment": "The refund window changed this morning."
}

Success:

{
  "trace_id": "trc_01",
  "signal": "stale",
  "item_ids": ["billing-refunds-2026"],
  "comment": "The refund window changed this morning.",
  "received_at": "2026-05-01T10:04:12Z",
  "trace_known": true
}

Mutation errors use the same public-safe error envelope as retrieval. Side-effecting failures may include acknowledged: true when the runtime committed part of the operation and is returning recovery evidence.

Observability

Observability tokens are server-held credentials for trace, diagnosis, feedback lookup, and proof counters. Keep them behind the KyroDB console BFF (Backend for Frontend, a backend tailored to the console UI), trusted backend jobs, or CLI workflows. Revoke them by key rotation or removing the project's server-held runtime credential reference.

Route	Purpose
`GET /v1/traces/{trace_id}`	Retrieve retained trace evidence.
`GET /v1/traces/{trace_id}/diagnosis`	Classify stale, scope, relevance, and availability incidents.
`GET /v1/context/feedback/{trace_id}`	Read feedback for a trace, including feedback accepted after trace eviction.
`GET /v1/proofs/context`	Inspect proof counters and connector certification.

Trace request:

curl https://runtime.example.com/v1/traces/trc_01 \
  -H "Authorization: Bearer $KYRODB_OBSERVABILITY_TOKEN"

Trace success:

{
  "trace_id": "trc_01",
  "timestamp": "2026-05-01T10:00:03Z",
  "scope": {
    "tenant_id": "acme",
    "namespace": "kb"
  },
  "query_hash": "14695981039346656037",
  "top_k_requested": 3,
  "freshness_mode": "strict",
  "served_freshness_mode": "strict",
  "execution_path": "backend_fetch",
  "stages": [
    {
      "stage": "connector_search",
      "ok": true,
      "latency_ms": 24
    }
  ],
  "status": "complete",
  "freshness_generation": 184,
  "items_returned": 1,
  "items_omitted": 0,
  "total_latency_ms": 31
}

Diagnosis request:

curl https://runtime.example.com/v1/traces/trc_01/diagnosis \
  -H "Authorization: Bearer $KYRODB_OBSERVABILITY_TOKEN"

Diagnosis success:

{
  "trace_id": "trc_01",
  "kind": "fresh_backend_fetch",
  "summary": "Backend fetch satisfied strict freshness.",
  "recommended_actions": []
}

Feedback lookup:

curl https://runtime.example.com/v1/context/feedback/trc_01 \
  -H "Authorization: Bearer $KYRODB_OBSERVABILITY_TOKEN"

Feedback success:

[
  {
    "trace_id": "trc_01",
    "signal": "stale",
    "received_at": "2026-05-01T10:04:12Z",
    "trace_known": true
  }
]

Context proof request:

curl https://runtime.example.com/v1/proofs/context \
  -H "Authorization: Bearer $KYRODB_OBSERVABILITY_TOKEN"

Context proof success:

{
  "generated_at": "2026-05-01T10:05:00Z",
  "traces_considered": 100,
  "feedback_entries_considered": 4,
  "reuse_hit_rate": 0.42,
  "degraded_count": 0,
  "stale_blocked_count": 3,
  "downgraded_count": 0,
  "avg_latency_ms": 31,
  "incident_counts": [],
  "feedback_signal_counts": [],
  "incident_trace_keys": [],
  "negative_feedback_trace_keys": [],
  "redactions": [],
  "proof_quality": {
    "strict_complete_count": 64,
    "strict_verified_count": 64,
    "strict_source_verified_count": 64,
    "weak_watermark_evidence_count": 0,
    "watermark_lag_count": 0,
    "watermark_ahead_count": 0,
    "watermark_lookup_failure_count": 0,
    "capability_mismatch_count": 0,
    "proof_validation_failure_count": 0,
    "generation_race_count": 0,
    "stale_reuse_served_count": 0,
    "degraded_without_reason_count": 0
  },
  "connector_certification": {
    "connector_id": "pgvector",
    "serving_safe": true,
    "strict_eligible": true,
    "ownership": "event_feed",
    "findings": []
  }
}

Scoped observability principals may receive deployment_evidence_redacted: true instead of connector_certification when deployment-level evidence is not authorized for that token.

Common observability errors:

{
  "code": "UNAUTHORIZED",
  "error": "authentication is required"
}

{
  "code": "TRACE_NOT_FOUND",
  "error": "trace evidence was not found"
}

Admin evidence

Admin routes operate on retained evidence and replay artifacts. Keep them behind protected backends, CLI workflows, or the KyroDB console BFF (Backend for Frontend, a backend tailored to the console UI).

Route	Purpose
`GET /v1/health/context`	Runtime, evidence, connector, and overload health.
`POST /v1/proofs/bundle`	Redacted proof bundle for partner/customer review.
`POST /v1/root-cause/report`	Incident/root-cause report.
`GET /v1/replay/capture`	Bounded replay capture export.
`POST /v1/replay/diff`	Baseline vs candidate replay diff.
`POST /v1/replay/counterfactual`	Isolated counterfactual replay.
`POST /v1/replay/shadow-sessions`	Candidate shadow session.

Admin evidence may contain sensitive operational metadata even when redacted. Do not call these routes directly from browsers; route them through the console BFF, enforce account/project authorization, and store only redacted summaries in the console backend.

Next guideFreshness and scope