Swap a base URL and API key. Keep your prompts, model IDs, SDK, and request shape. Finest serves the model you asked for unless exact published evidence authorizes a cheaper configuration for that exact job, and a model id the vendor has renamed or retired resolves to the vendor's own successor, named on the receipt.
Use the same provider SDK you already have. The gateway exposes an OpenAI-shaped Chat Completions surface and an Anthropic Messages surface.
1
Issue a key
Open /console/keys#door1. Key material starts with fk_ and is shown once.
2
Set two variables
Add FINEST_GATEWAY_URL and FINEST_API_KEY to the process that makes model calls.
3
Change the client
Replace only the base URL and API key. Your request body and model ID stay unchanged.
4
Verify the deployment
After you deploy, run npx @finest-ai/claude-code@latest verify-app <url> --body '<request body>'. VERIFIED names the receipt; BYPASSED means the app answered and Finest saw nothing.
Both paths send supported calls through the same managed gateway. The difference is what can happen after a refusal that Finest proves occurred before provider dispatch.
Pure key swap
No package
Point the provider client at Finest and use the fk_ key. It is the smallest change and works in any language. The tradeoff is explicit: a proven pre-dispatch Finest refusal cannot go direct to your provider, so that call fails visibly.
Works without Finest package code
Preserves your request body and model ID
No direct fallback on a Finest-owned refusal
The one-line shim
Safest path
Keep your provider key in the environment. The shim goes direct only when the gateway returns literal x-finest-gateway-error: 1, proving that no provider dispatch occurred.
Direct fallback for proven pre-dispatch refusals
Unsupported provider endpoints stay direct
Transport ambiguity never creates a duplicate request
client.ts
import OpenAI from 'openai';
import { door1 } from 'finest-ai';
const openai = new OpenAI({ ...door1('openai') });
The router is conservative by construction. A cheaper model is not chosen because it looks similar or scores well on a public leaderboard. It must have evidence for this request's complete measured configuration.
01
Read the exact request
Finest resolves the model name, then identifies the provider, model, prompt and schema revisions, decoding, effort, cache, release mode, endpoint, and other quality-affecting configuration.
02
Resolve serving authority
A cheaper configuration is eligible only when the complete request matches current published evidence. Missing, changed, stale, or ambiguous evidence means no switch.
03
Serve or escalate
The selected arm must satisfy hard constraints. A refusal or validator failure escalates to the model you asked for. Streamed requests serve under the same law: a substitution needs the same sealed evidence, and the receipt names it.
04
Write the receipt
The response names the requested and served models, decision, evidence label, prices, savings, fee, and persistence state. Content is not stored in the receipt.
served_as_requested
No exact authority applied. The requested configuration served.
demoted
Exact evidence authorized a cheaper configuration.
escalated_to_requested
A cheaper attempt was withheld and the requested configuration served.
auto_selected
A finest/auto slug delegated the choice, so no caller model was named.
refused
Finest refused before any provider dispatch, so nothing served and nothing billed.
Send the model ids your code already has, including ids the vendor has renamed or retired. A name the gateway does not carry by exact spelling resolves through the vendor's own naming rules, in a fixed order, and the response says so every time. Nothing resolves by guesswork.
01
Exact match
The name is a served endpoint. Bare and provider-prefixed spellings both work, so a model and its provider/model form name the same endpoint.
02
Dateless alias
A vendor's dateless spelling completes to its one served dated release. Two dated releases under one base name refuse rather than choose, because a grammar must not make that choice for you.
03
Vendor lineage
The successor the vendor declares, else the nearest release at or above the named one in the same product line and size class. Never an older generation, never a different size class, and never a claim that the substitute is better.
04
Suffix grammar
A -latest or vendor date suffix strips to a base that re-enters the rungs above. No case folding, no edit-distance guessing: an unrecognized string is refused.
A serve through rungs 02 to 04 is disclosed, never silent: x-finest-requested-model and x-finest-served-model diverge, the receipt records the exact rule as resolved_by_lineage with its basis, and the console lists the request as Matched instead of Served as asked. A match by name is not an evidence-gated demotion: the match itself adds no fee, and the savings share applies only where sealed evidence separately serves the request cheaper.
A name no rung recognizes is refused with 404 model_not_found in your SDK's own error dialect, reading is not an admitted model on this gateway. When a served name is close enough, the message names up to three of them, so a typo answers itself; a string with nothing close gets the unadorned refusal. Under strict matching the refusal instead names the model the ladder would have served, which is the one fact a strict caller needs to decide what to do next.
Use a finest/auto model slug when you want to delegate the model choice. Auto applies capability, context, output, streaming, and residency constraints before its deterministic profile ranking.
finest/auto
Balanced. The same profile as finest/auto:balanced.
finest/auto:quality
Quality-first ranking after every hard constraint passes.
finest/auto:balanced
The median eligible price rank, with deterministic tie-breaking.
finest/auto:economy
The lowest-priced eligible endpoint.
finest/auto:documents
Document-oriented selection. It is explicit plan consent, but falls back to a single eligible endpoint when no governed plan is published.
finest/auto:<task class>
The balanced profile with the task class declared in the model string itself: extract, classify, summarize, generate, agent, code, transform, or reason. One string does what the x-finest-task-class header does, for SDKs where the model name is the only thing you can set. An unknown suffix is refused with the valid list.
Exact model names only for this request. A name that would resolve through a vendor alias or lineage is refused with model_not_found naming the model it would have served.
x-finest-residencymetadata.finest_residency
Apply a region or comma-separated region list as a hard constraint before price.
x-finest-routemetadata.finest_route
Name the exact customer route whose personal evidence may be considered.
x-finest-task-classmetadata.finest_task_class
Declare the kind of work, which scopes the published-evidence lookup and receipt attribution. Absent, the class is inferred from the request only where that holds at high precision, and the receipt says so; an uninferrable request serves exactly as asked. A declaration always wins over inference, and never authorizes a switch by itself: a published record for the class must also exist.
x-finest-posturemetadata.finest_posture
Override the key posture for one request: max_savings, balanced, or silent_safe.
x-finest-planmetadata.finest_plan
Allow or deny an evidence-bound buffered plan for this request when one is published.
declare-task-class
// OpenAI SDK: one line at client construction
const openai = new OpenAI({ baseURL, apiKey, defaultHeaders: { 'x-finest-task-class': 'extract' } });
// Anthropic SDK: the same one line
const anthropic = new Anthropic({ baseURL, apiKey, defaultHeaders: { 'x-finest-task-class': 'extract' } });
// Python (either SDK): default_headers={"x-finest-task-class": "extract"}
// No header access at all? The model string is enough:
model: 'finest/auto:extract'
# cURL: one flag
curl ... -H 'x-finest-task-class: extract'
The managed surface is intentionally narrow. The shim preserves the rest of each official client by sending unsupported paths directly to the provider when its key is present.
OpenAI-shaped
POST /gateway/openai/v1/chat/completionsGET /gateway/openai/v1/models
Anthropic-shaped
POST /gateway/anthropic/v1/messagesGET /gateway/anthropic/v1/models · POST /gateway/anthropic/v1/messages/count_tokens
Token counting is answered on the Anthropic wire, proxied to Anthropic's own counter so every answer comes from one declared tokenizer: a Claude model counts on its own, and a non-Anthropic pin counts on the claude-sonnet-5 basis rather than its vendor's. It is free and unreceipted, with a per-key rate limit that answers 429 rate_limited above roughly two calls a second. The Anthropic-wire model listing is the curated Claude Code catalog, narrower by design than the OpenAI-shaped listing. Under the TypeScript shim both of those Anthropic paths currently go direct to the provider unreceipted, because the shim treats every Anthropic path except Messages as unsupported; call them on the gateway base URL when you want the Finest answer. The TypeScript shim keeps embeddings, Responses, images, audio, files, batch calls, and other unsupported official-client paths direct and unreceipted. Pure key swap clients do not have that bypass. Portable request parsing rejects fields it cannot preserve instead of dropping them. Provider-semantic errors pass through unchanged. Streamed requests serve under the same evidence law as buffered ones, and every streamed serve is receipted with the models and prices it actually carried. stream_options.include_usage: true is part of the portable subset on every model: a managed stream always answers with one final usage chunk, so asking for it by name serves canonically rather than forcing verbatim forwarding.
A receipt is the audit trail for a managed request, not a transcript. It records configuration identity, decision facts, model and provider identities, token and cost facts, evidence references, and persistence state without prompt or completion content.
Name
Purpose
durable
The receipt landed in durable storage and survives a restart.
pending
A reference was assigned, but the durable write has not landed yet.
deferred
A stream is open. The receipt lands after the stream completes.
terminal / dropped
Accounting failed. Routing stops instead of serving an unrecorded outcome.
receipt_accounting_quarantined
Not a state. It is the gateway error code on a pre-dispatch 503 that carries no receipt reference at all, because even refusal accounting is unavailable.
Successful managed responses carry x-finest-receipt-id, x-finest-receipt-state, x-finest-requested-model, x-finest-served-model, and x-finest-evidence-label. Read the ledger at GET /v1/receipts with the same fk_ key that served the traffic: a serving key reads its own workspace's receipts and holds no other account authority.
A substitute only serves a request whose output budget it was measured at. The floor is per model and measured; the default is 4096.
Some substitutes reason before they answer, and that reasoning spends the same max_tokens budget as the visible reply. Below a measured floor a tight cap can be consumed before any output exists, so requests under the floor are served exactly as asked at pass-through price; the receipt names the floor. The default floor is 4096 tokens. A substitute sealed at a lower cap carries its own floor, and the floor is never higher than the cap its evidence was measured at.
A request served as asked for this reason carries x-finest-eligible-max-tokens: the max_tokens that would make it eligible for a substitute. The receipt sentence says the same thing, and the console shows the eligible cap beside the row. Your request is never rewritten: max_tokens stays exactly what you sent.
Evidence labels describe how a route earned authority. They are derived from immutable records, and no surface may render a label stronger than its record supports.
Recommended
Finest measured a common job on its own paired test set and published the record. It is house evidence, never a claim about your traffic.
Verified for your examples
Your frozen examples passed a preregistered replay and confirmation for this exact route and configuration.
Proven in your production
The route also survived a sticky production canary and its economics were reconciled to provider-reported spend.
Validated per request
Not an earned level, and deliberately not one of the three above. It makes no claim about the cheaper model. It says that every machine-checkable validator on the plan ran against this one response, and that a failure would have escalated to the model you named with Finest absorbing the cost. On the wire it is validated_per_request.
The integrity rule is simple: no surface may render a label stronger than its record supports. Recommended never means personalized, and a routed escalation strips the label rather than pretending the cheaper arm served.
The gateway uses a one-time-visible serving key and a prepaid internal credit ledger. Both are designed to fail before provider dispatch when a request cannot be funded or attributed safely.
Serving keys
A human issues, rotates, and revokes fk_ keys. Only the hash is stored. The agent install path hands key creation back to the human.
Finite quotas
Each key has request, token, and daily spend limits. An exhausted limit is a marked pre-dispatch refusal.
Prepaid credits
An append-only ledger reserves and settles managed serving. An empty balance returns a receipted 402 before provider dispatch.
Frozen baseline
The first key issuance freezes the declared incumbent models as the record of what you arrived running. The savings share is measured per request against the model you asked for, whether or not it is in that record.
Quality posture
Choose max_savings, balanced, or silent_safe at issuance. Balanced is the default; a request may override it without weakening evidence requirements.
Intelligence floor
Optionally name a resolvable reference model. A demotion target must be proven non-inferior to that floor before it can serve.
Plan consent
Plans default off at the key level. A request may allow or deny one, and finest/auto:documents acts as explicit document-plan consent.
The implemented billing law records a fee only on positive, eligible per-request savings. The requested model baseline, quality reference, routing arms, and billing counterfactual remain separate facts.
Worked example: a $100 eligible baseline and a $90 fully loaded routed cost produce $10 eligible savings, a $2.50 fee, and $92.50 paid. Provider price cuts reprice the comparison downward and are never claimed as Finest savings. The referral program can rebate an actually charged gateway fee after the fact, but it never turns fee credit into provider credit.
Verification compares one exact challenger configuration with the requested configuration on a frozen set, under explicit consent and a spend ceiling. Queued, running, blocked, or failed jobs are not evidence.
01
Freeze the job
Bind prompt, schema, provider, endpoint, model revision, decoding, effort, adapter, prices, and corpus identity.
02
Replay both arms
Run paired items through the governed worker and retain errors, refusals, tokens, latency, and grader versions.
03
Confirm once
Apply preregistered quality, safety, economics, and worst-stratum gates on an untouched confirmation split.
04
Publish or abstain
Only a passing immutable record may authorize serving. A failed or incomplete result publishes no switch.
Finest has one machine-readable gateway install contract. A coding agent can change the client boundary, run Doctor, and prepare an uninstall without seeing key material.
1. Read
Point the agent at /llms.txt or call the finest_install MCP tool. Both return the same generated instructions.
2. Hand off
The agent never handles key material. It opens the console path for a human to create and place the fk_ key.
3. Verify
Doctor reads secrets from the environment, never flags, and reports the exact blocking readiness gate.
Before the first edit, the instructions record each original file and environment variable by name, never value. Uninstall restores that original by reference instead of trying to reverse a text edit.
Eject is a resumable, admin-only walkthrough. It exports the audit trail, converts policies, and proves what still depends on Finest without declaring independence it cannot observe.
1
Export the bundle
POST /v1/eject/export collects verification records, policies, receipts, credit history, and savings statements.
2
Provision your provider keys
The guide names the providers and environment variables your app needs. Finest cannot create provider accounts for you.
3
Convert policies
POST /v1/eject/convert-policies re-signs active policies into artifacts you hold.
4
Verify independence
GET /v1/eject/verify-independence lists every remaining dependency, including live fk_ keys, open canaries, queued work, and unconverted policies.
5
Verify uninstall
POST /v1/eject/verify-uninstall compares the restored client with the original recorded before the first edit.
Use environment variables for deployment-wide configuration and headers or metadata for optional per-request control.
Environment
Name
Purpose
FINEST_GATEWAY_URL
The gateway origin shown beside the key. Do not guess it.
FINEST_API_KEY
The one-time-visible fk_ serving key.
OPENAI_API_KEY
Optional direct-provider fallback for the shim and unsupported OpenAI endpoints.
ANTHROPIC_API_KEY
Optional direct-provider fallback for the shim and unsupported Anthropic endpoints.
FINEST_DISABLE
Set to 1 to return the plain provider configuration when using the shim.
Response headers
Name
Purpose
x-finest-receipt-id
Immutable reference for the managed outcome.
x-finest-receipt-state
Persistence state for that receipt.
x-finest-requested-model
The model named by the caller.
x-finest-served-model
Finest's own identity for the endpoint it dispatched to.
x-finest-provider-reported-model
The model the provider itself named in its response. Present on canonical serves when the provider reported one.
x-finest-evidence-label
One of none, validated_per_request, recommended, verified_for_your_examples, proven_in_your_production.
x-finest-policy-version
Present when a published policy decided the request.
x-finest-eligible-max-tokens
Present only when a request was served exactly as asked because its max_tokens was below the substitute's output floor. The value is the max_tokens that would make the request eligible for a substitute. Absent on every other response.
x-finest-residency-required
The normalized region constraint applied to the request.
x-finest-residency-honored
Whether a stated residency requirement was satisfied.
x-finest-cache
What became of the prompt-cache breakpoints in the request: honored, relocated, positions_not_expressible, none, or auto. Absent when the request carried no cache instruction and Finest placed none. none means the served surface could have carried the caller's breakpoint and none went out, which is always a defect on our side.
x-finest-gateway-error
Literal 1 only for a proven pre-dispatch Finest refusal that the shim may replay direct.
The gateway serves live traffic, and live serving is not the same thing as customer proof. These are the current boundaries a production evaluation must close.
Serving readiness
The gateway serves live traffic in production: real provider dispatch, receipted per request. Model endpoints are admitted from official provider documentation with human sign-off. GET /v1/public/served-models is the authority on names: it publishes what serves exactly and what resolves through the vendor's own lineage and naming grammar, named on every receipt.
House evidence
Historical or placeholder evidence does not authorize a current demotion. The exact prompt, schema, provider, model, adapter, and price identities must be current.
Streaming
Streams serve under the same sealed-evidence law and are receipted with both models and both prices. Whole-body validation and plans require a buffered response.
Document plans
The bounded plan substrate exists in code, but no plan is authorized for publication in this checkout. finest/auto:documents therefore cannot be presented as a live multi-step compiler.
Public packages
This deployment attests that packages are published.
Payments and fees
Prepaid credit and live fee collection are in production: the savings share is debited from your prepaid balance as the request is served, and every charge carries a receipt. Where no measurement authorizes a number, no number appears.
Content capture
Uploaded files and production prompt or output capture remain disabled until encryption, consent, erasure, retention, and operational controls are complete.
Customer proof
Repository tests, public benchmarks, and synthetic experiments are not production savings proof for a customer.
Machine-readable
Building with a coding agent?
Send it to /llms.txt. That generated document contains the API endpoints, authentication, model-name resolution, request controls, response headers, current limits, and the same install contract returned by the finest_install MCP tool, including the key handoff, Doctor, kill switch, and uninstall.
The complete wire contract is published as OpenAPI 3.1 at /openapi.json on the gateway origin shown beside your key, anonymously. For the exact model names and aliases serving today, query GET /v1/public/served-models rather than any hardcoded list.