# Conduit Router

> A policy-first model router for AI agents. Bring your own provider keys (BYOK).
> Every call is policy-checked, budget-checked before the first token, metered,
> and written to a hash-chained audit log you can verify without trusting us.

Conduit Router v0.7.0 — base URL: https://router.pipavia.com

## Start in one minute

1. Get a trial key: POST https://router.pipavia.com/v1/trial (no auth; rate-limited per IP).
2. Store a provider key: POST https://router.pipavia.com/v1/byok with your Conduit key as
   Bearer and {provider, provider_key} — e.g. a Google AI Studio key.
   Keys are envelope-encrypted at rest and never logged.
3. Call a model (OpenAI-compatible):
   POST https://router.pipavia.com/v1/chat/completions
   { "model": "google:gemini-2.5-flash-lite",
     "messages": [{"role": "user", "content": "Hello"}] }
   Add "stream": true for SSE streaming. Every response carries _meta with
   the served model, cost, outcome, and a receipt_id.

## Surfaces

- API (OpenAI-compatible): POST /v1/chat/completions, GET /v1/models
  (OpenAI shape; ?format=conduit for the native catalog shape).
- API (native): POST /v1/route — signed-config handshake for full control
  (task profiles, declared fallback chains, per-call provider keys).
- MCP server: POST /mcp — tools route_chat, list_models, get_usage,
  get_receipt, verify_receipt, get_policy. Same Bearer Conduit key.
- Dashboard: https://router.pipavia.com/dashboard — keys, provider keys, usage, policy, receipts.
- CLI: `conduit` (in-repo package `cli/`): login, trial, models, byok,
  route, usage, receipt, verify, policy.
- SDKs: TypeScript (`sdk/typescript`, @pipavia/conduit-router) and Python
  (`sdk/python`, pipavia_conduit) — in the conduit-router repository.
- OpenAPI 3.1: GET /openapi.json. Agent card: GET /.well-known/agent-card.json.
- Status: GET /.well-known/conduit/status.json.

## Standing terms (your policy)

POST /v1/config sets your key's standing terms: task profile
(reasoning|tool-use|bulk), per-request and daily budgets (USD), model
allowlist, and a declared fallback chain. GET /v1/policy reads them.
Budgets are enforced fail-closed BEFORE a call: if the estimate exceeds
the budget, nothing is sent to any provider.

## Receipts and verification

Every call writes a hash-chained audit record. GET /v1/receipts/{id}
(owner key required) returns your record plus its chain proof.
POST /v1/audit/verify is PUBLIC: send {receipt: <record>} and the service
recomputes the record hash and checks the record sits in the chain.
GET /v1/audit/anchor returns the latest signed chain-head checkpoint.

To verify WITHOUT trusting this server (Stage 4): the chain head is
checkpointed into signed anchors — GET /v1/audit/anchors lists them.
Each anchor names the records since the previous anchor (their hashes,
in order), the chain head, and the previous anchor's hash, and is
signed with Ed25519. The signing public key is published at
GET /.well-known/conduit/anchor-key.json, and the anchors are mirrored
to a public git repository (append-only history you can audit):
https://github.com/nrupala/conduit-audit-anchors
Check any receipt yourself, three ways:
- Browser: https://router.pipavia.com/verify — paste a receipt; all checks run locally.
- Standalone script (no dependencies, Node >= 18): verify.mjs in the
  mirror repository — it reads the mirror by default, not this server.
- Your code: verifyReceiptIndependent in the TypeScript SDK,
  verify_receipt_independent in the Python SDK, or `conduit verify`
  in the CLI — each runs the same five checks on your machine.
Honest limit: an anchor proves the record existed, unchanged, in the
chain at anchor time. It cannot prove a call that was never recorded.

## Billing (test mode)

Router Pro billing is wired to Paddle in TEST MODE ONLY: subscriptions
grant the Pro tier through signed webhooks, entitlements are keyed to
the Paddle subscription id (never to email), and a buyer binds the
subscription to a key with POST /v1/billing/claim
{subscription_id from the Paddle receipt}. GET /v1/billing/status
reports your tier, binding, and mode. Router Pro is NOT on sale yet —
no live charging exists on this service; the owner's billing-proof
gate controls any go-live.

## Models and honesty

GET /v1/models lists 17 production models across OpenAI,
Anthropic, Google, Groq, Cloudflare Workers AI, and OpenRouter (as an
upstream), plus your own custom OpenAI-compatible endpoints. Every model
carries a pricing source and an as-of date. Free-tier models are marked;
Google's free tier trains on prompts — that disclosure travels with the
catalog. GLM models are never served. DeepSeek exists only in the dev
profile and is unreachable from production configs.

## Contact

info@pipavia.com — the only published address. Operated by Pipavia
(2351485 ALBERTA INC.), Calgary, Canada.