Wire Finest into your app, and read the contract it holds itself to.
https://gateway.finest.so, the key is issued in the console, and the swap is those two lines. The packages are published, so the shim is one install away. The pure key swap needs no package at all.A human issues the key in the console at /console/keys#door1. The material (prefix fk_) is shown once. There are two ways in, and they differ in one property only.
1 · Pure key swap: no package required
baseURL: `${process.env.FINEST_GATEWAY_URL}/gateway/openai/v1`
apiKey: process.env.FINEST_API_KEY // fk_…
// Anthropic-shaped clients append /v1/messages themselves:
baseURL: `${process.env.FINEST_GATEWAY_URL}/gateway/anthropic`The tradeoff, stated rather than discovered: without the shim, a proven pre-dispatch Finest refusal cannot go direct to your provider, so that call fails instead of falling back. Either way, a transport rejection stays visible, because the gateway may already have sent the request and retrying it could create a duplicate charge. Nothing else about your app changes, and your model ids stay as they are.
2 · The one-line shim: keeps a direct path
import { door1 } from 'finest-ai';
const openai = new OpenAI({ ...door1('openai') });The shim reads FINEST_GATEWAY_URL and FINEST_API_KEY. When the gateway returns a failure it explicitly owns, the shim replays the identical request against your provider on the key already in your environment, so keep that key. A refused key, your kill switch, exhausted credit, one of our rate limits or a model we do not carry is marked x-finest-gateway-error: 1, and only that marker authorises the direct fallback. Everything else stands, because it may have arrived after the request reached the provider, and a missing receipt is not enough evidence to risk charging you twice. A request our portable subset cannot express stays a plain 400 for you to fix rather than being quietly routed around. FINEST_DISABLE=1 hands your client the plain provider configuration and the original fetch reference.
You do not have to annotate anything. Finest derives stable prompt and schema revisions from the wire, and may substitute a cheaper model only when the complete request configuration matches a published record. Optionally, add metadata.finest_task_class in the body, or the x-finest-task-class header, which wins, as one of extract, classify, summarize, generate, agent. That tag is a consistency hint for receipts and evidence discovery, never authority to switch models: a contradictory or unrecognised hint is refused or served as asked. Evidence from your own examples is tied to the route it was measured on, so pass metadata.finest_route or the x-finest-route header with that exact route key to use it. Without it, unannotated traffic can still use exact house evidence, but it can never borrow another job’s policy because the two happen to share a system prompt. To forbid substitution on one call, set metadata.finest_no_demote: true or x-finest-no-demote: true. The receipt records the opt-out.
Stating a data residency requirement. Use metadata.finest_residency in the body, or the x-finest-residency header, which wins: a region or a comma-separated list, such as eu. It is a hard constraint and it is applied before any price is compared. finest/auto selects only from endpoints whose registered region or declared data handling satisfies it, and a demotion, the swap to a cheaper model, is refused when its target cannot. Both facts come from the catalogue’s hashed, documentation-sourced entry, never from a hostname. An endpoint that declares nothing counts as failing, because unproven residency is not residency. If nothing qualifies, the request is refused with the region named, not served from somewhere else. The one thing the constraint does not do is block the model you asked for by name: that choice is yours, and the response tells you whether the endpoint that served it met your requirement. An empty or malformed value is a 400, because a constraint is never silently ignored.
What comes back. Every response we serve carries x-finest-receipt-id, x-finest-receipt-state, x-finest-requested-model, x-finest-served-model and x-finest-evidence-label. When a signed policy applied, it also carries x-finest-policy-version. A request that stated a residency requirement carries x-finest-residency-required and x-finest-residency-honored, because “we left it out” must never be readable as “we complied”. The body’s model field names what actually served you. Receipts are readable at GET /v1/receipts. Streaming requests are never substituted, and they are still receipted.
The install is agent-native. Point a coding agent at /llms.txt, one executable document, or let it call the finest_install tool on our MCP server, which returns that same document plus the console URL where a human issues the key.
Two boundaries are written into the agent instructions themselves, not just into ours: the agent never handles key material, so it hands the human a link, and it records the original of every file and environment variable it touches, by name and never by value, before the first edit. Uninstall then restores the original client by reference instead of by reversing an edit.
A route name describes the job, not the model: extract_invoice_fields, not gpt_call. Model ids belong in configuration, because the model behind a route is expected to change.
Finest ran its own paired replay on an open test set for a common kind of job and published the result, including the jobs that failed their bar. It is measured evidence, never an imported score, and every published entry links the immutable records behind it.
Rendered on: Substitutions before you have evidence of your own; finest/auto responses; the house policy table.Your own replay and confirmation passed on your frozen test set: a bar set in advance, splits that share no examples, one-shot confirmation, and statistical bounds recorded in an immutable record.
Rendered on: Route candidates, verification records, the policies signed from them, and the requests those policies serve.The change additionally survived a sticky canary on real traffic and reconciled against your provider’s own reported spend.
Rendered on: Promoted routes, savings statements, the fee. A fee is unreachable without both of those.The rule that makes the labels worth reading: no surface may render a label stronger than its record supports. Labels are derived on the server from the record itself and arrive at the browser as a fixed value, so no component can upgrade one.
eligible_savings = max(0,
min(origin_baseline_cost, approved_counterfactual_cost)
− actual_fully_loaded_cost)
fee = 25% × eligible_savings # portfolio-netted, above the $200/mo allowanceFour things are kept apart and never blurred: the origin configuration (what you ran before us, and what the export returns you to), the quality reference (the quality target you approved), the routing arms (what a policy may select) and the billing counterfactual (what savings are measured against). The counterfactual must be something you actually ran, or something that predates us. Accepting our recommendation never raises it. A pricier model joins your baseline only after you run it in production yourself for a defined window, or a permanent randomized control proves it was the real comparison.
Provider price cuts re-freeze the baseline downward and are never billed as savings, because comparisons are priced from current prices. The worked example is a binding acceptance test: $100 prior spend, a $150 recommended model, a $90 routed mix, giving $10 eligible, $2.50 fee, $92.50 paid. It is rendered on the pricing page by calling the same functions the statement builder calls.
GET /v1/eject is the guide: ordered steps whose state is derived from what actually happened, so the flow is resumable and nothing is merely checked off. It is driven by a signed-in admin, because an API key must never be able to walk a workspace out the door.
- Export the bundle. POST /v1/eject/export writes every verification record, policy generation, receipt and savings statement into one bundle you keep. Exporting is itself an audited act, so the flow can tell you it already happened.
- Provision your own keys. The guide names the providers your routes actually serve and the environment variable names your app will read. This is the one step we can describe but not perform for you.
- Convert the policies. POST /v1/eject/convert-policies re-signs the policies we serve as policies you hold, with the same four parts: the configuration you arrived with, the quality reference, what a policy may select, and what savings are measured against.
- Verify independence. GET /v1/eject/verify-independence names what still depends on us: a live fk_ gateway key, an open canary, a queued verification job, a policy your client does not yet hold. It reports true only when every check ran and was clean; a check it could not run is listed as unverified, never as clean.
- Verify the uninstall. POST /v1/eject/verify-uninstall compares your restored client against the original recorded before the first edit. Restoration is by reference, not by reversing a text edit, and a byte-identical restore is the pass condition.
The flow is tested end to end against fixtures in this repository.
- We are in your request path, by your explicit choice. You get the model you asked for, served exactly as asked, unless the complete configuration of the request matches a published record showing a cheaper model already did this exact job just as well. With your provider key present, the client we ship goes direct only when the gateway proves it refused before the request reached a provider. A transport failure is never replayed, because the request may already have been dispatched.
- Every request we serve, and every ordinary refusal after we have authenticated and parsed it, is assigned a receipt reference and written down. A landed receipt records the model you asked for, the model that served you, the evidence label, both prices, the saving and the fee, including requests we served exactly as asked and earned nothing from. The states a receipt can be in are listed further down this page.
- If we cannot record what happened, we do not change what happens. A route stays on the model it is already using.
- A replay request is not evidence. Only a completed, immutable verification record can authorise a policy that moves a route.
- This release verifies only frozen public-reference, synthetic or CI test sets. Uploaded files, staging traffic and production traffic are blocked until encryption, consent and erasure exist end to end.
- The thing we verify is the whole configuration: provider, endpoint, region, pinned version, host, quantization, service tier, adapter and prompt revisions, reasoning effort, decoding, cache policy, release mode. Two hosts serving the same weights are different candidates.
- Hard constraints filter before cost: privacy, residency, retention, no-training flags, licences, allowlists. No budget rule routes around them.
- Evidence expires. Any change to the configuration, the prompt template, the traffic mix or provider prices invalidates it. Changing the model you asked for invalidates everything fitted to the old one: refit, reconfirm, re-sign.
- A model enters the catalogue only from official provider documentation, fetched, hashed and effective-dated, and a human performs the final admission. An agent never does. Serving a provider through the gateway also requires that provider’s commercial-terms clearance, which defaults to off.
- What we choose for you cannot inflate what we charge. Authority to move a route comes only from published, versioned evidence records, receipts can be audited against them, and finest/auto is flat-priced, never savings-share priced.
- No surface may render an evidence label stronger than its record supports, and “Recommended” copy never claims personalization.
- Provider invoices can reconcile what you actually spent. What you would have spent without us stays an estimate, shown with the share of traffic it covers. Missing evidence withholds a total rather than turning into zero.
x-finest-receipt-state tells you where the record of your request got to.
| State | What it means |
|---|---|
| durable | The receipt is written and survives a restart. This is the only state that satisfies the recovery check. |
| pending | A reference is assigned and the write has not landed yet. Recovery is process-local in this release. |
| deferred | The stream is still open; the receipt lands when it finishes. Response-only, and never a Doctor value. |
| terminal, dropped, saturated | Accounting failed. Routing stops and the workspace waits for an operator rather than serving unrecorded. |
| receipt_accounting_quarantined | A 503 refused before the request reached a provider, deliberately with no receipt reference, because even refusal accounting is unavailable. It normally holds one workspace; if the index of held workspaces fills, it applies to every workspace rather than discarding unresolved evidence. |
Four things can come back without a receipt reference at all: an invalid or unresolvable credential, malformed input, a fault we have not classified, and the quarantine 503 above. Each returns an explicit error rather than a silent success.
Doctor is the connection check in the console. It probes one authenticated Finest diagnostic catalog at /gateway/openai/v1/models for both supported providers, and reports readiness at probe time, not that a real provider request has succeeded. The OpenAI-shaped path is not an Anthropic Models API compatibility claim. Doctor grades the receipt journal as healthy (pass), pending (warn), or saturated, terminal, quarantined or dropped (fail); a missing or unknown value fails too. Recovery passes only on durable.
An operator picks one exact challenger configuration and an existing, non-empty frozen test set. The API checks worker liveness, where the test set came from and that it has not changed, before it commits any provider spend. The resulting job shows as queued, running, blocked or failed. None of those states is quality evidence.
The replay runs on the Finest worker, under recorded consent and a spend ceiling you set. The customer-local replay executor, the design in which content never leaves your environment, is not built, so we do not describe the current release that way: the boundary protecting content today is a refusal, not an enclave. Uploaded files, staging traffic and production prompts or outputs are blocked, because encrypted content storage, consent and erasure do not exist end to end.
Completion writes an immutable record: the exact configurations, the test set’s identity and hash, the grader versions, the statistical bounds, the prices used and an attestation level. Levels 1 and 2, local_attested and provider_receipted, are live. Audited and reconciled exist in the schema only, and they gate fees rather than launch. Raw transcripts are not shown in production, because encrypted retention is not implemented. No environment variable can turn that missing system into safe storage.
The version of this page for your coding agent is at /llms.txt, generated from the same source the MCP install tool returns.