Build
Ask a question. Get a typed answer.
Turn shared state into probabilities, choices and scores. Choose an available model from the decision catalog.
- Boolean
How likely is this to be true? Get a probability from 0 to 1.
- Choice
Which option fits? Get a selection and option probabilities.
- Score
How well does it fit? Get a score against your ordered criteria.
Availability
A decision model is available when it appears in the decision catalog and your API key permits it. If no supported route is available, requests return HTTP 503 before a credit hold or provider call. Authenticated native discovery lists the models your key may use.
Your first decision
Set MINIROUTER_KEY to your integration key, then send an explicit model and question.
curl --fail-with-body https://api.minirouter.sh/v1/evaluate \
-H "Authorization: Bearer $MINIROUTER_KEY" \
-H 'Content-Type: application/json' \
--data '{
"model": "perplexity/pplx-decider-flash-v1.2",
"state": "The subscription was charged twice.",
"questions": {
"billing": {
"type": "boolean",
"instructions": "Does this describe a billing problem?"
}
}
}'Read the response
A typed answer, probabilities, and token usage. Example values are illustrative.
{
"model": "perplexity/pplx-decider-flash-v1.2",
"answers": {
"billing": { "type": "boolean", "probability": 0.98 }
},
"usage": { "inputTokens": 283, "outputTokens": 21 }
}These are illustrative values, not a live result.
Endpoints
Decision requests and authenticated native model discovery.
| Method | Path | Format |
|---|---|---|
| POST | /v1/decisions | Ordered predicate, choice and score questions; model-specific availability |
| POST | /v1/evaluate | Boolean, choice and score questions |
| POST | /typesafe/v1/systemone | Native TypeSafe noul, choice and score questions |
| GET | /typesafe/v1/models | Authenticated model discovery |
Choose a model from the catalog and use its documented endpoints and limits. The first request below uses PPLX Decider Flash v1.2. Use a MiniRouter integration API key as a bearer token and set model to the selected catalog ID. Chat endpoints, native aliases and omitted model defaults are unsupported.
Question types and limits
Question counts and request sizes vary by model.
- Boolean: use
type:and instructions. Optional criteria describe the true and false cases. The answer contains a probability from 0 to 1."boolean" - Choice: use
type:with a criteria object mapping option names to descriptions. The answer contains the selected choice and each option's probability."choice" - Score: use
type:with at least two ordered descriptions in a criteria array. The answer contains an interpolated score and each level's probability."score"
State and instructions accept strings, objects or arrays. Paid models accept up to 64 questions per request. Free Laya models accept one question per request. Each evaluation question allows 64 options per choice question or 2–10 levels per score question.
The normalized JSON sent to the provider must fit the selected model's byte limit, including routing fields added by MiniRouter. Check the model page and leave room for those fields. A byte limit is not a token estimate. The provider's context limit also applies to the input and questions.
Native decision format
Ordered questions and optional probability distributions.
Use / only when the selected model page lists that endpoint. Endpoint support and question limits vary by model.
Send an explicit model, input and an ordered questions array. Input accepts text or up to 64 messages with role: and text content. Questions accept an optional unique name and required text instructions:
- Predicate:
{ "type":."predicate", "instructions": "Does this describe a billing problem?" } - Choice: supply
choiceswith up to 255 entries (64 for Laya models) containing a string or booleanvalueand optional textdescription. - Score: supply
levelswith 2–10 entries containing a textlabeland optional textdescription.
Answers preserve question order and names. Predicate answers include probability; choice answers include choice; score answers include score. Choice and score answers may also include confidence and a probabilities array. Do not assume those optional fields are present. Usage uses input_, output_ and total_.
Models with refusal support can return { "type":. A refusal is a completed, billable result on paid routes. Preserve its position; do not automatically retry it.
Decision routes currently accept text input. Images, remote URLs, file IDs, audio and streaming are unsupported.
Native TypeSafe format
Use noul, choice, and score through /typesafe/v1/systemone.
Jev models also support the native TypeSafe format. This format and the SDK examples below need a Jev model listed in the decision catalog. Send requests to / on https:. Use noul in place of boolean; its answer uses { "type":. Native usage fields are input_ and output_. Choice and score answers include confidence, and score also includes the requested level legend.
Native errors use { "message":. Invalid request shapes return 422; malformed JSON returns 400. Missing or invalid MiniRouter keys return 401. Native model discovery requires authentication and lists only enabled models your key may use.
JavaScript and Python SDKs
Pinned versions, explicit models, and zero automatic retries.
These examples use JavaScript SDK 0.6.0 and synchronous Python SDK 0.7.0 with the native TypeSafe endpoint. Use the request fields and question formats documented above.
Install @typesafe-ai/, set MINIROUTER_, and run this JavaScript as an ES module:
import { TypeSafeClient, noul } from '@typesafe-ai/sdk';
const client = new TypeSafeClient({
apiKey: process.env.MINIROUTER_KEY,
baseURL: 'https://api.minirouter.sh/typesafe',
retry: { maxRetries: 0 },
});
const result = await client.systemOne({
model: 'typesafe-ai/jev',
state: 'The subscription was charged twice.',
questions: { billing: noul('Does this describe a billing problem?') },
});
console.log(result);For Python, install typesafe-sdk==0. and set the same environment variable:
import os
from typesafe_sdk import TypeSafeClient, RetryPolicy, Noul
with TypeSafeClient(
api_key=os.environ['MINIROUTER_KEY'],
base_url='https://api.minirouter.sh/typesafe',
retry=RetryPolicy(max_retries=0),
) as client:
result = client.system_one(
model='typesafe-ai/jev',
state='The subscription was charged twice.',
questions={'billing': Noul(instructions='Does this describe a billing problem?')},
)
print(result)Keep the explicit model and zero-retry setting; do not override retries on individual requests. X-Should-Retry: does not disable SDK retries. Two explicit calls remain two separate requests and may produce two charges.
Include question instructions and keep state and questions within the request limits. Native aliases, omitted instructions, structured criterion descriptions and extra request fields are unsupported. The Python example uses the synchronous client. Pointing an AI SDK Gateway client directly at MiniRouter is unsupported.
Pricing and settlement
The final charge is verified provider inference cost plus 10%, rounded once to nano-USD. Read the standard input, output and request rates in the model catalog. Catalog prices already include the markup. A verified zero-cost request has a zero customer charge. Pending or missing cost does not mean free. Provider promotions may change; no free period is guaranteed.
Paid requests reserve a temporary credit hold from the model’s input bound and the number of questions submitted. Jev uses a shared request-level bound instead of multiplying the bound by question count. The hold can substantially exceed the final charge for a small request; it is not a minimum bill. The unused amount is released after settlement. If the hold expires before provider cost is known, reconciliation continues. A later verified exact-zero receipt finalizes the request without a customer charge. The response header X-Minirouter-Billing-State: means final provider cost is still being reconciled. Read the settled charge in account activity. Output usage remains counted even when output is free.
Free decision models
Zero customer charges and shared free-inference allowances.
A model explicitly offered as free uses shared free-inference quotas and concurrency limits. Laya and Laya Free accept one question per request, with up to 64 choices. No deposit or monetary hold is required, and the customer charge stays zero even if the upstream later reports a cost. Changing endpoints does not reset the allowance. The model’s token ceiling includes input and any reported output usage; see the selected model's limits. A missing provider-cost receipt remains pending reconciliation.
Free availability depends on current route and zero-price evidence. An unavailable free route does not fall back to a paid model.
Retries and unsupported fields
One upstream attempt. No streaming, chat parameters, or fallback models.
Disable automatic client retries. Each new incoming request has a separate billing identity. A timeout or lost response can still incur provider cost. Each accepted request makes at most one upstream attempt; X-Should-Retry: is advisory and does not disable a library's retry policy.
Streaming, chat parameters, fallback models, caller providerOptions, duplicate JSON keys and unknown request fields are rejected. An invalid provider response can still incur a charge. MiniRouter does not automatically retry it.