> ## 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.

# Classify

> **Deprecated.** Use `POST /v3/router/decisions` and `orq.router.decisions.create()` for new integrations. This endpoint remains available for backward compatibility with the same request and response contract.

**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.

<Warning>
  Classify is deprecated. Use [Create decisions](/reference/decisions/create-decisions) and `orq.router.decisions.create()` for new integrations. Existing `/classify` clients remain supported with the same request and response contract.
</Warning>

See the [Decisions guide](/ai-gateway/features/decisions) for examples and migration instructions.


## OpenAPI

````yaml post /v3/router/classify
openapi: 3.1.0
info:
  title: orq.ai API
  version: '2.0'
  description: orq.ai API documentation
servers:
  - url: https://my.orq.ai
security:
  - ApiKey: []
tags:
  - name: Chunking
    description: Split text into smaller chunks for retrieval and generation workflows.
  - name: File Systems
    description: >-
      Create and manage persistent file systems that agents and MCP clients read
      from and write to.
  - name: Knowledge Bases
    description: Create and manage knowledge bases used by agents and retrieval workflows.
  - name: Memory Stores
    description: Create and manage memory stores, memories, and memory documents.
  - name: Evals
    description: Run an evaluator against a conversation and its result
  - name: Logs
    description: >-
      OpenTelemetry log query API. Search, filter, aggregate, and facet log
      records ingested via OTLP.
  - name: Reporting
    description: >-
      GenAI reporting API over canonical analytics rollups. Accepts a metric
      name, time range, grain, group-by, and filters; returns a typed time
      series and optional totals.
  - name: Traces
    description: >-
      Query and inspect ingested trace data: search trace summaries, aggregate
      metrics, and read individual traces and their spans.
  - description: List models available through the AI Router.
    name: Models
  - name: Policies
  - name: Alerts
    description: >-
      Alerts evaluate a Reporting API metric on a fixed interval and fire
      notifications through notifiers when the value breaches a threshold. Each
      breach opens a trigger that tracks the incident until the value recovers.
  - name: Annotation Queues
    description: Annotation queues collect spans for human review.
  - name: API keys
    description: >-
      API keys authenticate programmatic access to the workspace. They expose
      opaque tokens, per-domain access grants, and budget and rate-limit
      constraints.
  - name: Audit Logs
    description: Audit logs record workspace entity changes and access-relevant events.
  - name: Budgets
    description: >-
      Budgets govern spend, token usage, and request rate across six scopes:
      workspace, project, identity, API key, provider, and model. Every
      applicable budget is enforced, and the most restrictive limit applies per
      dimension.
  - name: Files
    description: File upload and retrieval operations.
  - name: Guardrail Rules
    description: >-
      Guardrail Rules conditionally enforce evaluators and plugins for AI
      Gateway traffic. Rules may be scoped to a project or the whole workspace.
  - name: Hub
    description: Hub items are reusable templates available to a workspace.
  - name: Identities
    description: >-
      Identities represent end users from your system for usage and engagement
      tracking.
  - name: Management keys
    description: >-
      Management keys are workspace-scoped credentials that authenticate
      programmatic access to workspace administration surfaces (API keys,
      budgets). Unlike project-scoped API keys, a management key always operates
      at the workspace level.
  - name: MCP Gateway
    description: >-
      Register upstream MCP servers, discover and sync their tools, and assemble
      gateways that expose a curated tool surface to MCP clients.
  - name: Model Catalog
    description: >-
      Browse the orq.ai model catalog: every model orq offers, across every
      provider, with pricing, capabilities and benchmark data. List endpoints
      only return models that are not deprecated. This API is public, requires
      no authentication, and is rate limited to 120 requests per minute per IP.
      Responses carry a 5-minute cache-control max-age.
  - name: Notifiers
    description: Notifier destinations used to send delivery and workflow notifications.
  - name: Projects
    description: Projects organize resources within a workspace
  - name: Routing Rules
    description: >-
      Routing Rules conditionally select models and enforce request plugins for
      AI Gateway traffic. Rules are evaluated by ascending priority and may be
      scoped to a project or the whole workspace.
  - name: Threads
    description: Threads group related trace invocations and their aggregate usage
  - name: Skills
    description: >-
      Skills are modular instructions you can use to codify processes and
      conventions
  - name: Smart Routers
    description: >-
      Create and manage workspace Smart Routers. A Smart Router selects a model
      from an eligible pool for each request according to a quality, balanced,
      or cost profile.
  - name: Webhooks
    description: >-
      Create and manage webhooks that deliver workspace events to external HTTPS
      endpoints.
  - name: Workspaces
    description: >-
      A workspace is the tenant. Create is called from a user session during
      onboarding; Get, List, and Update are the public management surface.
  - name: Workspace Security
    description: >-
      Workspace-level domain verification and IP allowlist controls. These
      operations are restricted to workspace administrators.
  - name: Workspace Settings
    description: >-
      Workspace-level settings managed with a workspace credential. A workspace
      is the tenant, so these settings are a singleton — there is nothing to
      create or delete, only read and update.
  - name: Responses
  - description: Run agents on a cron cadence. Minimum firing interval is 1 hour.
    name: Agent Schedules
  - name: Embeddings
  - name: Telemetry
    description: >-
      Unified query envelope for traces, metrics, and logs. One request shape,
      one filter dialect, and one response shape per source, validated by a
      per-source registry.
  - description: Beta. Run typed classification questions against a classify model.
    name: Classify
  - description: Search Gateway with managed credits or BYOK.
    name: Web Search
  - description: Beta. Run classification decisions with the classify contract.
    name: Decisions
externalDocs:
  url: https://docs.orq.ai
  description: orq.ai Documentation
paths:
  /v3/router/classify:
    post:
      tags:
        - Classify
      summary: Classify
      description: >-
        **Deprecated.** Use `POST /v3/router/decisions` and
        `orq.router.decisions.create()` for new integrations. This endpoint
        remains available for backward compatibility with the same request and
        response contract.


        **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.
      operationId: CreateClassify
      requestBody:
        content:
          application/json:
            examples:
              fallback_retry_identity:
                summary: Decisions with fallbacks, retries and identity
                value:
                  fallbacks:
                    - model: openai/gpt-5.6-luna
                  identity:
                    id: customer-demo
                    display_name: Sample customer
                  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: null
                        positive: Positive sentiment
                      instructions: Classify sentiment.
                      type: choice
                  retry:
                    count: 2
                    on_codes:
                      - 429
                      - 502
                      - 503
                      - 504
                  state: 'The customer says: I love this product. It is wonderful!'
              openai_inline_image:
                description: >-
                  A small self-contained PNG. Replace it with your own base64
                  image data URL.
                summary: Classify an inline image with OpenAI Decisions
                value:
                  model: openai/gpt-6-luna
                  questions:
                    contains_text:
                      instructions: Does the image contain text?
                      type: noul
                  state:
                    - content:
                        - text: Evaluate this image.
                          type: input_text
                        - image_url: >-
                            data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAACLSURBVHgBdY8NDYAgEIXBBEQgAhG0gRGMYBNtoA2M4EygDYygDfCxvdMbk7d9A453f8ZQMcYAWuBVzIHujeGyxE8nYz7dJWYl01p749zxDKABEzhYfDNaMPZSAUymJLZLuvSsSVUhx4G7VM2xpSzQ5YYhLUHDCGoad47ixXjxY84qi1a9QPgZpdYLPVkbtsfywz3jAAAAAElFTkSuQmCC
                          type: input_image
                      role: user
              openai_text:
                summary: Classify text with OpenAI Decisions
                value:
                  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: null
                        positive: Positive sentiment
                      instructions: Classify sentiment.
                      type: choice
                  state: 'The customer says: I love this product. It is wonderful!'
              support_ticket:
                summary: Classify a support message
                value:
                  model: typesafe/jev-latest
                  questions:
                    is_complaint:
                      instructions: Is the customer complaining?
                      type: noul
                    severity:
                      criteria:
                        - Minor
                        - Moderate
                        - Severe
                      instructions: How severe is the issue?
                      type: score
                    topic:
                      criteria:
                        delivery: Shipping or delivery issues
                        other: null
                        product: Product quality
                      instructions: What is the message mainly about?
                      type: choice
                  state: The parcel arrived two days late and the box was crushed.
            schema:
              additionalProperties: false
              properties:
                fallbacks:
                  description: >-
                    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. Image requests require native OpenAI image-capable
                    fallbacks.
                  items:
                    $ref: '#/components/schemas/FallbackConfig'
                  maxItems: 10
                  type:
                    - array
                    - 'null'
                identity:
                  $ref: '#/components/schemas/ResponseIdentity'
                  description: The identity to attach to the trace.
                metadata:
                  additionalProperties:
                    type: string
                  description: Key-value metadata attached to the trace.
                  type: object
                model:
                  description: >-
                    ID of a model that supports native or emulated classify,
                    including openai/gpt-6-luna.
                  type: string
                name:
                  description: >-
                    The name to display on the trace. If not specified, the
                    default system name will be used.
                  type: string
                questions:
                  additionalProperties:
                    oneOf:
                      - description: >-
                          Answers with a probability between 0 and 1 that the
                          statement holds.
                        properties:
                          criteria:
                            description: Optional descriptions of what true and false mean.
                            properties:
                              'false':
                                type: string
                              'true':
                                type: string
                            type: object
                          instructions:
                            anyOf:
                              - title: String
                                type: string
                              - additionalProperties: true
                                title: Object
                                type: object
                              - items: {}
                                title: Array
                                type: array
                            description: >-
                              The evaluation prompt for this question. A string,
                              an object or an array.
                          type:
                            enum:
                              - noul
                            type: string
                        required:
                          - type
                          - instructions
                        title: NoulQuestion
                        type: object
                      - description: >-
                          Picks one of the given options and returns the
                          probability of each.
                        properties:
                          criteria:
                            additionalProperties:
                              type:
                                - string
                                - 'null'
                            description: >-
                              Options keyed by name, each mapped to a
                              description or null.
                            minProperties: 1
                            type: object
                          instructions:
                            anyOf:
                              - title: String
                                type: string
                              - additionalProperties: true
                                title: Object
                                type: object
                              - items: {}
                                title: Array
                                type: array
                            description: >-
                              The evaluation prompt for this question. A string,
                              an object or an array.
                          type:
                            enum:
                              - choice
                            type: string
                        required:
                          - type
                          - instructions
                          - criteria
                        title: ChoiceQuestion
                        type: object
                      - description: >-
                          Places the state on an ordered scale and returns the
                          probability of each level.
                        properties:
                          criteria:
                            description: >-
                              Ordered level descriptions from lowest to highest.
                              At least two levels.
                            items:
                              type: string
                            minItems: 2
                            type: array
                          instructions:
                            anyOf:
                              - title: String
                                type: string
                              - additionalProperties: true
                                title: Object
                                type: object
                              - items: {}
                                title: Array
                                type: array
                            description: >-
                              The evaluation prompt for this question. A string,
                              an object or an array.
                          type:
                            enum:
                              - score
                            type: string
                        required:
                          - type
                          - instructions
                          - criteria
                        title: ScoreQuestion
                        type: object
                  description: >-
                    Typed questions keyed by an identifier of your choice. Each
                    answer is returned under the same key.
                  minProperties: 1
                  type: object
                retry:
                  $ref: '#/components/schemas/ClassifyRetryConfig'
                  description: Retry configuration for the request.
                state:
                  anyOf:
                    - title: String
                      type: string
                    - additionalProperties: true
                      title: Object
                      type: object
                    - items: {}
                      title: Array
                      type: array
                  description: >-
                    The content to evaluate. A string, an object or an array.
                    For OpenAI GPT-6 Luna, strings are passed as text and
                    objects or ordinary JSON arrays are serialized as text.
                    User-message arrays accept string content or
                    input_text/input_image parts. Images must be inline base64
                    data URLs, with at most 128 images across the request.
                    Remote image URLs, file IDs, audio, non-user roles, bare
                    content parts and tool items are rejected.
              required:
                - model
                - state
                - questions
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                openai_answers:
                  summary: OpenAI Decisions answers and usage
                  value:
                    model: openai/gpt-6-luna
                    answers:
                      positive:
                        type: noul
                        noul: 1
                      rating:
                        type: score
                        score: 2
                        legend:
                          '0': Negative
                          '1': Neutral
                          '2': Positive
                        probabilities:
                          '0': 0
                          '1': 0
                          '2': 1
                        confidence: 1
                      sentiment:
                        type: choice
                        choice: positive
                        probabilities:
                          negative: 0
                          neutral: 0
                          positive: 1
                        confidence: 1
                    usage:
                      input_tokens_details:
                        cached_tokens: 0
                        cache_write_tokens: 0
                      input_tokens: 408
                      output_tokens: 0
                      input_cost: 0.0000408
                      output_cost: 0
                      total_cost: 0.0000408
                partial_refusal:
                  description: >-
                    Illustrative response. A provider may refuse one question
                    while answering the rest. Refusals have no scored fields.
                  summary: One question is refused
                  value:
                    model: openai/gpt-6-luna
                    answers:
                      positive:
                        type: refusal
                      rating:
                        type: score
                        score: 2
                        legend:
                          '0': Negative
                          '1': Neutral
                          '2': Positive
                        probabilities:
                          '0': 0
                          '1': 0
                          '2': 1
                        confidence: 1
                      sentiment:
                        type: choice
                        choice: positive
                        probabilities:
                          negative: 0
                          neutral: 0
                          positive: 1
                        confidence: 1
                    usage:
                      input_tokens_details:
                        cached_tokens: 0
                        cache_write_tokens: 0
                      input_tokens: 408
                      output_tokens: 0
                      input_cost: 0.0000408
                      output_cost: 0
                      total_cost: 0.0000408
              schema:
                additionalProperties: false
                properties:
                  answers:
                    additionalProperties:
                      $ref: '#/components/schemas/ClassifyAnswer'
                    description: >-
                      Answers keyed by the question identifiers from the
                      request.
                    type: object
                  model:
                    description: >-
                      The requested ID of the model that answered. This can be a
                      fallback model.
                    type: string
                  telemetry:
                    $ref: '#/components/schemas/ResponseTelemetry'
                    description: OpenTelemetry trace and span identifiers for this request.
                  usage:
                    $ref: '#/components/schemas/ClassifyUsage'
                    description: The usage information for the request.
                required:
                  - model
                  - answers
                  - usage
                type: object
          description: Returns one answer per question.
        '400':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  error:
                    $ref: '#/components/schemas/APIError'
                required:
                  - error
                type: object
          description: >-
            Malformed JSON, missing or unsupported model, or invalid
            retry/fallback fields.
        '401':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  error:
                    $ref: '#/components/schemas/APIError'
                required:
                  - error
                type: object
          description: Missing, invalid, expired or revoked API key.
        '403':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  error:
                    $ref: '#/components/schemas/APIError'
                required:
                  - error
                type: object
          description: >-
            The API key lacks classify permission, or the workspace or project
            cannot access the model.
        '422':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  error:
                    $ref: '#/components/schemas/APIError'
                required:
                  - error
                type: object
          description: The state or a question violates the classification contract.
        '429':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  error:
                    $ref: '#/components/schemas/APIError'
                required:
                  - error
                type: object
          description: A plan rate limit, budget or provider rate limit was exceeded.
        '500':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  error:
                    $ref: '#/components/schemas/APIError'
                required:
                  - error
                type: object
          description: An internal model-resolution error occurred.
        '502':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  error:
                    $ref: '#/components/schemas/APIError'
                required:
                  - error
                type: object
          description: >-
            The upstream provider failed or returned an invalid classification
            response.
      deprecated: true
      x-code-samples:
        - label: Node.js
          lang: typescript
          source: |-
            const result = await orq.router.classify.create({
              model: "typesafe/jev-latest",
              state: "The parcel arrived two days late and the box was crushed.",
              questions: {
                is_complaint: { type: "noul", instructions: "Is the customer complaining?" },
                topic: {
                  type: "choice",
                  instructions: "What is the message mainly about?",
                  criteria: { delivery: "Shipping or delivery issues", product: "Product quality", other: null },
                },
                severity: { type: "score", instructions: "How severe is the issue?", criteria: ["Minor", "Moderate", "Severe"] },
              },
            });
        - label: Python
          lang: python
          source: |-
            result = client.router.classify.create(
                model="typesafe/jev-latest",
                state="The parcel arrived two days late and the box was crushed.",
                questions={
                    "is_complaint": {"type": "noul", "instructions": "Is the customer complaining?"},
                    "topic": {
                        "type": "choice",
                        "instructions": "What is the message mainly about?",
                        "criteria": {"delivery": "Shipping or delivery issues", "product": "Product quality", "other": None},
                    },
                    "severity": {"type": "score", "instructions": "How severe is the issue?", "criteria": ["Minor", "Moderate", "Severe"]},
                },
            )
        - label: 'Node.js: OpenAI text'
          lang: typescript
          source: |-
            import { Orq } from "@orq-ai/node";

            const orq = new Orq({ apiKey: process.env["ORQ_API_KEY"] ?? "" });
            const result = await orq.router.classify.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": null,
                    "positive": "Positive sentiment"
                  },
                  "instructions": "Classify sentiment.",
                  "type": "choice"
                }
              },
              "state": "The customer says: I love this product. It is wonderful!"
            });

            for (const [name, answer] of Object.entries(result.answers)) {
              if (answer.type === "refusal") {
                console.log(name, "refused");
                continue;
              }
              console.log(name, answer);
            }
        - label: 'Python: OpenAI text'
          lang: python
          source: >-
            import json

            import os

            from orq_ai_sdk import Orq


            client = Orq(api_key=os.environ["ORQ_API_KEY"])

            request = json.loads("{\n  \"model\": \"openai/gpt-6-luna\",\n 
            \"questions\": {\n    \"positive\": {\n      \"criteria\":
            {\n        \"false\": \"The customer is unhappy.\",\n       
            \"true\": \"The customer is happy.\"\n      },\n     
            \"instructions\": \"Is the sentiment positive?\",\n      \"type\":
            \"noul\"\n    },\n    \"rating\": {\n      \"criteria\": [\n       
            \"Negative\",\n        \"Neutral\",\n        \"Positive\"\n     
            ],\n      \"instructions\": \"Rate sentiment.\",\n      \"type\":
            \"score\"\n    },\n    \"sentiment\": {\n      \"criteria\":
            {\n        \"negative\": \"Negative sentiment\",\n       
            \"neutral\": null,\n        \"positive\": \"Positive
            sentiment\"\n      },\n      \"instructions\": \"Classify
            sentiment.\",\n      \"type\": \"choice\"\n    }\n  },\n  \"state\":
            \"The customer says: I love this product. It is wonderful!\"\n}")

            result = client.router.classify.create(**request)


            for name, answer in result.answers.items():
                if answer.type == "refusal":
                    print(name, "refused")
                    continue
                print(name, answer)
        - label: 'cURL: OpenAI text'
          lang: bash
          source: |-
            curl https://my.orq.ai/v3/router/classify \
              -H "Authorization: Bearer $ORQ_API_KEY" \
              -H "Content-Type: application/json" \
              --data-binary @- <<'JSON'
            {
              "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": null,
                    "positive": "Positive sentiment"
                  },
                  "instructions": "Classify sentiment.",
                  "type": "choice"
                }
              },
              "state": "The customer says: I love this product. It is wonderful!"
            }
            JSON
        - label: 'Node.js: OpenAI inline image'
          lang: typescript
          source: |-
            import { Orq } from "@orq-ai/node";

            const orq = new Orq({ apiKey: process.env["ORQ_API_KEY"] ?? "" });
            const result = await orq.router.classify.create({
              "model": "openai/gpt-6-luna",
              "questions": {
                "contains_text": {
                  "instructions": "Does the image contain text?",
                  "type": "noul"
                }
              },
              "state": [
                {
                  "content": [
                    {
                      "text": "Evaluate this image.",
                      "type": "input_text"
                    },
                    {
                      "image_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAACLSURBVHgBdY8NDYAgEIXBBEQgAhG0gRGMYBNtoA2M4EygDYygDfCxvdMbk7d9A453f8ZQMcYAWuBVzIHujeGyxE8nYz7dJWYl01p749zxDKABEzhYfDNaMPZSAUymJLZLuvSsSVUhx4G7VM2xpSzQ5YYhLUHDCGoad47ixXjxY84qi1a9QPgZpdYLPVkbtsfywz3jAAAAAElFTkSuQmCC",
                      "type": "input_image"
                    }
                  ],
                  "role": "user"
                }
              ]
            });

            for (const [name, answer] of Object.entries(result.answers)) {
              if (answer.type === "refusal") {
                console.log(name, "refused");
                continue;
              }
              console.log(name, answer);
            }
        - label: 'Python: OpenAI inline image'
          lang: python
          source: >-
            import json

            import os

            from orq_ai_sdk import Orq


            client = Orq(api_key=os.environ["ORQ_API_KEY"])

            request = json.loads("{\n  \"model\": \"openai/gpt-6-luna\",\n 
            \"questions\": {\n    \"contains_text\": {\n      \"instructions\":
            \"Does the image contain text?\",\n      \"type\": \"noul\"\n   
            }\n  },\n  \"state\": [\n    {\n      \"content\": [\n       
            {\n          \"text\": \"Evaluate this image.\",\n         
            \"type\": \"input_text\"\n        },\n        {\n         
            \"image_url\":
            \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAACLSURBVHgBdY8NDYAgEIXBBEQgAhG0gRGMYBNtoA2M4EygDYygDfCxvdMbk7d9A453f8ZQMcYAWuBVzIHujeGyxE8nYz7dJWYl01p749zxDKABEzhYfDNaMPZSAUymJLZLuvSsSVUhx4G7VM2xpSzQ5YYhLUHDCGoad47ixXjxY84qi1a9QPgZpdYLPVkbtsfywz3jAAAAAElFTkSuQmCC\",\n         
            \"type\": \"input_image\"\n        }\n      ],\n      \"role\":
            \"user\"\n    }\n  ]\n}")

            result = client.router.classify.create(**request)


            for name, answer in result.answers.items():
                if answer.type == "refusal":
                    print(name, "refused")
                    continue
                print(name, answer)
        - label: 'cURL: OpenAI inline image'
          lang: bash
          source: |-
            curl https://my.orq.ai/v3/router/classify \
              -H "Authorization: Bearer $ORQ_API_KEY" \
              -H "Content-Type: application/json" \
              --data-binary @- <<'JSON'
            {
              "model": "openai/gpt-6-luna",
              "questions": {
                "contains_text": {
                  "instructions": "Does the image contain text?",
                  "type": "noul"
                }
              },
              "state": [
                {
                  "content": [
                    {
                      "text": "Evaluate this image.",
                      "type": "input_text"
                    },
                    {
                      "image_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAACLSURBVHgBdY8NDYAgEIXBBEQgAhG0gRGMYBNtoA2M4EygDYygDfCxvdMbk7d9A453f8ZQMcYAWuBVzIHujeGyxE8nYz7dJWYl01p749zxDKABEzhYfDNaMPZSAUymJLZLuvSsSVUhx4G7VM2xpSzQ5YYhLUHDCGoad47ixXjxY84qi1a9QPgZpdYLPVkbtsfywz3jAAAAAElFTkSuQmCC",
                      "type": "input_image"
                    }
                  ],
                  "role": "user"
                }
              ]
            }
            JSON
        - label: 'Node.js: Fallbacks, retries and identity'
          lang: typescript
          source: |-
            import { Orq } from "@orq-ai/node";

            const orq = new Orq({ apiKey: process.env["ORQ_API_KEY"] ?? "" });
            const result = await orq.router.classify.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": null,
                    "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!"
            });

            for (const [name, answer] of Object.entries(result.answers)) {
              if (answer.type === "refusal") {
                console.log(name, "refused");
                continue;
              }
              console.log(name, answer);
            }
        - label: 'Python: Fallbacks, retries and identity'
          lang: python
          source: >-
            import json

            import os

            from orq_ai_sdk import Orq


            client = Orq(api_key=os.environ["ORQ_API_KEY"])

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

            result = client.router.classify.create(**request)


            for name, answer in result.answers.items():
                if answer.type == "refusal":
                    print(name, "refused")
                    continue
                print(name, answer)
        - label: 'cURL: Fallbacks, retries and identity'
          lang: bash
          source: |-
            curl https://my.orq.ai/v3/router/classify \
              -H "Authorization: Bearer $ORQ_API_KEY" \
              -H "Content-Type: application/json" \
              --data-binary @- <<'JSON'
            {
              "fallbacks": [
                {
                  "model": "openai/gpt-5.6-luna"
                }
              ],
              "identity": {
                "id": "customer-demo",
                "display_name": "Sample customer"
              },
              "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": null,
                    "positive": "Positive sentiment"
                  },
                  "instructions": "Classify sentiment.",
                  "type": "choice"
                }
              },
              "retry": {
                "count": 2,
                "on_codes": [
                  429,
                  502,
                  503,
                  504
                ]
              },
              "state": "The customer says: I love this product. It is wonderful!"
            }
            JSON
components:
  schemas:
    FallbackConfig:
      additionalProperties: false
      properties:
        model:
          type: string
      required:
        - model
      type: object
    ResponseIdentity:
      additionalProperties: false
      properties:
        display_name:
          type: string
        email:
          type: string
        id:
          type: string
        metadata:
          items:
            type: object
            additionalProperties: {}
          type:
            - array
            - 'null'
        tags:
          items:
            type: string
          type:
            - array
            - 'null'
      required:
        - id
      type: object
    ClassifyRetryConfig:
      additionalProperties: false
      properties:
        count:
          description: >-
            Number of retries per model after the initial attempt (1-5). No
            retries are made when retry is omitted.
          format: int64
          maximum: 5
          minimum: 1
          type: integer
        on_codes:
          description: >-
            HTTP status codes that trigger retries, between 100 and 599.
            Retry-After is honored; otherwise the gateway waits one second.
          items:
            format: int64
            maximum: 599
            minimum: 100
            type: integer
          minItems: 1
          type: array
      required:
        - count
        - on_codes
      type: object
    ClassifyAnswer:
      description: >-
        One answer to a classification question. The type selects the answer
        fields. A refusal contains only type.
      discriminator:
        mapping:
          choice: '#/components/schemas/ClassifyChoiceAnswer'
          noul: '#/components/schemas/ClassifyNoulAnswer'
          refusal: '#/components/schemas/ClassifyRefusalAnswer'
          score: '#/components/schemas/ClassifyScoreAnswer'
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/ClassifyNoulAnswer'
        - $ref: '#/components/schemas/ClassifyChoiceAnswer'
        - $ref: '#/components/schemas/ClassifyScoreAnswer'
        - $ref: '#/components/schemas/ClassifyRefusalAnswer'
    ResponseTelemetry:
      additionalProperties: false
      properties:
        span_id:
          type: string
        trace_id:
          type: string
      required:
        - trace_id
        - span_id
      type: object
    ClassifyUsage:
      additionalProperties: false
      properties:
        input_cost:
          description: >-
            Cost (USD) of input tokens. Present when billing was computed for
            this request.
          format: double
          type: number
        input_tokens:
          description: The number of input tokens processed.
          format: int64
          type: integer
        input_tokens_details:
          $ref: '#/components/schemas/ClassifyInputTokensDetails'
          description: >-
            Provider-reported cache token usage. OpenAI Decisions does not
            charge for cache reads or writes.
        output_cost:
          description: >-
            Cost (USD) of output tokens. 0 for native classify providers,
            including OpenAI Decisions. Present when billing was computed for
            this request.
          format: double
          type: number
        output_tokens:
          description: >-
            The number of output tokens generated. Free for native classify
            providers, billed at the model rate for emulated chat models.
          format: int64
          type: integer
        total_cost:
          description: >-
            Total cost (USD) of the request. Present when billing was computed
            for this request.
          format: double
          type: number
      required:
        - input_tokens
        - output_tokens
      type: object
    APIError:
      additionalProperties: false
      properties:
        code:
          type:
            - string
            - 'null'
        failures: {}
        message:
          type: string
        param:
          type:
            - string
            - 'null'
        type:
          type: string
      required:
        - message
        - type
        - param
        - code
      type: object
    ClassifyChoiceAnswer:
      additionalProperties: false
      properties:
        choice:
          description: The selected option. Present for choice answers.
          type: string
        confidence:
          description: >-
            How sure the model is of the answer it selected: on emulated chat
            models the largest value in probabilities, so it adds nothing the
            distribution does not; native providers return their own confidence
            value, which can sit below the largest probability. Present for
            choice and score answers.
          format: double
          type: number
        probabilities:
          additionalProperties:
            type: number
            format: double
          description: >-
            Probability distribution over the options or levels. Present for
            choice and score answers.
          type: object
        type:
          enum:
            - choice
          type: string
      required:
        - type
        - choice
      title: ClassifyChoiceAnswer
      type: object
    ClassifyNoulAnswer:
      additionalProperties: false
      properties:
        noul:
          description: >-
            Probability between 0 and 1 that the statement holds. Present for
            noul answers.
          format: double
          type: number
        type:
          enum:
            - noul
          type: string
      required:
        - type
        - noul
      title: ClassifyNoulAnswer
      type: object
    ClassifyRefusalAnswer:
      additionalProperties: false
      properties:
        type:
          enum:
            - refusal
          type: string
      required:
        - type
      title: ClassifyRefusalAnswer
      type: object
    ClassifyScoreAnswer:
      additionalProperties: false
      properties:
        confidence:
          description: >-
            How sure the model is of the answer it selected: on emulated chat
            models the largest value in probabilities, so it adds nothing the
            distribution does not; native providers return their own confidence
            value, which can sit below the largest probability. Present for
            choice and score answers.
          format: double
          type: number
        legend:
          additionalProperties:
            type: string
          description: Level index to level description. Present for score answers.
          type: object
        probabilities:
          additionalProperties:
            type: number
            format: double
          description: >-
            Probability distribution over the options or levels. Present for
            choice and score answers.
          type: object
        score:
          description: >-
            Position on the scale, not an index: on emulated chat models and
            OpenAI Decisions the weighted index, each level index multiplied by
            that level probability and summed, so the value is usually
            fractional; typesafe/jev-latest returns its own score. Present for
            score answers.
          format: double
          type: number
        type:
          enum:
            - score
          type: string
      required:
        - type
        - score
      title: ClassifyScoreAnswer
      type: object
    ClassifyInputTokensDetails:
      additionalProperties: false
      properties:
        cache_write_tokens:
          description: Input tokens written to cache.
          format: int64
          type: integer
        cached_tokens:
          description: Input tokens read from cache.
          format: int64
          type: integer
      required:
        - cached_tokens
        - cache_write_tokens
      type: object
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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