> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Router.Decisions SDK Reference

> SDK reference for the Router.Decisions API, available in Node.js and Python.

## Router.Decisions

### Create a Decision

**Beta.** Runs typed classification questions (`noul`, `choice`, `score`) against a native classify provider, including OpenAI Decisions with `openai/gpt-6-luna`, or a chat model that supports classify emulation. Emulated models answer through one structured-output call and their probabilities are model-reported rather than calibrated. Native providers can return `refusal` for individual questions; refused answers contain only `type`. The request and response follow the TypeSafe classification contract; `model` in the response identifies the primary or fallback model that answered and `usage` carries the computed cost like the Responses API. Both `/v3/router/classify` and `/v3/router/decisions` use this contract, including ordered `fallbacks`, request-level `retry`, and `identity` attribution. Both require `classify.execute`. This endpoint currently does not apply PII plugins or guardrails.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.router.decisions.create(model="openai/gpt-6-luna", questions={
          "positive": {
              "criteria": {
                  "false": "The customer is unhappy.",
                  "true": "The customer is happy.",
              },
              "instructions": "Is the sentiment positive?",
              "type": "noul",
          },
          "rating": {
              "criteria": [
                  "Negative",
                  "Neutral",
                  "Positive",
              ],
              "instructions": "Rate sentiment.",
              "type": "score",
          },
          "sentiment": {
              "criteria": {
                  "negative": "Negative sentiment",
                  "neutral": "Neutral sentiment",
                  "positive": "Positive sentiment",
              },
              "instructions": "Classify sentiment.",
              "type": "choice",
          },
      }, state="The customer says: I love this product. It is wonderful!", fallbacks=[
          {
              "model": "openai/gpt-5.6-luna",
          },
      ], identity={
          "display_name": "Sample customer",
          "id": "customer-demo",
      }, retry={
          "count": 2,
          "on_codes": [
              429,
              502,
              503,
              504,
          ],
      })

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.router.decisions.create({
      fallbacks: [
        {
          model: "openai/gpt-5.6-luna",
        },
      ],
      identity: {
        displayName: "Sample customer",
        id: "customer-demo",
      },
      model: "openai/gpt-6-luna",
      questions: {
        "positive": {
          criteria: {
            false: "The customer is unhappy.",
            true: "The customer is happy.",
          },
          instructions: "Is the sentiment positive?",
          type: "noul",
        },
        "rating": {
          criteria: [
            "Negative",
            "Neutral",
            "Positive",
          ],
          instructions: "Rate sentiment.",
          type: "score",
        },
        "sentiment": {
          criteria: {
            "negative": "Negative sentiment",
            "neutral": "Neutral sentiment",
            "positive": "Positive sentiment",
          },
          instructions: "Classify sentiment.",
          type: "choice",
        },
      },
      retry: {
        count: 2,
        onCodes: [
          429,
          502,
          503,
          504,
        ],
      },
      state: "The customer says: I love this product. It is wonderful!",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "model": str,  # required
        "questions": Dict[str, Union[QuestionsNoulQuestion, QuestionsChoiceQuestion, QuestionsScoreQuestion]],  # required
        "state": Union[str, Dict[str, Any], List[Any]],  # required
        "fallbacks": [{  # optional
            "model": str,  # required
        }],
        "identity": {  # optional
            "display_name": Optional[str],
            "email": Optional[str],
            "id": str,  # required
            "metadata": List[Dict[str, Any]],  # optional
            "tags": List[str],  # optional
        },
        "metadata": Dict[str, str],  # optional
        "name": Optional[str],
        "retry": {  # optional
            "count": int,  # required
            "on_codes": List[int],  # required
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      fallbacks?: {
        model: string;  // required
      }[];
      identity?: {
        displayName?: string;
        email?: string;
        id: string;  // required
        metadata?: Record<string, any>[];
        tags?: string[];
      };
      metadata?: Record<string, string>;
      model: string;  // required
      name?: string;
      questions: Record<string, QuestionsNoulQuestion | QuestionsChoiceQuestion | QuestionsScoreQuestion>;  // required
      retry?: {
        count: number;  // required
        onCodes: number[];  // required
      };
      state: string | { [k: string]: any } | any[];  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "answers": Dict[str, Union[ClassifyChoiceAnswer, ClassifyNoulAnswer, ClassifyRefusalAnswer, ClassifyScoreAnswer]],
        "model": str,
        "telemetry": {  # optional
            "span_id": str,
            "trace_id": str,
        },
        "usage": {
            "input_cost": Optional[float],
            "input_tokens": int,
            "input_tokens_details": {  # optional
                "cache_write_tokens": int,
                "cached_tokens": int,
            },
            "output_cost": Optional[float],
            "output_tokens": int,
            "total_cost": Optional[float],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      answers: Record<string, ClassifyChoiceAnswer | ClassifyNoulAnswer | ClassifyRefusalAnswer | ClassifyScoreAnswer>;
      model: string;
      telemetry?: {
        spanId: string;
        traceId: string;
      };
      usage: {
        inputCost?: number;
        inputTokens: number;
        inputTokensDetails?: {
          cacheWriteTokens: number;
          cachedTokens: number;
        };
        outputCost?: number;
        outputTokens: number;
        totalCost?: number;
      };
    }
    ```
  </CodeGroup>
</Expandable>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.