Architecture

primerouter is an API gateway — your request goes through authentication, routing, format conversion, billing, and finally an upstream model. This page covers only the externally visible flow and design principles, not internal implementation details.

Request flow

   ┌─────────┐
   │ client  │  (your SDK / tool)
   └────┬────┘
        │  HTTPS
        ▼
   ┌─────────────────────────────────────┐
   │ 1. auth      Bearer / API key       │
   ├─────────────────────────────────────┤
   │ 2. rate-limit  user + model         │
   ├─────────────────────────────────────┤
   │ 3. routing  weight / priority /     │
   │             affinity                │
   │              ┌────────────────┐     │
   │              │ Ability lookup │     │
   │              │ group×model×ch │     │
   │              └────────────────┘     │
   ├─────────────────────────────────────┤
   │ 4. format   OpenAI ⇄ Claude ⇄       │
   │             Gemini ⇄ upstream       │
   ├─────────────────────────────────────┤
   │ 5. pre-charge  by estimated max     │
   ├─────────────────────────────────────┤
   │ 6. upstream call  HTTPS             │
   │      ▲                ▼              │
   │   resp/SSE         upstream API     │
   ├─────────────────────────────────────┤
   │ 7. settlement  byte-identical to    │
   │                upstream usage       │
   ├─────────────────────────────────────┤
   │ 8. audit  trace-id + upstream SHA   │
   │           + parity into ledger      │
   └─────────────────┬───────────────────┘
                     ▼
                  your client

Key design principles

Adapter isolation

Each upstream provider is an independent adapter responsible for:

• Request conversion to the upstream's expected JSON
• Auth headers for that provider
• Response parsing including SSE streams
• Token accounting read precisely from upstream's response

Adding an upstream doesn't affect existing channels.

Quota & billing decoupled

PreConsume → Settle → Refund in three steps:

1. Pre-charge against the request's estimated upper bound
2. Settle once the real usage arrives
3. Refund on failure or early termination

No step's failure can cause double-charge or missing accounting.

Audit trail

Every request's ledger entry has at minimum:

Field	Meaning
trace_id	unique request ID (also in response header)
upstream_provider	which provider was actually routed to
upstream_model	full upstream model identifier
upstream_sha	upstream verifiable signature (when available)
prompt_tokens / completion_tokens	byte-identical to upstream
parity	comparison result against upstream usage

This is the programmatic basis for the "no token inflation" commitment.

Externally visible boundaries

Boundary	URL
REST / SSE endpoints	https://primerouter.ai
Admin console	https://primerouter.ai/console
Chat surface	https://primerouter.ai/chat
API Reference	API docs

Specific endpoint paths and schemas: API docs. Models and pricing: Pricing.