APIs, integrations & migration

Discovery document

Lets tools and other Kynetra products find the interfaces, runtime shape and connection contract of a running instance without hard-coded URLs.

Available in previewEngine edition 5f8ea3af

What it does

GET /.well-known/kynetra returns a versioned, secret-free JSON document. It names the base paths of the REST, MCP, telemetry and OpenAPI surfaces, the runtime profile, node role and storage backend, a connection contract, and a short capability list in which each item carries a status, including one marked roadmap. It needs no credentials.

How it works

The document is built on each request from a fixed template and the running server: the runtime profile, the node role (primary or replica), the storage backend, and whether the QuantumOS event connector is enabled and configured. Its schema identifier is kynetra.fabric/v1.

A connect block carries the connection contract, kynetra.connect/v1: the API version, the transport, the OpenAPI, health and readiness URLs, the credential modes the server accepts (project publishable key, project service key and user token), and the status of the TypeScript client package, which the document reports as source available and unpublished. It contains no key values. A test checks that neither a service key nor a publishable key appears anywhere in the document.

The interfaces block lists base paths: /v1 with its OpenAPI link, the MCP endpoints (JSON-RPC over HTTP with server-sent events, authenticated and read-only), the QuantumOS event endpoint, the capability catalogue and the telemetry URLs for health, readiness, Prometheus metrics and the request-id header. The capabilities block marks entity read and write, BM25, vector and hybrid search, the change feed, read-only MCP and the DPDP operational controls as implemented, and distributed consensus as roadmap.

kynetra doctor reads the same document as one of its stages, to check the schema and API version before it tests authentication.

Where you reach it

  • HTTPGET /.well-known/kynetra
  • CLIkynetra doctor --remote <url> (reads the document as a stage)

Example

Excerpt of the responsejson
{
  "schema": "kynetra.fabric/v1",
  "connect": {
    "schema": "kynetra.connect/v1",
    "api_version": "v1",
    "openapi_url": "/openapi.json",
    "health_url": "/healthz",
    "ready_url": "/readyz"
  },
  "interfaces": {
    "rest": { "base_url": "/v1", "openapi_url": "/openapi.json" },
    "mcp": { "base_url": "/mcp", "access": "authenticated_read_only" }
  },
  "capabilities": [
    { "id": "search.bm25", "status": "implemented" },
    { "id": "distributed.consensus", "status": "roadmap" }
  ]
}

Limits

  • The capability list is short and fixed. It is not an inventory of everything the server does; this catalogue is.
  • It describes the instance, not a project. Every caller gets the same document, and it carries no tenant data.
  • Integration statuses, for example compatible or contract ready, are labels written into the template. They are not live health checks.

Evidence

  • On this siteAPI reference: public routes
  • TestsCovered in the engine repository by a unit test of the schema and integration names, and a mounted-router test that the connect block is public and contains no key material

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to try this against your own workload.