Documentation

The OpenAPI schema

The full machine-readable schema is served from this deployment and is the authoritative description of every door:

Open the OpenAPI schema

That schema is version-pinned, not merely published. A committed baseline is diff-gated in CI: adding, removing or reshaping a path or a method reds the gate until the baseline is updated deliberately, in the same change that caused it. The contract cannot drift quietly.

/docs and /redoc both land on this page. They used to serve FastAPI’s stock Swagger UI and ReDoc, which load their entire implementation from a third-party CDN — this deployment’s content-security policy is default-src 'self' with no external origin, so every one of those requests was blocked and both pages painted nothing while still answering 200. They are unmounted. This deployment serves no third-party script, stylesheet or font from any origin but its own, and that is not relaxed for a convenience page: the schema above is the interactive surface’s replacement, and it is the same document any explorer would have read.

Guide 1 — Get a workspace and a session

A workspace is the tenant boundary. Every source, role and audit row belongs to exactly one, and a session is scoped to one. Create one, then exchange credentials for a session:

POST /auth/login
Content-Type: application/json

{"email": "you@example.test",
 "password": "…",
 "tenant": "your-workspace"}

A browser receives an HttpOnly session cookie and never handles the token itself. A machine client sends the credential it was issued as an Authorization: Bearer header instead; the two transports are byte-identical to every route behind them.

Guide 2 — Load the sources

Trivon answers only from what you have loaded, so the knowledge base is the product surface that matters most. Load documents from the workspace’s knowledge screens; each becomes a retrievable, citable source scoped to that workspace. An answer can never cite a document another workspace loaded — that boundary is enforced at the data layer, not in application code.

Guide 3 — Ask

One door, and the same four gates on every call:

POST /ask
Content-Type: application/json
Authorization: Bearer <your session credential>

{"question": "What is the receiving temperature limit?"}

The identity, the workspace and the role are taken from the authenticated session — never from the request body. A caller cannot name the workspace it wants to read.

Treat every one of these as a normal outcome. A client that handles only the answered case has not integrated the governance — it has integrated around it.

Guide 4 — Read the record

Every exchange is appended to a hash-chained audit trail, and each response carries the reference that identifies its row. Keep it: it is how an answer is checked after the fact rather than taken on trust, and it is what makes the trail worth having. The workspace’s audit screens resolve a reference to what was asked, what was answered, which sources were used and which gate fired.

Operating notes

• Rate limits. Authentication and the public doors sit behind a fail-closed limiter. A limited caller receives 429 — retry with backoff rather than in a loop.
• Readiness. /health returns 503, not 200, when a configured database does not answer, so a load balancer de-routes the instance. The human-readable form is the status page.
• Refusals are answers. A 4xx from a gate is the system working. It is not an error to retry around.