---
title: "Decisions"
method: POST
path: "/v3/router/decisions"
tags: ["Decisions"]
---

# Decisions

`POST /v3/router/decisions`

## Request

- Base URL: `https://my.orq.ai`
- URL: `https://my.orq.ai/v3/router/decisions`
- Auth: HTTP bearer

**Beta.** Evaluate content against named questions and receive structured answers, probabilities, and usage costs. Send the content as `state` and define each entry in `questions` as:

- `noul`: estimate the probability that a statement is true.
- `choice`: select an option from a set.
- `score`: rate the content on an ordered scale.
- `box`: locate one target in an image and return its bounding box. Beta, TypeSafe `jev-preview` only.

Instructions and criteria accept strings or structured JSON. TypeSafe models also accept inline images through `assets` (beta).

Use a native decision model or a supported chat model. Configure ordered `fallbacks`, optional `retry`, `timeout.call_timeout` in milliseconds, and an exact-match `cache`. Each retry and fallback gets a fresh timeout; omit `retry` to move directly to the next fallback on timeout. The response identifies the model that answered.

Requires the `classify` API-key permission. PII plugins and guardrails are not applied. See the [Decisions guide](/ai-gateway/features/decisions) for supported models, probability interpretation, and refusals.

## Request body

- object
  - `assets` object: Beta, TypeSafe models only. Inline images keyed by a reference string. Write the reference in state, instructions or criteria wherever the image belongs; every asset must be referenced. Required for box questions.
  - `cache` ClassifyCacheConfig
    - `ttl` integer: Time to live for the cached response in seconds, up to 259200 (3 days). Defaults to 3600.
    - `type` 'exact_match', required: Cache type. Only exact_match is supported.
  - `fallback_on_codes` integer[], nullable: HTTP status codes that trigger fallback. Defaults to [408,429,500,502,503,504,529]. Each code must be unique and between 400 and 599.
  - `fallbacks` FallbackConfig[], nullable: Up to 10 fallback models in order. The gateway retries a model for matching error codes before trying the next model. Every model must support classification and satisfy access checks. Requests with images in state require native OpenAI image-capable fallbacks; requests with assets or box questions require TypeSafe fallbacks.
    - `model` string, required
  - `identity` ResponseIdentity
    - `display_name` string
    - `email` string
    - `id` string, required
    - `metadata` object[], nullable
    - `tags` string[], nullable
  - `metadata` object: Key-value metadata attached to the trace.
  - `model` string, required: ID of a model that supports native or emulated classify, including openai/gpt-6-luna.
  - `name` string: The name to display on the trace. If not specified, the default system name will be used.
  - `prompt_cache_key` string: Native OpenAI only. Partitions reuse of shared input across requests.
  - `prompt_cache_options` ClassifyPromptCacheOptions
    - `mode` 'implicit' | 'explicit': Implicit uses the shared input boundary by default; explicit uses only marked input boundaries.
    - `ttl` '30m': Minimum cache lifetime. Only 30m is supported by native OpenAI Decisions.
  - `questions` object, required: Typed questions keyed by an identifier of your choice. Each answer is returned under the same key. Native OpenAI accepts 1 to 400 questions.
  - `retry` ClassifyRetryConfig
    - `count` integer, required: Number of retries per model after the initial attempt (0-5). Set 0 to disable retries. When retry is omitted, the gateway retries twice.
    - `on_codes` integer[]: HTTP status codes that trigger retries, between 100 and 599. Defaults to [408, 429, 500, 502, 503, 504, 529]. Retry-After is honored; otherwise the gateway backs off exponentially.
  - `state` union, required: The content to evaluate. A string, an object or an array. For TypeSafe models, reference images declared in assets by writing their reference string. Native OpenAI accepts messages and function/custom-tool history. User messages support input_text, input_image and input_json; images can use inline base64 data URLs or public HTTP(S) URLs. At most 128 images across state and question instructions. Shared text/image parts support explicit prompt_cache_breakpoint markers. File IDs, audio, item references and bare content parts are unsupported. Other objects and arrays are serialized as text.
    - string
    - object
    - unknown[]
      - unknown
  - `timeout` ClassifyTimeoutConfig
    - `call_timeout` integer, required: Timeout in milliseconds for each model call. Set 2000 for two seconds. When retry is configured, timeout errors (408) are automatically retried.

## Response `200`

Returns one answer per question.

- object
  - `answers` object, required: Answers keyed by the question identifiers from the request.
  - `model` string, required: The requested ID of the model that answered. This can be a fallback model.
  - `telemetry` ResponseTelemetry
    - `span_id` string, required
    - `trace_id` string, required
  - `usage` ClassifyUsage, required
    - `input_cost` number, double: Cost (USD) of input tokens. Present when billing was computed for this request.
    - `input_tokens` integer, required: The number of input tokens processed.
    - `input_tokens_details` ClassifyInputTokensDetails
      - `cache_write_tokens` integer, required: Input tokens written to cache.
      - `cached_tokens` integer, required: Input tokens read from cache.
    - `output_cost` number, double: Cost (USD) of output tokens. 0 for native classify providers, including OpenAI Decisions. Present when billing was computed for this request.
    - `output_tokens` integer, required: The number of output tokens generated. Free for native classify providers, billed at the model rate for emulated chat models.
    - `total_cost` number, double: Total cost (USD) of the request. Present when billing was computed for this request.

## Other responses

- `400`: Malformed JSON, missing or unsupported model, or invalid retry, timeout, or fallback fields.
- `401`: Missing, invalid, expired or revoked API key.
- `403`: The API key lacks classify permission, or the workspace or project cannot access the model.
- `408`: The final model call exceeded its timeout after available retries and fallbacks were exhausted.
- `422`: The state or a question violates the classification contract.
- `429`: A plan rate limit, budget or provider rate limit was exceeded.
- `500`: An internal model-resolution error occurred.
- `502`: The upstream provider failed or returned an invalid classification response.

## Changes

> 554 revisions in range; 71 not diffed.

- **2026-10-29** `928a71e92252`: 2 info
  - added the new optional request property `prompt_cache_key`
  - added the new optional request property `prompt_cache_options`
- **2026-10-29** `33d63277cd4e`: 2 warning
  - removed the request property `prompt_cache_key`
  - removed the request property `prompt_cache_options`
- **2026-10-29** `ccec1a4526ee`: 2 info
  - added the new optional request property `prompt_cache_key`
  - added the new optional request property `prompt_cache_options`
- **2026-10-28** `58f2f0cd5c1e`: 2 warning
  - removed the request property `prompt_cache_key`
  - removed the request property `prompt_cache_options`
- **2026-10-27** `12559332d797`: 2 info
  - added the new optional request property `prompt_cache_key`
  - added the new optional request property `prompt_cache_options`

[Operation history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v3/router/decisions/post.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) - [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/928a71e92252?raw)