Decisions API (/v1/decisions, /v1/systemone)

Decision models answer typed questions about an input and return probabilities instead of generated text: a yes/no probability, a pick from a fixed list, or a score on a scale. The AI Gateway serves them on two routes that share one provider list, so any model whose type is Decision works on either route.

Route	Alias	Request format	Use it when
`POST /v1/decisions`	`/decisions`	OpenAI Decisions: `input` plus a list of `predicate`, `choice`, and `score` questions	You write against OpenAI’s format or need image input
`POST /v1/systemone`	`/systemone`	System One: `state` plus a map of `noul`, `choice`, and `score` questions	You already have TypeSafe Jev request bodies

The route you call does not limit which provider you can use. OpenAI receives OpenAI-format bodies; every other provider receives System One bodies. Answers come back in the format of the route you called.

Feature	Supported	Notes
Tracing	Yes	Same request logs and spans as other gateway APIs
Cost tracking	Yes	Decision models bill input tokens only; set output cost to `0`
Rate limits, budgets, access control	Yes	Same as any other model
Virtual models, load balancing, fallbacks	Yes	A virtual model can mix OpenAI and System One targets
Streaming	No
Image input	OpenAI on `/v1/decisions` only	Other providers return `400`

Add the model with Model Types set to Decision. A chat model cannot serve these routes. Custom Endpoint pass-through of TypeSafe (the Jev guide) is a different path — it does not use /v1/systemone on the gateway, and it has no cost tracking.

Provider capabilities

Legend:

✅ Supported by provider and TrueFoundry
Provided by provider, but not by TrueFoundry
Provider does not support this feature

Provider	Example model	Gateway route it speaks natively	Images
OpenAI	`gpt-6-luna`	`/v1/decisions`	Yes
TypeSafe (Jev, Cloudflare Clef)	`jev-1.13.0`, `typesafe/jev`, `@cf/cloudflare/clef`	`/v1/systemone`	Clef only
OpenRouter	`typesafe/jev-1.13`	`/v1/systemone`	No
Perplexity	`pplx-decider-v1-27b`	`/v1/systemone`	No
Databricks	`databricks-openjev-qwen35-4b`, `system.ai.openjev-qwen35-4b`	`/v1/systemone`	No
Microsoft Foundry	`Microsoft-Decision-1`	`/v1/systemone`	No
Self-hosted vLLM	a Qwen3 / Qwen3.5 checkpoint	`/v1/systemone`	No

For every gateway endpoint and provider, see Supported APIs. The AI Gateway translates between the two formats per target:

Text parts of an OpenAI input are joined into the System One state. System One questions are named by their map keys when they go to OpenAI.
A noul’s criteria have no OpenAI field, so they are folded into the instructions OpenAI sees. Missing instructions on a System One question get a generic fallback such as “Is this true of the input?”.
safety_identifier is forwarded to OpenAI and dropped for other providers.
usage is left in the provider’s own shape so cost tracking still works.

Add a decision model

Pick the provider, add the model with Model Types = Decision, then call either route with the TrueFoundry FQN account-name/model-display-name.

Add the provider account

Follow the provider page for credentials and base URL:

TypeSafe — TypeSafe API key; optional Base URL for Cloudflare Workers AI
OpenAI
OpenRouter
Perplexity
Databricks
Microsoft Foundry
Self-hosted vLLM

Add the model with type Decision

Set Model Types to Decision. Pin a versioned Model ID where the provider offers one (jev-1.13.0 rather than jev-latest) so confidence thresholds stay stable across releases.

Call either route

Send your TrueFoundry API key to the AI Gateway. The gateway injects the upstream credential. Set GATEWAY_BASE_URL without a trailing slash.

`/v1/systemone`

The System One format. Send the content in state and named questions in questions. Answers come back keyed by those names. Set GATEWAY_BASE_URL to your gateway base URL without a trailing slash and TFY_API_KEY to your TrueFoundry API key.

import os

import requests

gateway_base_url = os.environ["GATEWAY_BASE_URL"].rstrip("/")
response = requests.post(
    f"{gateway_base_url}/v1/systemone",
    headers={"Authorization": f"Bearer {os.environ['TFY_API_KEY']}"},
    json={
        "model": "my-typesafe-account/jev",
        "state": "Customer wrote: I was charged twice for my order #4411 and want one of the charges refunded today.",
        "questions": {
            "is_refund_request": {
                "type": "noul",
                "instructions": "Is the customer asking for a refund?",
            },
            "urgency": {
                "type": "choice",
                "instructions": "How urgent is this?",
                "criteria": {
                    "low": "can wait a week",
                    "high": "needs action today",
                },
            },
            "frustration": {
                "type": "score",
                "instructions": "How frustrated is the customer?",
                "criteria": ["calm", "mildly annoyed", "angry"],
            },
        },
    },
    timeout=60,
)
response.raise_for_status()
print(response.json()["answers"]["is_refund_request"])

curl --fail-with-body -X POST "${GATEWAY_BASE_URL}/v1/systemone" \
  -H "Authorization: Bearer ${TFY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-typesafe-account/jev",
    "state": "Customer wrote: I was charged twice for my order #4411 and want one of the charges refunded today.",
    "questions": {
      "is_refund_request": {
        "type": "noul",
        "instructions": "Is the customer asking for a refund?"
      },
      "urgency": {
        "type": "choice",
        "instructions": "How urgent is this?",
        "criteria": {
          "low": "can wait a week",
          "high": "needs action today"
        }
      },
      "frustration": {
        "type": "score",
        "instructions": "How frustrated is the customer?",
        "criteria": ["calm", "mildly annoyed", "angry"]
      }
    }
  }'

Example response:

{
  "model": "jev-1.13.0",
  "answers": {
    "is_refund_request": { "type": "noul", "noul": 0.99 },
    "urgency": {
      "type": "choice",
      "choice": "high",
      "confidence": 1.0,
      "probabilities": { "low": 0.0, "high": 1.0 }
    },
    "frustration": {
      "type": "score",
      "score": 0.95,
      "confidence": 0.86,
      "legend": { "0": "calm", "1": "mildly annoyed", "2": "angry" },
      "probabilities": { "0": 0.07, "1": 0.91, "2": 0.02 }
    }
  },
  "usage": { "input_tokens": 391, "output_tokens": 67 }
}

Changing "model" to an OpenAI decision FQN asks OpenAI instead and still returns System One answers keyed by question name.

Field	Type	Description
`model`	string	TrueFoundry model FQN, `account-name/model-display-name`
`state`	string, object, or array	The content being judged — a support ticket, a document, or a transcript
`questions`	object	Named questions. Each key becomes a key in `answers`

Every question has a type and an optional instructions field.

`type`	`criteria`	Answer fields
`noul`	Optional object with `true` and `false` descriptions. A noul question needs `instructions` or `criteria`.	`noul`: probability that the answer is true, from 0 to 1
`choice`	Required object mapping labels to descriptions	`choice`, `confidence`, `probabilities` per label
`score`	Required array of levels, lowest first	`score` (0 to levels − 1), `confidence`, `legend`, `probabilities` per level

See the TypeSafe API reference for the full System One schema.

`/v1/decisions`

The OpenAI Decisions format. Send the content in input and a list of questions. Answers come back as a list in the same order, echoing each name.

import os

import requests

gateway_base_url = os.environ["GATEWAY_BASE_URL"].rstrip("/")
response = requests.post(
    f"{gateway_base_url}/v1/decisions",
    headers={"Authorization": f"Bearer {os.environ['TFY_API_KEY']}"},
    json={
        "model": "openai-main/gpt-6-luna",
        "input": "Customer wrote: I was charged twice for my order #4411 and want one of the charges refunded today.",
        "questions": [
            {
                "type": "predicate",
                "name": "is_refund_request",
                "instructions": "Is the customer asking for a refund?",
            },
            {
                "type": "choice",
                "name": "needs_human",
                "instructions": "Should a human agent take over?",
                "choices": [
                    {"value": True, "description": "billing dispute that needs a person"},
                    {"value": False},
                ],
            },
            {
                "type": "score",
                "name": "frustration",
                "instructions": "How frustrated is the customer?",
                "levels": [
                    {"label": "calm"},
                    {"label": "mildly annoyed"},
                    {"label": "angry", "description": "uses hostile language"},
                ],
            },
        ],
    },
    timeout=60,
)
response.raise_for_status()
print(response.json()["answers"][0])

curl --fail-with-body -X POST "${GATEWAY_BASE_URL}/v1/decisions" \
  -H "Authorization: Bearer ${TFY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai-main/gpt-6-luna",
    "input": "Customer wrote: I was charged twice for my order #4411 and want one of the charges refunded today.",
    "questions": [
      {
        "type": "predicate",
        "name": "is_refund_request",
        "instructions": "Is the customer asking for a refund?"
      },
      {
        "type": "choice",
        "name": "needs_human",
        "instructions": "Should a human agent take over?",
        "choices": [
          {"value": true, "description": "billing dispute that needs a person"},
          {"value": false}
        ]
      },
      {
        "type": "score",
        "name": "frustration",
        "instructions": "How frustrated is the customer?",
        "levels": [
          {"label": "calm"},
          {"label": "mildly annoyed"},
          {"label": "angry", "description": "uses hostile language"}
        ]
      }
    ]
  }'

Changing "model" to a TypeSafe Jev FQN sends the same questions to TypeSafe and still returns OpenAI-shaped answers.

Field	Type	Description
`model`	string	TrueFoundry model FQN, `account-name/model-display-name`
`input`	string or array	A string, or user messages whose `content` is a string or a list of `input_text` and `input_image` parts
`questions`	array	Questions to evaluate. Answers come back in the same order
`safety_identifier`	string, optional	A stable ID for your end user. Sent to OpenAI and dropped for other providers

Every question takes instructions and an optional name that is echoed in its answer. An unnamed question is keyed question_<index> when it is translated to System One.

`type`	Extra fields	Answer fields
`predicate`	None	`probability` that the answer is yes
`choice`	`choices`: entries of `{"value": string or boolean, "description": optional}`	`choice`, `probabilities` per value, `confidence`
`score`	`levels`: entries of `{"label": ..., "description": optional}`, lowest first	`score` (the probability-weighted level index), `probabilities` per level, `confidence`

A question the OpenAI model will not answer comes back as {"type": "refusal", "name": ...}.

Image input

input_image parts only work on OpenAI models, on /v1/decisions. image_url must be an inline data: URL — hosted URLs and file ids are not supported.

curl --fail-with-body -X POST "${GATEWAY_BASE_URL}/v1/decisions" \
  -H "Authorization: Bearer ${TFY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai-main/gpt-6-luna",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_text", "text": "Here is the swatch the customer uploaded."},
          {"type": "input_image", "image_url": "data:image/png;base64,<BASE64_PNG>"}
        ]
      }
    ],
    "questions": [
      {"type": "predicate", "name": "is_red", "instructions": "Is the swatch mostly red?"}
    ]
  }'

The same body with a TypeSafe, OpenRouter, Perplexity, Databricks, Microsoft Foundry, or vLLM model is rejected before that provider is called:

{
  "error": {
    "message": "No model available for this request can represent this decision. input_image parts are not supported because System One providers accept text input only.",
    "type": "invalid_request_error"
  }
}

Cloudflare Clef, added through a TypeSafe account pointed at Workers AI, accepts images on the System One images field instead — see TypeSafe.

Limits

These requests are rejected with a 400 before any provider is called:

Situation	What happens
Image parts on a System One provider	`input_image parts are not supported because System One providers accept text input only`
Two OpenAI questions with the same `name`	The names would collide into one System One answer
A choice with both `true` and `"true"`	System One keys choices by their text
A choice with one label, or a score with one level, sent to OpenAI	OpenAI requires at least two choices or levels
vLLM asked a `noul` or `score` question	vLLM serves `choice` questions only; the upstream `400` is forwarded

OpenAI requires instructions on every question. When a System One question without instructions goes to OpenAI, the AI Gateway fills in a generic one. Self-hosted vLLM answers only choice questions, and needs a vLLM build that includes vllm#59299 (after v0.31.0).

Virtual models

A virtual model whose model types include decision can load-balance or fail over across decision targets, including a mix of OpenAI and System One providers. The AI Gateway translates each attempt into that target’s dialect and translates the successful answer back into the dialect of the route you called. If every target cannot represent the request — for example every remaining target is System One and the body contains input_image — the gateway returns 400 with No model available for this request can represent this decision. Auto Routing can also use a TypeSafe Jev model as the classifier that picks simple / medium / complex for a chat virtual model. That is a routing setting, not a call you make to /v1/systemone. See Auto Routing.

Custom Endpoints vs these routes

The Jev Custom Endpoints guide forwards raw HTTP to https://api.typesafe.ai. You keep TypeSafe credentials on the gateway, but the path is /proxy-api/.../v1/systemone, cost tracking is unavailable, and you cannot switch providers by changing model. /v1/decisions and /v1/systemone use models in your catalog, so you get access control, tracing, cost tracking, virtual models, and the ability to change provider without changing the request body. Prefer the native TypeSafe integration unless you specifically need a transparent proxy.

Next steps

TypeSafe — add Jev, including via Cloudflare Workers AI.
OpenRouter — call Jev with an OpenRouter API key.
Auto Routing — let Jev pick the chat-model tier for each request.
TypeSafe API reference — System One question types.
OpenAI Decisions — OpenAI request and response schema.

Get Started

LLM Gateway

MCP Registry and Gateway

Skills Registry

Prompt Registry

Guardrails and Security

Observability

Deployment

Admin Guide

Chat

Messages

Embeddings

Rerank

Responses

Image

Audio

Batch

Files

Fine-tuning

Moderations

Video

Models

Decisions API (/v1/decisions, /v1/systemone)

Provider capabilities

Add a decision model

`/v1/systemone`

`/v1/decisions`

Image input

Limits

Virtual models

Custom Endpoints vs these routes

Next steps

​Provider capabilities

​Add a decision model

​/v1/systemone

​/v1/decisions

​Image input

​Limits

​Virtual models

​Custom Endpoints vs these routes

​Next steps

Provider capabilities

Add a decision model

`/v1/systemone`

`/v1/decisions`

Image input

Limits

Virtual models

Custom Endpoints vs these routes

Next steps