APIs, integrations & migration

OpenAPI document

Gives client generators and API explorers a machine-readable description of the server routes.

BetaEngine edition 5f8ea3af

What it does

GET /openapi.json returns an OpenAPI 3.1 document that is written by hand inside the server. It describes hundreds of paths across the native /v1 routes, the admin routes and the infrastructure surfaces. It is not complete: several mounts, including the collection REST layer, are missing, and because it is maintained by hand it can drift from the route table.

How it works

The document is one large JSON literal in the server crate. It is built on first request, on a dedicated thread with a large stack because the literal is too big for a normal worker thread, and cached for the life of the process. Nothing generates it from the router, so a route appears in the document when someone writes its entry, and not before.

The server returns it from /openapi.json without authentication. The discovery document and the connection bundle both point to it, so tools can find it from a base URL. Entries carry operation identifiers, tags, request and response shapes and security requirements, and some state their limits in their descriptions. For example, a route that is disabled in this build is documented as a refusal, not as a success.

Tests in the server crate assert that selected routes are present: the native transaction endpoint, the KynQL query endpoint, the view routes, the infrastructure job and lifecycle routes, the managed database routes, the pipeline control plane, residency, retention and others. None compares the document with the complete route table, which is why coverage is described as partial.

Where you reach it

  • HTTPGET /openapi.json
  • HTTPGET /.well-known/kynetra (links to the document in its connect block)

Limits

  • Partial coverage. These mounts are not described in the document: the collection REST layer under /rest/v1, the /auth/v1, /storage/v1 and /functions/v1 compatibility mounts, the WebSocket realtime endpoint, the outbound webhook routes, the cluster provisioning routes, the Postgres migration job routes and /metrics.
  • The document is maintained by hand, so a route added or changed in the server can be missing or out of date until someone updates the entry. Check the capability pages on this site for the surfaces the document leaves out.
  • It is not a promise of client compatibility. Generated clients should be tested against your preview.

Evidence

  • On this siteAPI reference: route groups and authentication
  • TestsCovered in the engine repository by 25 tests that assert named routes and schemas are present, plus a connection-contract test that the project connect route is in the document

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 talk through the limits above against your own workload.