Build

Ask a question. Get a typed answer.

Turn shared state into probabilities, choices and scores. Choose an available model from the decision catalog.

  1. Boolean

    How likely is this to be true? Get a probability from 0 to 1.

  2. Choice

    Which option fits? Get a selection and option probabilities.

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

POST /v1/evaluate
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.
Example response
{
  "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.
MethodPathFormat
POST/v1/decisionsOrdered predicate, choice and score questions; model-specific availability
POST/v1/evaluateBoolean, choice and score questions
POST/typesafe/v1/systemoneNative TypeSafe noul, choice and score questions
GET/typesafe/v1/modelsAuthenticated 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: "boolean" and instructions. Optional criteria describe the true and false cases. The answer contains a probability from 0 to 1.
  • Choice: use type: "choice" with a criteria object mapping option names to descriptions. The answer contains the selected choice and each option's probability.
  • Score: use type: "score" with at least two ordered descriptions in a criteria array. The answer contains an interpolated score and each level's probability.

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 /v1/decisions 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: "user" 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 choices with up to 255 entries (64 for Laya models) containing a string or boolean value and optional text description.
  • Score: supply levels with 2–10 entries containing a text label and optional text description.

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_tokens, output_tokens and total_tokens.

Models with refusal support can return { "type": "refusal", "name": null }. 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 /typesafe/v1/systemone on https://api.minirouter.sh. Use noul in place of boolean; its answer uses { "type": "noul", "noul": 0.98 }. Native usage fields are input_tokens and output_tokens. Choice and score answers include confidence, and score also includes the requested level legend.

Native errors use { "message": "…", "error_type": "…" }. 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/sdk@0.6.0, set MINIROUTER_KEY, and run this JavaScript as an ES module:

Pinned SDK examples
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.7.0 and set the same environment variable:

Pinned SDK examples
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: false 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: pending 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: false 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.

References

API sources, authentication, and billing.