Skip to content
Docs/API
Managed Runtime

Your model calls, now evidence-routed.

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.

No request rewrite

Prompts and model IDs stay yours.

Fail closed on evidence

No exact proof means no demotion, and no fee.

Receipted outcomes

Managed serves and classified refusals explain what happened.

Browse API docs
Start

Quickstart

Use the same provider SDK you already have. The gateway exposes an OpenAI-shaped Chat Completions surface and an Anthropic Messages surface.
  1. 1

    Issue a key

    Open /console/keys#door1. Key material starts with fk_ and is shown once.

  2. 2

    Set two variables

    Add FINEST_GATEWAY_URL and FINEST_API_KEY to the process that makes model calls.

  3. 3

    Change the client

    Replace only the base URL and API key. Your request body and model ID stay unchanged.

  4. 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.

openai.ts
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: `${process.env.FINEST_GATEWAY_URL}/gateway/openai/v1`,
  apiKey: process.env.FINEST_API_KEY,
});

const response = await openai.chat.completions.create({
  model: 'your-current-model',
  messages,
});
Connect

Choose your connection path

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') });
Understand

What happens to every request

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.

Understand

Model names, aliases, and strict matching

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.

served-models
curl -s "$FINEST_GATEWAY_URL/v1/public/served-models"

{
  "models":  ["<model>", "<provider>/<model>"],
  "aliases": ["<retired-model>", "<provider>/<retired-model>"]
}
Model selection

Delegate with finest/auto

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.

Per request

Keep control without changing the default path

Controls are optional. The header wins when both a header and metadata field are present, and malformed constraints are rejected rather than ignored.
x-finest-no-demotemetadata.finest_no_demote

Serve the named model for this request, even when exact evidence exists.

x-finest-strict-modelsmetadata.finest_strict_models

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'
Compatibility

Supported provider surfaces

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.

Operate

Receipts explain every decision

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.
NamePurpose
durableThe receipt landed in durable storage and survives a restart.
pendingA reference was assigned, but the durable write has not landed yet.
deferredA stream is open. The receipt lands after the stream completes.
terminal / droppedAccounting failed. Routing stops instead of serving an unrecorded outcome.
receipt_accounting_quarantinedNot 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.

Operate

Output caps

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.

Proof, not labels

Three evidence levels

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.

Access and spend

Keys, quotas, credits, and baselines

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.

Economics

No verified savings, no fee

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.
billing-law.txt
eligible_savings = max(0,
  min(origin_baseline_cost, approved_counterfactual_cost)
  - actual_fully_loaded_cost
)

fee = 25% * eligible_savings

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.

Evidence production

How a route earns authority

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.
  1. 01

    Freeze the job

    Bind prompt, schema, provider, endpoint, model revision, decoding, effort, adapter, prices, and corpus identity.

  2. 02

    Replay both arms

    Run paired items through the governed worker and retain errors, refusals, tokens, latency, and grader versions.

  3. 03

    Confirm once

    Apply preregistered quality, safety, economics, and worst-stratum gates on an untouched confirmation split.

  4. 04

    Publish or abstain

    Only a passing immutable record may authorize serving. A failed or incomplete result publishes no switch.

Coding agents

Install with an agent

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.

Portability

Leave with your evidence and policies

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. 1

    Export the bundle

    POST /v1/eject/export collects verification records, policies, receipts, credit history, and savings statements.

  2. 2

    Provision your provider keys

    The guide names the providers and environment variables your app needs. Finest cannot create provider accounts for you.

  3. 3

    Convert policies

    POST /v1/eject/convert-policies re-signs active policies into artifacts you hold.

  4. 4

    Verify independence

    GET /v1/eject/verify-independence lists every remaining dependency, including live fk_ keys, open canaries, queued work, and unconverted policies.

  5. 5

    Verify uninstall

    POST /v1/eject/verify-uninstall compares the restored client with the original recorded before the first edit.

Reference

Environment and response headers

Use environment variables for deployment-wide configuration and headers or metadata for optional per-request control.

Environment

NamePurpose
FINEST_GATEWAY_URLThe gateway origin shown beside the key. Do not guess it.
FINEST_API_KEYThe one-time-visible fk_ serving key.
OPENAI_API_KEYOptional direct-provider fallback for the shim and unsupported OpenAI endpoints.
ANTHROPIC_API_KEYOptional direct-provider fallback for the shim and unsupported Anthropic endpoints.
FINEST_DISABLESet to 1 to return the plain provider configuration when using the shim.

Response headers

NamePurpose
x-finest-receipt-idImmutable reference for the managed outcome.
x-finest-receipt-statePersistence state for that receipt.
x-finest-requested-modelThe model named by the caller.
x-finest-served-modelFinest's own identity for the endpoint it dispatched to.
x-finest-provider-reported-modelThe model the provider itself named in its response. Present on canonical serves when the provider reported one.
x-finest-evidence-labelOne of none, validated_per_request, recommended, verified_for_your_examples, proven_in_your_production.
x-finest-policy-versionPresent when a published policy decided the request.
x-finest-eligible-max-tokensPresent 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-requiredThe normalized region constraint applied to the request.
x-finest-residency-honoredWhether a stated residency requirement was satisfied.
x-finest-cacheWhat 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-errorLiteral 1 only for a proven pre-dispatch Finest refusal that the shim may replay direct.
Honest boundaries

Current limits

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.

API docs · Finest