How a request flows
One endpoint, one execution path, and a stored account of every decision made along the way.
Request lifecycle
Each stage is timed and recorded on the request for the trace viewer.
- 1
Parse and bound
Body size is capped before parsing; the payload is validated against a schema with explicit limits on message count and total length.
- 2
Authenticate
The presented key is hashed and matched against the stored hash. Workspace, application and environment come from the key, never from the body.
- 3
Check scope and expiry
A revoked or expired key is rejected before any work is done.
- 4
Evaluate quotas
Consumption for the current window is counted and compared to the configured limits. A rejected request never reaches a provider.
- 5
Select a route
The policy filters candidates on capability, context and cost, then ranks them by its strategy. The full decision — including rejections — is captured.
- 6
Execute
The ranked chain is walked. Each failure is classified, and that classification decides whether to retry, fall back, or stop.
- 7
Normalise
The provider response is mapped into the platform envelope so application code never sees provider-specific shapes.
- 8
Record
Request, attempts, route explanation, trace stages and daily usage are persisted. A correlation id is returned to the caller.
Technology
Application
- Next.js 16 with the App Router
- React 19, Server Components by default
- TypeScript in strict mode
- Tailwind CSS 4
- Zod for every external input
Data
- PostgreSQL 16
- Prisma 7 via the pg driver adapter
- 21 relational entities with enforced workspace isolation
- JSONB only where policy shape must vary
- Supabase-compatible for production
Decisions worth defending
One execution path
The playground, the guided demo and the public API all call the same runCompletion function. A demonstration is therefore evidence about production behaviour, not a parallel mock that can drift.
The routing decision is stored, not logged
Most gateways log which model they chose. OmniRouter persists why — as structured data on the request, including rejected candidates and the score breakdown. That record outlives the policy that produced it.
Database-backed sessions
The cookie holds an opaque token; the database stores only its SHA-256. A session can be revoked server-side immediately, which a self-contained JWT cannot. Nothing is placed in localStorage.
Metadata-only logging by default
Prompt and response bodies are not retained unless a workspace explicitly opts in. The default posture is the one that retains the least personal data.
Estimates are labelled as estimates
Token counts are heuristic unless a provider reports them, and cost is derived from workspace-configured pricing. Both are presented as estimates rather than as a bill.