API overview

The orchestrator is the HTTP and WebSocket API behind the Assay Console and candidate app.

Generated, not written

Every endpoint in the Reference section is generated from openapi.json, which is itself produced from the route schemas the server validates against. Nothing about the API surface here is hand-maintained, so it cannot drift away from what the service does.

Status

This API is not yet stable and carries no versioning or deprecation policy. It exists today to serve the Assay Console and candidate app, and it is documented so that it can be reviewed and built against internally.

If you are planning an integration, talk to us first at info@kravos.tech rather than building against this surface and expecting it to hold still.

Shape of the API

• Base URL: the deployed orchestrator service.
• Format: JSON in, JSON out.
• Authentication: a Firebase ID token as a bearer credential. See Authentication.
• Errors: every failure returns { "error": "..." } with a human-readable message. Not a Fastify-shaped { statusCode, error, message } envelope.

A validation failure

{
  "error": "dimensions.0.category must be one of: process, correctness"
}

Multi-tenancy

Every staff-facing route is scoped to an organisation, and isolation is enforced at the database layer rather than in application code. A request that fails to scope itself returns nothing rather than another customer’s data. See Security.

Real-time

The voice interview runs over a WebSocket rather than HTTP, because it is a live full-duplex audio stream. It is not described in the OpenAPI document, which covers the HTTP surface only.