# ultrarouter docs

> Agent-first documentation for the ultrarouter AI cost-optimization gateway.
> Full corpus: https://docs.ultrarouter.io/llms-full.txt  ·  every page also
> available as clean markdown at `<url>.md`.

## Docs

- [Overview](https://docs.ultrarouter.io/docs.md): Frontier self-improvement for your AI Agent — we build and manage your platform's data moat with a plug-and-play continuous learning agent.
- [The AGENTS.md snippet](https://docs.ultrarouter.io/docs/agents-snippet.md): Paste this into your repo's AGENTS.md / CLAUDE.md and your coding agent wires ultrarouter itself.
- [API reference](https://docs.ultrarouter.io/docs/api.md): The full /v1 + ops surface, generated from the OpenAPI spec.
- [Adaptive optimization](https://docs.ultrarouter.io/docs/api/adaptive-optimization.md): Adaptive optimization endpoints.
- [API keys](https://docs.ultrarouter.io/docs/api/api-keys.md): API-key provisioning.
- [Audit](https://docs.ultrarouter.io/docs/api/audit.md): Zero-configuration Audit Autopilot — the passive readiness report.
- [Bench](https://docs.ultrarouter.io/docs/api/bench.md): ultrarouter Bench — dev/test capture suites + readiness.
- [Billing](https://docs.ultrarouter.io/docs/api/billing.md): Billing endpoints.
- [Call types](https://docs.ultrarouter.io/docs/api/call-types.md): Programmatic call-type config (the objects the dashboard edits).
- [Chat](https://docs.ultrarouter.io/docs/api/chat.md): OpenAI-compatible chat completions (streaming + non-streaming).
- [Custom providers](https://docs.ultrarouter.io/docs/api/custom-providers.md): Workspace-owned OpenAI-compatible providers.
- [Embeddings](https://docs.ultrarouter.io/docs/api/embeddings.md): Multi-provider embeddings.
- [Feedback](https://docs.ultrarouter.io/docs/api/feedback.md): Human feedback that feeds evals.
- [Flywheel](https://docs.ultrarouter.io/docs/api/flywheel.md): The outcome ledger — artifacts, typed outcome events, finals, pending claims.
- [Generation](https://docs.ultrarouter.io/docs/api/generation.md): Post-hoc per-request stats (OpenRouter parity).
- [Invitations](https://docs.ultrarouter.io/docs/api/invitations.md): Workspace invitations.
- [Keys](https://docs.ultrarouter.io/docs/api/keys.md): API-key introspection.
- [Knowledge](https://docs.ultrarouter.io/docs/api/knowledge.md): Knowledge endpoints.
- [Learning](https://docs.ultrarouter.io/docs/api/learning.md): Per-call-type learning controls — status, self-serve enable, pause / resume / disable, versions, evaluations, rollback and manual promote / reject.
- [Members](https://docs.ultrarouter.io/docs/api/members.md): Workspace membership management.
- [Models](https://docs.ultrarouter.io/docs/api/models.md): The model catalog and per-provider offers.
- [Ops](https://docs.ultrarouter.io/docs/api/ops.md): Operational probes and smoke endpoints.
- [Passthrough](https://docs.ultrarouter.io/docs/api/passthrough.md): Passthrough endpoints.
- [Preflight](https://docs.ultrarouter.io/docs/api/preflight.md): Ask what the gateway would decide before a non-proxied call — model, fallbacks, learned knowledge, placement.
- [Provider keys](https://docs.ultrarouter.io/docs/api/provider-keys.md): BYOK provider keys (write-only secrets).
- [Workspaces](https://docs.ultrarouter.io/docs/api/workspaces.md): Workspace tenancy management.
- [ultrarouter Bench](https://docs.ultrarouter.io/docs/bench.md): Turn your own API traffic into an inspectable, paired benchmark — capture, freeze, run, gate.
- [Bench CI gate](https://docs.ultrarouter.io/docs/bench/ci-gating.md): The ur bench run --gate exit-code contract and the GitHub Action inputs.
- [Bench evidence & honesty](https://docs.ultrarouter.io/docs/bench/concepts.md): Dataset cards, power plans, paired-vs-retained compare, dual-interval verdicts, trust classes, and evidence bundles.
- [Bench quickstart](https://docs.ultrarouter.io/docs/bench/quickstart.md): Zero to a captured suite, a frozen dataset, a paired run, a report, and a CI gate.
- [Changelog](https://docs.ultrarouter.io/docs/changelog.md): What has shipped, by phase.
- [Concepts](https://docs.ultrarouter.io/docs/concepts.md): The core ideas behind ultrarouter — call types, routing, compression, evals, savings.
- [Audit mode](https://docs.ultrarouter.io/docs/concepts/audit.md): Change the base URL and key. ultrarouter passively learns your traffic — zero config, zero changes to how requests are served.
- [Call types](https://docs.ultrarouter.io/docs/concepts/call-types.md): Per-workload config resolved through a five-level precedence chain.
- [Compression tiers](https://docs.ultrarouter.io/docs/concepts/compression.md): A safety taxonomy for prompt compression — off by default, evidence-qualified transforms, honest savings.
- [Discovery](https://docs.ultrarouter.io/docs/concepts/discovery.md): How ultrarouter finds a workflow worth learning from your own traffic — the two a-ha moments, the channel ladder, and the law that a proposed objective never teaches.
- [Evals & auto-routing](https://docs.ultrarouter.io/docs/concepts/evals.md): Continuous evaluation, model-migration recommendations, and canary rollouts.
- [The Flywheel](https://docs.ultrarouter.io/docs/concepts/flywheel.md): How ultrarouter turns the outcomes your product already generates into tested, customer-owned improvements — the six channels, the loop, and the laws that keep every claim honest.
- [Holdout and lift](https://docs.ultrarouter.io/docs/concepts/holdout-and-lift.md): The standing holdout, the exposure arms, and how the Flywheel proves a real improvement — superiority behind a randomized live contrast, arms never pooled, and the laws that keep a merged PR from becoming a result.
- [Hosted prompts](https://docs.ultrarouter.io/docs/concepts/hosted-prompts.md): Host your prompt as a versioned object per call type — fetch it from preflight or the SDK, or let the gateway apply it when proxying. A prompt we host is a prompt we can manage.
- [The Improvements inbox](https://docs.ultrarouter.io/docs/concepts/improvements-inbox.md): One inbox, one lifecycle for every improvement the Flywheel proposes — a prompt version, a model or routing change, an evaluator change — each with its offline result, live status and where it came from. Approve or reject with a reason; a refused one is archived with its evidence and never re-proposed.
- [Your knowledge DB](https://docs.ultrarouter.io/docs/concepts/knowledge-db.md): The read-only dashboard screen where you own what the Flywheel distilled from your own traffic — counts and coverage, what it taught with the evidence behind each fact, the injection policy per workflow, and the "tried and did not help" tab.
- [Export your knowledge DB](https://docs.ultrarouter.io/docs/concepts/knowledge-export.md): Take your whole knowledge DB out as a portable, content-addressed bundle — every distilled fact, exemplar, prior and process pattern with its evidence and lineage, plus the learned modules and their lift history. It is yours; training a model from your content happens only for your own workspace, never a shared or cross-workspace model.
- [The five products](https://docs.ultrarouter.io/docs/concepts/products.md): Router, Evals, Scoring, Flywheel and Context — five capabilities on one outcome ledger and one evidence gate, reached through two parallel entry actions, each with its honest availability.
- [Routing modes](https://docs.ultrarouter.io/docs/concepts/routing.md): Pinned, multi-offer fallback, and auto-routing with deadlines and provider prefs.
- [Savings methodology](https://docs.ultrarouter.io/docs/concepts/savings.md): How ultrarouter computes honest, procurement-defensible savings.
- [Evidence status](https://docs.ultrarouter.io/docs/evidence-status.md): What exists, what is verified end to end, and what is demonstrated about learning, kept apart. Learning is a preview; improvement for your agent is not yet demonstrated.
- [For agents](https://docs.ultrarouter.io/docs/for-agents.md): The machine-first quickstart — MCP server, llms.txt, markdown, OpenAPI.
- [Get started](https://docs.ultrarouter.io/docs/get-started.md): Connect your agent, wire a trusted outcome signal, turn on learning, then watch, pause or roll back. Or copy one prompt into Claude Code or Codex and let it do the setup.
- [Set up with Claude Code or Codex](https://docs.ultrarouter.io/docs/guides/agent-integrations.md): Copy-to-agent setup prompts for Claude Code and Codex, generated from versioned setup recipes, and what really differs between the two agents.
- [The AI reviewer (automated teacher)](https://docs.ultrarouter.io/docs/guides/ai-reviewer.md): How ultrarouter's AI reviewer judges a draft against its own request, records the verdict as a machine-verified correction, and why those corrections stay audit-only until the reviewer earns its qualification — with the on/off switches you control.
- [Confirm a candidate in your own app](https://docs.ultrarouter.io/docs/guides/application-ci.md): A bounded M2 walkthrough — from a screened lever candidate through your application CI, the rollout gate, refusal and rollback — with honest states for everything not yet built.
- [Connect a check (oracles)](https://docs.ultrarouter.io/docs/guides/connect-a-check.md): Register the check that knows the right answer — a platform rule, an HTTPS endpoint we call, or a worker that claims jobs — and let it earn the right to certify fixes. API reference level.
- [Plug in your decision record](https://docs.ultrarouter.io/docs/guides/connect-decisions.md): Turn the approve/reject record you already keep into correction outcomes with ZERO integration — a decision connector pulls your owner decisions, matches each delivered item to the draft the gateway captured, and records the result. Plus the experimental echo measurement and what it does and does not see.
- [The context runtime](https://docs.ultrarouter.io/docs/guides/context-runtime.md): Deterministic context assembly — lift, compile, render and a pure exit — plus compatibility profiles, memory classes, the lazy SOP catalog and native-delivery adapters. Adopt in one file, leave in one file.
- [Capture your first reviewer correction](https://docs.ultrarouter.io/docs/guides/correction-start.md): A bounded M1 walkthrough — send a request, join a human reviewer's correction to the original output in the ledger, and repair a failed import — with honest boundaries for what is captured now and what learning is still M2.
- [Find a workflow worth learning](https://docs.ultrarouter.io/docs/guides/discovery-start.md): A workflow-first quickstart — connect your traffic, let ultrarouter surface the two a-ha payloads, read the proposed learning plan over the API, and confirm one workflow. No five-toggle onboarding; nothing is learned until you confirm.
- [Declare what "it worked" means](https://docs.ultrarouter.io/docs/guides/flywheel-objectives.md): Register an artifact type and its objective — the one thing ultrarouter refuses to infer. Append-only versions, idempotent re-runs.
- [Import history](https://docs.ultrarouter.io/docs/guides/import-history.md): Bring past traffic and resolutions into the ledger without the proxy — usage-only vs intact-trace classes, the capability report, per-record idempotency, repairable per-row receipts, and binding history to a confirmed call type so its verdicts can count toward readiness. Nothing is guessed; nothing is trained.
- [Learning controls](https://docs.ultrarouter.io/docs/guides/learning-controls.md): Turn learning on for a call type yourself, decide how a learned version becomes the one your agent is served (a randomized evaluation, your own decision, or immediately), and pause, roll back, promote, reject or disable it — with the learning running only on a provider your workspace owns.
- [MCP servers for Claude Code and Codex](https://docs.ultrarouter.io/docs/guides/mcp-servers.md): The documentation MCP and the authenticated management MCP, how to install them in Claude Code and Codex (installer, plugin or by hand), what each one does not do, and how to remove them.
- [Plan a model migration](https://docs.ultrarouter.io/docs/guides/migration-start.md): A bounded M0 walkthrough — from a model being deprecated to a scoped migration decision, with honest states for everything not yet built.
- [Model price comparison — what each model costs on your own traffic](https://docs.ultrarouter.io/docs/guides/model-comparison.md): For the models your workspace may use, see the net-effective price per 1M tokens, a projected monthly cost from your own recent volume, and what we actually know about each model's quality — with honest unknowns.
- [Model policy — which models your account may run](https://docs.ultrarouter.io/docs/guides/model-policy.md): Choose US-only or global, then allow or deny by lab, provider, or model — with a US-hosted open-weight exception. Enforced everywhere a model is picked.
- [Record outcomes](https://docs.ultrarouter.io/docs/guides/outcomes.md): The thesis walkthrough — declare the objective, then record outcomes five ways (instant, delayed, batch, warehouse backfill, flush) over the real SDK and raw REST, and report the moment you have the answer with a durable receipt. Server-assigned provenance, durable idempotent retries, never a body.
- [Native passthrough (OpenAI Responses / Anthropic Messages)](https://docs.ultrarouter.io/docs/guides/passthrough.md): Point the official OpenAI and Anthropic SDKs at ultrarouter by changing only the base URL and the key. POST /v1/responses and POST /v1/messages forward your request body verbatim and meter the call.
- [Preflight a non-proxied call](https://docs.ultrarouter.io/docs/guides/preflight.md): Ask the gateway, before a call it will never see, which model and fallbacks it would route, which learned knowledge it would inject — and where — and get your exposure grant in the same response. One read, two cache lifetimes, an honest provisional flag, and an uncached grant.
- [Prompt caching (cache breakpoints)](https://docs.ultrarouter.io/docs/guides/prompt-caching.md): Send an Anthropic-style cache_control breakpoint on a content part through the OpenAI-compatible surface; the gateway carries it through and the Anthropic adapter serves the marked prefix as a cached block.
- [Providers & BYOK](https://docs.ultrarouter.io/docs/guides/providers-byok.md): The first-class providers, bring-your-own-key, and per-provider policy.
- [Review and curate what the flywheel learns](https://docs.ultrarouter.io/docs/guides/review-queue.md): An optional dashboard review queue for one call type's drafts — approve, edit, accept the AI reviewer's suggestion, or reject with a reason. Every verdict is a declared correction recorded through the existing outcome paths; the promise stays automated learning.
- [Python SDK](https://docs.ultrarouter.io/docs/guides/sdk-python.md): The ultrarouter Python client — sync + async, pydantic-typed.
- [TypeScript SDK](https://docs.ultrarouter.io/docs/guides/sdk-typescript.md): The @ultrarouter/sdk client — OpenAI-shaped, with the ur.* extensions.
- [Self-hosted models](https://docs.ultrarouter.io/docs/guides/self-hosted.md): Route to your own OpenAI-compatible endpoint (e.g. vLLM) as a custom provider.
- [Self-learning agents](https://docs.ultrarouter.io/docs/guides/self-learning-agents.md): Point an unmodified OpenAI-compatible agent at the gateway and report one outcome per finished episode. The gateway remembers the tasks your agent solved and serves the most similar ones back — with the actions that worked — on every step of new episodes. Retrieval, not training; per-workspace; identifiers redacted.
- [The training-ready export](https://docs.ultrarouter.io/docs/guides/training-export.md): What the Flywheel export is, what `not_trainable` means, and the consent that gates it. Training on your content is a separate, governed decision — it runs only for your own workspace, never a shared or cross-workspace model.
- [From OpenAI direct](https://docs.ultrarouter.io/docs/migrate/from-openai.md): Field-by-field mapping from the OpenAI API to ultrarouter.
- [From OpenRouter](https://docs.ultrarouter.io/docs/migrate/from-openrouter.md): Field-by-field mapping from OpenRouter to ultrarouter.
- [Pricing](https://docs.ultrarouter.io/docs/pricing.md): Prepaid model credits, bounded evaluations, optional BYOK, and Pro analysis.
- [Quickstart](https://docs.ultrarouter.io/docs/quickstart.md): Make your first ultrarouter call in five minutes (curl, TypeScript, Python).
- [Security & data handling](https://docs.ultrarouter.io/docs/security.md): Tenancy, secrets, retention, and how request payloads are treated.

## Setup recipes

Versioned setup recipes (schema `ur.setup-recipes/1`) with exact commands, env var names, expected output and a ready copy-to-agent prompt per coding agent (Claude Code, Codex) and language: https://docs.ultrarouter.io/setup-recipes.json

- Add learning to an existing app (`existing-app`, revision 4, preview): Keep your agent and its OpenAI-compatible client. Point the client at the gateway, report a trusted outcome per finished task, then turn learning on.
- New TypeScript example (`fresh-typescript`, revision 4, preview): A new Node.js project with the native SDK installed from a local build and one runnable toy episode: a request, a verifier, an outcome, its receipt and the learning state.
- New Python example (`fresh-python`, revision 4, preview): A new Python project with the native SDK installed from a local build and one runnable toy episode: a request, a verifier, an outcome, its receipt and the learning state.
- Install the MCP servers, then connect the project (`mcp-plugin`, revision 4, preview): Give the coding agent the management MCP (learning status, receipts, pause and rollback) and the documentation MCP first, built from source and registered by the installer or the plugin, then connect the project and report outcomes.
- Walkthrough: https://docs.ultrarouter.io/docs/get-started.md
- What is and is not demonstrated: https://docs.ultrarouter.io/docs/evidence-status.md

## Machine surfaces

- [OpenAPI (YAML)](https://docs.ultrarouter.io/openapi.yaml)
- [OpenAPI (JSON)](https://docs.ultrarouter.io/openapi.json)
- [llms-full.txt](https://docs.ultrarouter.io/llms-full.txt)
- [Setup recipes (JSON)](https://docs.ultrarouter.io/setup-recipes.json)
- MCP servers (documentation + management), built from the ultrarouter checkout (not on a registry yet): https://docs.ultrarouter.io/docs/guides/mcp-servers.md