> For the complete documentation index, see [llms.txt](https://docs.fastrouter.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastrouter.ai/api-reference/decisions.md).

# Decisions

## Create Decisions

> Evaluates shared evidence (\`input\`) against a list of typed questions and returns structured answers instead of generated text. Served by OpenAI's Decisions API (\`gpt-6-luna\`, currently in public beta). FastRouter adds \`id\`, \`model\` and \`usage\` (with \`cost\`, \`chat\_id\` and \`provider\`) to the response.\
> \
> \*\*Question types\*\*\
> \- \`predicate\`: the probability (0 to 1) that a yes/no condition is true.\
> \- \`choice\`: one option from an unordered set, with a probability per option and a \`confidence\`.\
> \- \`score\`: a rating against ordered \`levels\` (lowest first), returned as the probability-weighted average of the 0-based level indices, with a probability per level and a \`confidence\`.\
> \- Give every question a unique \`name\`; it is echoed on its answer. A duplicate name is rejected with \`400\`.\
> \
> \*\*Behavior\*\*\
> \- One answer per question, in request order. A question the model declines comes back as \`{"type": "refusal", "name": "..."}\`; check \`type\` before reading \`probability\`, \`choice\` or \`score\`.\
> \- Images must be inline base64 data URLs in \`input\_image\` parts. Hosted image URLs and \`file\_id\` inputs are not supported.\
> \- Billed on input tokens only, so \`usage.output\_tokens\` is always \`0\`; \`usage.cost\` reports the charge in USD.\
> \- BYOK OpenAI keys, including custom hosts, are honoured. The upstream call is capped at about 15 seconds; a slower request fails with \`502\`.\
> \
> \*\*Response format\*\*\
> \- The response follows the shape of the request. A Decisions-shaped body (\`input\` plus a \`questions\` array) is answered with an \`answers\` array; a TypeSafe systemone-shaped body (\`state\` plus a \`questions\` object) is answered with \`answers\` keyed by question id.\
> \- Set \`response\_format\` to \`"decisions"\` or \`"systemone"\` to override. This changes only the response; the request keeps its own schema.\
> \- Alias path: \`/api/v1/systemone\` (same behavior).

```json
{"openapi":"3.1.0","info":{"title":"FastRouter API Reference","version":"1.0.0"},"tags":[{"name":"Decisions","description":"OpenAI Decisions API through FastRouter. Evaluate shared evidence against typed `predicate`, `choice` and `score` questions and receive calibrated probabilities, a selected option, or a rubric score instead of generated text."}],"servers":[{"url":"https://api.fastrouter.ai","description":"Production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"FastRouter API Key. Get yours at https://fastrouter.ai\n\nFormat: `Authorization: Bearer YOUR_API_KEY`"}},"schemas":{"DecisionsRequest":{"type":"object","required":["model","input","questions"],"properties":{"model":{"type":"string","description":"Decision model. `gpt-6-luna` is currently the only model served on this endpoint."},"input":{"description":"Shared evidence for all questions: a text string, or an array of user messages containing `input_text` and `input_image` parts. Forwarded to the provider byte-for-byte.","oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/DecisionsInputMessage"}}]},"questions":{"type":"array","minItems":1,"description":"Questions to evaluate against `input`. Answers come back in the same order. Each `name` must be unique.","items":{"$ref":"#/components/schemas/DecisionsQuestion"}},"response_format":{"description":"Overrides the response shape. By default the response follows the shape of the request, so a Decisions-shaped body is answered in the Decisions shape (an ordered `answers` array). `systemone` returns `answers` as a map keyed by question `name` in the TypeSafe systemone shape, with a `legend` on score answers. Accepted as a plain string or as an object `{\"type\": \"...\"}`. Aliases: `decision`/`openai` = decisions, `system_one`/`typesafe` = systemone. Any other value (e.g. `json_object`) is ignored. It changes only the **response**; the request keeps its own schema.","oneOf":[{"type":"string","enum":["decisions","systemone"]},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["decisions","systemone"]}}}]}}},"DecisionsInputMessage":{"type":"object","description":"A user message carrying text and/or image parts as shared evidence.","required":["role","content"],"properties":{"role":{"type":"string","enum":["user"]},"content":{"oneOf":[{"type":"string"},{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/DecisionsInputPart"}}]}}},"DecisionsInputPart":{"description":"One content part of a Decisions input message.","oneOf":[{"$ref":"#/components/schemas/DecisionsInputTextPart"},{"$ref":"#/components/schemas/DecisionsInputImagePart"}]},"DecisionsInputTextPart":{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string","description":"Text content."}}},"DecisionsInputImagePart":{"type":"object","required":["type","image_url"],"properties":{"type":{"type":"string","enum":["input_image"]},"image_url":{"type":"string","description":"Inline base64 data URL (`data:image/png;base64,...`). Hosted HTTP/HTTPS image URLs and `file_id` inputs are **not** supported."}}},"DecisionsQuestion":{"oneOf":[{"$ref":"#/components/schemas/DecisionsPredicateQuestion"},{"$ref":"#/components/schemas/DecisionsChoiceQuestion"},{"$ref":"#/components/schemas/DecisionsScoreQuestion"}]},"DecisionsPredicateQuestion":{"type":"object","description":"Checks a yes/no condition. The answer is the probability (0 to 1) that the condition is true.","required":["type","instructions"],"properties":{"type":{"type":"string","enum":["predicate"]},"name":{"type":"string","description":"Recommended. Identifier echoed on the answer and used as the map key in the systemone response shape. Must be unique across `questions`; a duplicate is rejected with 400."},"instructions":{"type":"string","description":"The condition to check, phrased as a yes/no question."}}},"DecisionsChoiceQuestion":{"type":"object","description":"Selects exactly one unordered option from `choices`. Returns the selected value, a probability for every option (sums to 1) and a `confidence`.","required":["type","instructions","choices"],"properties":{"type":{"type":"string","enum":["choice"]},"name":{"type":"string","description":"Recommended. Identifier echoed on the answer; must be unique across `questions`."},"instructions":{"type":"string","description":"What the model should decide."},"choices":{"type":"array","description":"The options, in the order you want `probabilities` returned. Include a fallback such as `other` when the options might not cover every input.","items":{"$ref":"#/components/schemas/DecisionsChoiceOption"}}}},"DecisionsChoiceOption":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"Returned as `choice` when selected."},"description":{"type":"string","description":"When this option applies."}}},"DecisionsScoreQuestion":{"type":"object","description":"Rates the input against ordered `levels` (lowest first). Returns a probability-weighted average of the level indices (starting at 0), the per-level distribution and a `confidence`.","required":["type","instructions","levels"],"properties":{"type":{"type":"string","enum":["score"]},"name":{"type":"string","description":"Recommended. Identifier echoed on the answer; must be unique across `questions`."},"instructions":{"type":"string","description":"What the model should rate."},"levels":{"type":"array","description":"Ordered levels, **lowest first**. Index 0 is the first level.","items":{"$ref":"#/components/schemas/DecisionsLevel"}}}},"DecisionsLevel":{"type":"object","required":["label"],"properties":{"label":{"type":"string","description":"Short level name. Echoed back on each `probabilities[]` entry of a score answer."},"description":{"type":"string","description":"Criteria for this level."}}},"DecisionsResponse":{"type":"object","required":["answers","id","model","usage"],"properties":{"answers":{"type":"array","description":"One answer per question, in request order. A question the upstream dropped is still present as a `refusal`.","items":{"$ref":"#/components/schemas/DecisionsAnswer"}},"id":{"type":"string","description":"FastRouter request ID (`fr_...`), also shown in the Activity Log."},"model":{"type":"string","description":"Model that served the request."},"usage":{"$ref":"#/components/schemas/DecisionsUsage"}}},"DecisionsAnswer":{"oneOf":[{"$ref":"#/components/schemas/DecisionsPredicateAnswer"},{"$ref":"#/components/schemas/DecisionsChoiceAnswer"},{"$ref":"#/components/schemas/DecisionsScoreAnswer"},{"$ref":"#/components/schemas/DecisionsRefusalAnswer"}]},"DecisionsPredicateAnswer":{"type":"object","required":["type","name","probability"],"properties":{"type":{"type":"string","enum":["predicate"]},"name":{"type":"string"},"probability":{"type":"number","minimum":0,"maximum":1,"description":"Probability that the condition is true."}}},"DecisionsChoiceAnswer":{"type":"object","required":["type","name","choice"],"properties":{"type":{"type":"string","enum":["choice"]},"name":{"type":"string"},"choice":{"type":"string","description":"The selected value."},"probabilities":{"type":"array","description":"One entry per option, in the order the choices were supplied. Sums to 1.","items":{"$ref":"#/components/schemas/DecisionsChoiceProbability"}},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Certainty derived from the distribution."}}},"DecisionsChoiceProbability":{"type":"object","required":["value","probability"],"properties":{"value":{"type":"string","description":"One of the supplied `choices[].value`."},"probability":{"type":"number","minimum":0,"maximum":1}}},"DecisionsScoreAnswer":{"type":"object","required":["type","name","score"],"properties":{"type":{"type":"string","enum":["score"]},"name":{"type":"string"},"score":{"type":"number","description":"Probability-weighted average of the level indices (0-based), so it can fall between levels."},"probabilities":{"type":"array","description":"One entry per level, in level order.","items":{"$ref":"#/components/schemas/DecisionsScoreProbability"}},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Certainty derived from the distribution."}}},"DecisionsScoreProbability":{"type":"object","required":["value","probability"],"properties":{"value":{"type":"integer","description":"Level index, starting at 0."},"label":{"type":"string","description":"The level's `label` as supplied in the request."},"probability":{"type":"number","minimum":0,"maximum":1}}},"DecisionsRefusalAnswer":{"type":"object","description":"Returned when the model declines to answer a question. Always check `type` before reading `probability`, `choice` or `score`.","required":["type","name"],"properties":{"type":{"type":"string","enum":["refusal"]},"name":{"type":"string"}}},"DecisionsUsage":{"type":"object","description":"Token usage and FastRouter billing metadata.","properties":{"input_tokens":{"type":"integer","description":"Input tokens billed."},"output_tokens":{"type":"integer","description":"Always `0`: Decisions bills input tokens only."},"total_tokens":{"type":"integer"},"cost":{"type":"number","description":"Cost of the request in USD."},"chat_id":{"type":"string","description":"Same as the top-level `id`."},"provider":{"type":"string","description":"Upstream provider that served the request."}}},"SystemOneDecisionsResponse":{"type":"object","description":"Returned when `response_format` is `systemone`, or when the request arrived in the TypeSafe systemone shape.","required":["answers","id","model","usage"],"properties":{"answers":{"type":"object","description":"Answers keyed by question `name`.","additionalProperties":{"$ref":"#/components/schemas/SystemOneAnswer"}},"id":{"type":"string"},"model":{"type":"string"},"usage":{"$ref":"#/components/schemas/DecisionsUsage"}}},"SystemOneAnswer":{"type":"object","description":"TypeSafe systemone-shaped answer. `noul` is the systemone name for a predicate. Only the fields relevant to `type` are present; a refusal is rendered as an answer with an empty `type` and no value fields.","required":["type"],"properties":{"type":{"type":"string","enum":["noul","choice","score",""]},"noul":{"type":"number","minimum":0,"maximum":1,"description":"Predicate answers: probability from 0 (no) to 1 (yes)."},"choice":{"type":"string","description":"Choice answers: the highest-probability option."},"score":{"type":"number","description":"Score answers: probability-weighted value across the levels."},"legend":{"type":"object","additionalProperties":{"type":"string"},"description":"Score answers: level index (as a string) mapped to its label."},"probabilities":{"type":"object","additionalProperties":{"type":"number"},"description":"Choice and score answers: option value or level index mapped to its probability."},"confidence":{"type":"number","minimum":0,"maximum":1}}},"DecisionsErrorResponse":{"type":"object","description":"OpenAI-style error envelope used by the Decisions format. `type` is derived from the HTTP status: 400/422 `invalid_request_error`, 401/403 `authentication_error`, 402 `insufficient_quota`, 404 `not_found_error`, 429 `rate_limit_error`, anything else `api_error`.","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"type":"string"},"type":{"type":"string","enum":["invalid_request_error","authentication_error","insufficient_quota","not_found_error","rate_limit_error","api_error"]},"param":{"type":"string","nullable":true},"code":{"type":"string","nullable":true}}}}}},"responses":{"UnauthorizedError":{"description":"Invalid Credentials - Your API key is invalid, missing, or disabled. Check your credentials.\n\nNote: the 401 error body uses `code`, `message`, `param`, and `type` (there is no `status` field), and `type` is `invalid_request_error`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"param":{"type":"string","nullable":true},"code":{"type":"string"}}}}}}}},"InsufficientCreditsError":{"description":"Insufficient Credits - Your account or API key has run out of credits. Add more credits and retry the request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":"string"},"status":{"type":"integer"}}}}}}}},"RateLimitError":{"description":"Rate Limited - You have exceeded your request limits (TPM/RPM). Slow down or increase your limits.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":"string"},"status":{"type":"integer"}}}}}}}}}},"paths":{"/api/v1/decisions":{"post":{"operationId":"createDecisions","tags":["Decisions"],"summary":"Create Decisions","description":"Evaluates shared evidence (`input`) against a list of typed questions and returns structured answers instead of generated text. Served by OpenAI's Decisions API (`gpt-6-luna`, currently in public beta). FastRouter adds `id`, `model` and `usage` (with `cost`, `chat_id` and `provider`) to the response.\n\n**Question types**\n- `predicate`: the probability (0 to 1) that a yes/no condition is true.\n- `choice`: one option from an unordered set, with a probability per option and a `confidence`.\n- `score`: a rating against ordered `levels` (lowest first), returned as the probability-weighted average of the 0-based level indices, with a probability per level and a `confidence`.\n- Give every question a unique `name`; it is echoed on its answer. A duplicate name is rejected with `400`.\n\n**Behavior**\n- One answer per question, in request order. A question the model declines comes back as `{\"type\": \"refusal\", \"name\": \"...\"}`; check `type` before reading `probability`, `choice` or `score`.\n- Images must be inline base64 data URLs in `input_image` parts. Hosted image URLs and `file_id` inputs are not supported.\n- Billed on input tokens only, so `usage.output_tokens` is always `0`; `usage.cost` reports the charge in USD.\n- BYOK OpenAI keys, including custom hosts, are honoured. The upstream call is capped at about 15 seconds; a slower request fails with `502`.\n\n**Response format**\n- The response follows the shape of the request. A Decisions-shaped body (`input` plus a `questions` array) is answered with an `answers` array; a TypeSafe systemone-shaped body (`state` plus a `questions` object) is answered with `answers` keyed by question id.\n- Set `response_format` to `\"decisions\"` or `\"systemone\"` to override. This changes only the response; the request keeps its own schema.\n- Alias path: `/api/v1/systemone` (same behavior).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionsRequest"}}}},"responses":{"200":{"description":"Decisions evaluated. The body shape depends on `response_format`.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/DecisionsResponse"},{"$ref":"#/components/schemas/SystemOneDecisionsResponse"}]}}}},"400":{"description":"Invalid request. Raised by FastRouter for a malformed `questions` value, a duplicate question `name`, or a model/provider combination that cannot be routed; otherwise relayed from the provider (unknown model, empty `questions`, missing `input`, unsupported image URL, unknown question type, and so on).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionsErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"402":{"$ref":"#/components/responses/InsufficientCreditsError"},"403":{"description":"The API key or project is not allowed to use the requested model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionsErrorResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"description":"Internal error, for example a failure resolving BYOK credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionsErrorResponse"}}}},"502":{"description":"The upstream provider could not be reached, or returned a response FastRouter could not decode. Provider HTTP errors are relayed with their original status instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionsErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.fastrouter.ai/api-reference/decisions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
