Skip to main content
POST
Create typed decisions with a decision model

Overview

Decision models answer named, typed questions about the state you provide instead of generating prose:
  • choice selects one named option and returns a probability for every option.
  • score returns an expected score over an ordered rubric.
  • noul returns the probability that a yes/no statement is true.
PPLX Decider v1.2, Clef and Clef Flash can also evaluate images: send up to four photos with your questions and get the same typed answers. See Image input. For new HTTP integrations, use the native POST /api/v1/decisions endpoint. If you already use the official TypeSafe SDK, point it at NanoGPT’s POST /api/v1/systemone compatibility endpoint. Decision models are also available through NanoGPT’s OpenAI-compatible Chat Completions and Responses APIs and the Anthropic-compatible Messages API. Only input tokens are billed. Browse every decision model, with current pricing, on nano-gpt.com/models/decisions, or list them with GET /api/v1/decision-models.
Decision models work on both API hosts. The examples use the direct API host, https://api.nano-gpt.com; https://nano-gpt.com accepts the same requests. See API Hosts.Before using a model on either host, check that host’s GET /api/v1/models?detailed=true&output_modalities=decisions catalog for the model, its supported_endpoints, and its decision_input capabilities and limits. Catalogs can differ during rollouts.
Decision models return calibrated probabilities, not generated text. Use a chat model when you need an explanation or other free-form response.

Models

Use perplexity/pplx-decider-v1.2 for PPLX integrations. Requests for the retired perplexity/pplx-decider-v1.1-27b ID return HTTP 410 with code model_retired; update the model ID explicitly to use v1.2. The v1.2 price is $0.02 per million input tokens, with free output. Clef also accepts clef. The System One compatibility endpoint also accepts the official SDK model names jev-1.13 and jev-latest. GET /api/v1/models leaves decision models out, because they reject plain chat requests. List them with GET /api/v1/decision-models, which returns detailed entries by default (detailed=false for IDs only), or add output_modalities=decisions to /api/v1/models and its subscription, paid and personalized variants. Each entry has architecture.output_modalities: ["decisions"], a supported_endpoints list, and a decision_input object. decision_input.image_input is true for the image-capable models, and decision_input.image_limits lists their limits. For Clef and Clef Flash, the 1,800-token limit covers all text in the request, including state text, questions and request overhead. Images are counted separately; see Image input.

Native Decisions API

Endpoint

Authenticate with either Authorization: Bearer YOUR_API_KEY or x-api-key: YOUR_API_KEY.

Example request

Example response

noul is the probability of the true outcome. A score can be fractional because it is the expected value across the returned score distribution.

Usage and cost

Every response reports usage.input_tokens and usage.output_tokens. Only input tokens are billed; output tokens are free. By default, the response is returned as soon as the answers are ready, and billing settles immediately afterwards. The charge itself is unaffected. These responses report usage.estimated_cost: the model’s published input price for the reported input tokens, in USD. It does not include account discounts or payment-currency conversion, so your actual charge can differ. To get the exact amount charged instead, send "include_usage": true. The response then waits for billing to settle and reports the exact charge, in USD, as usage.cost instead of usage.estimated_cost. This adds a little latency. Your usage history always shows the exact charge.

Declined questions

A decision model can decline individual questions. On models that do this, such as GPT-6 Luna Decisions, a declined question comes back with only a type, and the other questions keep their answers:
Check each answer’s type before reading its value. A response with a declined question returns 200 and is charged normally. If every question is declined, the request returns 400 with the code content_policy_violation and isn’t charged. The compatibility endpoints return a declined question the same way, inside the JSON text. The official TypeSafe JavaScript SDK returns it as is. The Python SDK drops answer types it doesn’t recognize and logs a warning, so a declined question is simply missing from answers.

Image input

perplexity/pplx-decider-v1.2, cloudflare/clef and cloudflare/clef-flash accept images on the native POST /api/v1/decisions endpoint and the POST /api/v1/systemone compatibility endpoint. Use them to classify photos, score visual content, or answer yes/no questions about an image. Make state an array, and put each image directly in it as an image_url part with a base64 data URL. Plain strings in the same array add text context. The optional image_url.detail field accepts auto, low or high.
To compare several images, put a label before each one, for example ["Photo 1", image1, "Photo 2", image2], and refer to the labels in your question criteria. Images are billed as input tokens at the model’s normal input price; usage.input_tokens includes them. Resize larger photos before sending them. Privacy rules for image requests:
  • PPLX Decider v1.2 supports zero data retention: set provider.zdr to true, or use an API key with a ZDR policy.
  • Clef and Clef Flash do not support zero data retention. On these models, requests that require ZDR, and image requests with provider.data_collection: "deny", return 400.
  • Image input cannot be combined with PII redaction.
  • PII redaction uses the provider you chose (Tinfoil or Grepture; see PII Redaction). Tinfoil-hosted decision models do not support it.
Image errors use these codes: The Chat Completions, Responses and Messages compatibility endpoints accept text only.

Question types

instructions and criterion descriptions can be strings, non-empty JSON objects, or non-empty arrays. A choice criterion may also be null when its label is self-explanatory. The top-level state can be a string, JSON object, or JSON array. Question names become keys in answers. Any question can come back declined instead.

Model-specific rules

Request fields

For Jev 1.13, Jev Latest and Liquid D1, the provider object can contain endpoint-level order, only, ignore, allow_fallbacks, require_parameters, max_price, zdr, and data_collection controls. These names describe native Decisions endpoints such as TypeSafe; they are not NanoGPT provider IDs. PPLX Decider v1.2 uses a fixed decision endpoint and accepts only zdr and data_collection. Clef and Clef Flash support NanoGPT provider selection, including only, order, ignore, allow_fallbacks, max_price, and sort (price or auto). Clef and Clef Flash reject zdr: true. API-key provider restrictions and zero-data-retention requirements apply to every model.

Official TypeSafe SDK

NanoGPT exposes POST /api/v1/systemone so the official TypeSafe JavaScript and Python SDKs can call any decision model without changing their request types. Set the model to jev-latest, jev-1.13, liquid/d1, perplexity/pplx-decider-v1.2, clef or cloudflare/clef-flash. Image input and include_usage work the same way as on the native endpoint.
The SDK’s System One call is supported. The SDK’s model-list method is not, because NanoGPT’s /api/v1/models response uses the NanoGPT/OpenAI-compatible model-list shape rather than TypeSafe’s model-list shape.

OpenAI and Anthropic compatibility

Use these shapes when a decision model must fit into an existing OpenAI- or Anthropic-compatible client. The answer object is returned as JSON text, so parse the returned string once. Chat Completions and Responses report usage.estimated_cost by default. To get the exact charge as usage.cost, send "include_usage": true or "stream_options": {"include_usage": true}. Messages responses always report the exact charge.

Chat Completions

Parse choices[0].message.content as JSON.

Responses API

Parse output_text as JSON. The same JSON text is also available in the assistant output item.

Anthropic Messages

Parse content[0].text as JSON. max_tokens is accepted for Anthropic SDK compatibility but does not change the fixed typed output.

Limitations

Decision-model requests are deliberately narrower than chat generation requests:
  • Only non-streaming text input in user messages is supported on compatibility endpoints. Image input is available only on the native Decisions and System One endpoints, for PPLX Decider v1.2, Clef and Clef Flash.
  • System, developer, assistant, tool, audio, video, and file input is not supported. Compatibility endpoints also reject images.
  • Tools, sampling controls, log probabilities, and reasoning generation controls are not supported.
  • Output-token-limit fields are accepted where an SDK requires them, but they do not change the fixed typed output.
  • BYOK and accountless x402 payments are not supported.
  • Standard NanoGPT or X-Provider provider pins are not supported. Use the native Decisions provider object only when you need endpoint-level routing controls.
Unsupported combinations return a 400 error instead of being silently ignored.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
model
enum<string>
required

Decision model ID. clef is an alias of the prefixed IDs. Use perplexity/pplx-decider-v1.2 for PPLX. The retired perplexity/pplx-decider-v1.1-27b ID returns HTTP 410 with code model_retired.

Available options:
typesafe/jev-1.13,
~typesafe/jev-latest,
typesafe/jev-latest,
liquid/d1,
cloudflare/clef,
clef,
cloudflare/clef-flash,
perplexity/pplx-decider-v1.2
state
required

Application state to evaluate. PPLX Decider v1.2, Clef and Clef Flash also accept an array that mixes plain strings with up to four image_url parts holding static PNG, JPEG or WebP base64 data URLs, each at most 512x512 pixels (240,000 base64 characters in total). Remote image URLs are not fetched.

questions
object
required
provider
object | null

Optional model-specific routing controls. Jev 1.13, Jev Latest and Liquid D1 use native Decisions endpoint names. PPLX Decider v1.2 accepts only zdr and data_collection. Clef and Clef Flash support NanoGPT provider selection and reject zdr true.

session_id
string
Maximum string length: 256
trace
object
user
string
Maximum string length: 256
include_usage
boolean
default:false

Wait for billing to settle and report the exact charge as usage.cost. By default the response returns without waiting and reports usage.estimated_cost.

Response

Typed decisions response

model
string
required
answers
object
required
usage
object
required
id
string