Build
Presets
Reuse model settings, instructions and tools.
{
"model": "@preset/product-writer",
"messages": [
{
"role": "user",
"content": "Describe our new export feature."
}
],
"max_tokens": 256
}Create a preset
Open Dashboard → Presets. Choose an example or select models and add instructions. Advanced settings are optional: leave fields blank to use request, model or account defaults. Save creates an active version. Edits affect future requests; running requests keep their captured version.
Use a preset
Send model: "@preset/your-slug", preset: "@preset/your-slug" beside a model, or model: "vendor/model@preset/your-slug". Include @preset/; bare slugs are ignored in the preset field. Chat Completions, Responses and Messages accept /v1 and /api/v1 prefixes. Conflicting references are rejected.
Override saved settings
Request fields replace saved fields, including entire nested objects. An explicit model replaces saved fallbacks. System/developer instructions replace saved instructions. Tools merge by name; request definitions replace matches. An empty tools list does not remove saved tools. Account and key restrictions always apply.
Use in chat
Choose Add preset in Chat. Selection pins a version; reselect after editing to use the update. Preset chat requires paid-credit consent. Use selected model instead overrides saved models; presets without models require a selection. Chat’s response limit overrides the preset’s. Execute function calls in an API client. Removing the preset restores ordinary chat and trial eligibility. Selecting a preset sends no message.
Preview and test
Preview validates settings without saving, inference or credit use. It checks catalog eligibility, not live availability, capacity, balance or Free quota. Auto models are selected again at dispatch. Paid tests use the active saved version and reject version changes before dispatch. After a disconnect, check the receipt before retrying: a missing receipt does not prove the request was uncharged.
Validation API
POST /presets/validate with config. Optional fields: protocol (chat/completions, messages or responses), request overrides and keyId. Sessions preview account policy unless keyId selects an owned key; API keys preview their own restrictions. Results include resolvedRequest, fieldSources, eligible models/providers, ignored fields and issues. Missing messages use a labelled sample. Free uses its fixed provider and rejects explicit routing overrides.
API permissions
Inference keys can invoke presets. To read or edit private configuration, grant preset-management access under API access. Grant it only to trusted integrations. GET /presets?view=selection returns active names, slugs, version IDs/numbers and hasModel without configuration; it accepts q, cursor and limit (maximum 50). Ordinary list, detail, history and export responses contain private configuration.
Capture a request
POST /api/v1/presets/{slug}/chat/completions, /messages or /responses with an inference body, a preset-management key and Idempotency-Key. Capture saves settings and system instructions without inference. It discards user messages, transient IDs, stream flags and credentials. Reusing the key returns the original version without reactivating it; different settings with the same key return a conflict.
Manage versions
Use GET/POST /presets; GET/PATCH/DELETE /presets/{slug}; GET/POST /presets/{slug}/versions; POST /presets/{slug}/activate or /duplicate; GET /presets/{slug}/export; POST /presets/import. Saving, editing, deleting and activating require expectedRevision to reject stale edits. History accepts limit (maximum 50) and beforeVersion; paginate with nextCursor. Imports and exports contain schemaVersion: 1, slug, name, description and config. Unsupported fields are rejected.
Models and providers
Use up to three distinct models in priority order, including the primary. An explicit model comes first; an explicit models list replaces saved fallbacks. Provider fields: order, only, ignore, sort, allow_fallbacks and max_price. These controls also work without presets on supported routes. Do not combine them with native providerOptions; provider_options is unsupported.
Provider backups
provider.allow_fallbacks: false excludes providers outside provider.order. Without an order, MiniRouter selects one provider that supports every fallback model. Sort by price, latency or throughput; insufficient performance data falls back to price. Preview reports the selection basis, not a latency guarantee. Native requests use providerOptions.gateway.allowFallbacks. Never retry automatically when paid acceptance is uncertain.
Price caps
Set provider.max_price: {prompt: 1, completion: 2} in USD per million tokens. Values: 0–1,000,000, up to six decimal places; omit for no cap. Zero requires a proven zero rate. Caps include markup and exclude routes exceeding either cap or lacking price evidence. Every fallback model needs an eligible provider. Cache charges, request fees and minimum charges are separate. Request provider settings replace saved caps. Native requests use providerOptions.gateway.maxPrice. Image, audio and per-request caps are unsupported.
Messages fallbacks
Messages accepts fallbacks: [{model: "vendor/model"}] with an explicit or saved primary. Entries allow only model. Do not combine fallbacks with models. The list replaces saved fallbacks; an empty list keeps only the primary. MiniRouter’s three-model limit includes the primary.
Messages output schemas
Use output_config.format or output_format; if both are supplied, they must match. Capture defaults the schema name to preset_output. Names allow 1–64 letters, numbers, hyphens or underscores; descriptions allow 5,000 characters. Request output_format replaces the schema; output_config replaces the entire saved output object, including effort. Schema support depends on the model and endpoint.
Count tokens
POST /v1/messages/count_tokens or /api/v1/messages/count_tokens counts the expanded prompt, tools, tool choice and thinking for the primary model without inference. Responses include preset version headers. Saved generation limits are ignored; explicit generation-only fields are rejected. Provider restrictions, price caps and disabled fallbacks are rejected because counting cannot enforce them. Ignored routing preferences return x-minirouter-overrides: ignored. Prevent-overrides policy still applies.
Limits and deletion
Accounts allow 100 active or archived presets and 200 versions per preset. At the version limit, existing versions still work; contact support or duplicate to a new slug. Archive blocks new requests until restored. Delete is permanent: it frees a slot and queues prompt/tool removal. Request identifiers remain for history; running requests can finish. Supported fields and limits are available at /presets/capabilities. Server tools, plugins, response caching, shared workspaces and stored Responses continuations are unsupported.
Account merges
Presets and history transfer during account merges. Duplicate slugs, including deleted ones, block merging. Transferred keys retain inference access but need a new management grant. Key rotation within an account preserves that grant.
Activity and reports
Select a preset or version in Activity to filter requests. Attribution survives edits and deletion; older requests without attribution are excluded. Request CSV exports cover 30 days. Activity, /usage/requests, /generation-report and their CSV exports accept presetId and optional presetVersionId; /v1/report uses preset_id and preset_version_id. Version filters require a preset ID. Restart pagination after changing filters. Generation detail returns presetProvenance; /v1/generation returns preset_provenance: presetId, versionId, slug, version and digest.