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

Use runtime tokens from trusted server code: API routes, backend jobs, CLI workflows, or KyroDB console-authorized server routes. Browser and mobile clients call your application backend instead of carrying KyroDB bearer tokens.

All authenticated calls use:

Authorization: Bearer <plane-specific-token>

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

Idempotency-Key: <stable-operation-id>

Use one key for one logical retryable operation. A repeated key is valid only for the same request body and 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, manual invalidation, change-event ingest, document upsert/delete, feedback record/lookup, trace lookup, and trace diagnosis routes. Proof, health, replay artifact, root-cause, and shadow-session creation 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 and connector adapters; build connector queries through the SDK/runtime filter model.

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,
    "proof_diagnostics": {
      "proof_status": "source_backed",
      "proof_invalidating_diagnostic_count": 0,
      "guard_rejection_count": 0,
      "watermark_count": 2,
      "source_native_watermark_count": 1,
      "source_bridged_watermark_count": 1,
      "runtime_generation_watermark_count": 1
    }
  }
}

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.

For 429 responses, honor a Retry-After header when present; otherwise retry with exponential backoff and jitter. Back off instead of increasing concurrent requests. If 429 persists, reduce backend concurrency for that runtime and check the console health view before treating the response as a correctness failure.

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.

Default managed pgvector runtimes are event-feed first: your application writes Postgres directly, commits the source change, then sends KyroDB a scoped change event with a stable source_event_id. Write-through upsert/delete routes remain part of the public API, but they require an explicitly certified and provisioned write-through runtime and are not enabled by default.

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

Use this route only when the runtime is explicitly certified and provisioned for write-through mutation ACKs. Default managed pgvector runtimes should write Postgres directly and use POST /v1/events/change after commit.

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

Use this route only when the runtime is explicitly certified and provisioned for write-through mutation ACKs. Default managed pgvector runtimes should delete from Postgres directly and use POST /v1/events/change after commit.

{
  "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 backend credentials for trace, diagnosis, feedback lookup, and proof counters. Use them from KyroDB console-authorized server routes, trusted backend jobs, or CLI workflows. Revoke them by key rotation or removing the project's 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",
      "duration_ms": 24,
      "hit": false,
      "items_produced": 1
    }
  ],
  "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. Use them from protected backends, CLI workflows, or KyroDB console-authorized server routes.

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. Browser and mobile clients should reach these workflows through an authorized backend route that enforces account and project access, and console storage should keep only redacted summaries.

Next guideFreshness and scope