Classify

Classify is in Beta, and its request and response contract matches the TypeSafe Classify API.

Answers natively on OpenAI GPT-6 Luna and typesafe/jev-latest, and through structured outputs on a set of small chat models: see Supported models.
Does not apply PII plugins, guardrails, or evaluators yet: see Enforcement during the Beta.
Requires an API key with the classify permission.

Overview

Classify answers typed questions about a piece of content in one call. Send the content as state and one or more named questions to POST /decisions or POST /classify on the AI Gateway base URL, https://my.orq.ai/v3/router. Both endpoints accept the same request and return the same response. Existing /classify clients can continue using that path. The SDK methods are orq.router.decisions.create() and orq.router.classify.create(). The response returns one structured answer per question, so nothing has to be parsed out of free-form text. A choice or score answer also carries the probabilities behind it and a confidence for the selected option or level. A question pairs plain-language instructions with a type that fixes the answer shape, and criteria that define the rubric:

`type`	What the answer is	Reach for it when
`noul`	The probability that the statement in `instructions` is true, in `[0, 1]`	Yes/no decisions, or a probability to threshold instead of a hard label
`choice`	One option from a named rubric, with a probability for each option	The content belongs to one of a known set: a queue, a topic, a category
`score`	A position on an ordered scale, with a probability for each level	The answer is a degree rather than a category: sentiment, quality, effort

state is not limited to text: an object or array is serialized as JSON before classification, so the same call can judge a customer message, a tool payload, or a whole record. Several questions can be asked at once, each with its own rubric, so a request costs one round trip instead of one call per question. See Question types for the criteria each type expects. The request is traced, priced, and rate-limited like other gateway traffic. See Enforcement during the Beta for what applies today.

Use cases

Triage and routing. Ask noul whether the message reports a problem and choice for the topic or product, then route on the labels and escalate the rows whose confidence is low.
Building labelled data. Turn a rubric into a choice question to label a corpus for Evaluators or Datasets, and use probabilities to pick the rows worth human review.
Scoring open feedback. Use score on survey answers, support transcripts, or review text to get an ordinal reading without writing a scoring prompt.
Gating expensive work. Use a noul question on the native model, whose output tokens are free, as a pre-check, and send only the requests that pass on to a larger model.
Enriching structured records. Pass a record as state and ask one question per field to derive, instead of building a prompt per field.
Comparing models on one rubric. Ask the same questions against typesafe/jev-latest and a chat model to see where they disagree. Thresholds tuned on one do not transfer, so compare answers rather than raw probabilities.

Supported models

Model	How it answers	Output tokens
`openai/gpt-6-luna`, `openai/eu.gpt-6-luna`	Native OpenAI Decisions. Returns provider probabilities and confidence.	Free
`typesafe/jev-latest`	Native classify model. Probabilities are calibrated.	Free
`anthropic/claude-haiku-4-5`, also as `google/claude-haiku-4-5` and the Bedrock `aws/...claude-haiku-4-5...` profiles	One structured-output call; the model reports its own probabilities.	Billed at the model rate
`google-ai/gemini-3.8-flash`, `google/gemini-3.8-flash`	One structured-output call; the model reports its own probabilities.	Billed at the model rate
`zai/glm-5.3-flash`	One forced tool call; the model reports its own probabilities.	Billed at the model rate
`openai/gpt-5.6-luna`, also as `azure/gpt-5.6-luna`	One structured-output call; the model reports its own probabilities.	Billed at the model rate
`groq/openai/gpt-oss-20b`, `groq/openai/gpt-oss-120b`, `groq/openai/gpt-oss-safeguard-20b`, `groq/qwen/qwen3.8-27b`	One structured-output call; the model reports its own probabilities.	Billed at the model rate

The table lists model families. Every offering of these models, including regional and reseller variants, is in Supported models. Chat models return the same fields with their own probabilities, which express the model’s estimate and are not calibrated, so thresholds tuned on one model do not transfer to another. For emulated classification, reasoning is set to the minimum the model allows. OpenAI Decisions accepts text or arrays of user messages with input_text and inline base64 input_image parts in state. Hosted image URLs, file IDs, and non-user roles are rejected. Content parts must be nested inside user messages; bare content parts and tool items are rejected rather than serialized as text. Other objects and arrays are serialized as text. OpenAI can return {"type": "refusal"} under an individual question key; handle refusals before reading scored fields. Any other model returns 400.

Quick start

curl -X POST https://my.orq.ai/v3/router/classify \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-latest",
    "state": "The package arrived two days late and the box was damaged, but support refunded me right away.",
    "questions": {
      "is_complaint": {
        "type": "noul",
        "instructions": "Does the customer report a problem with their order?",
        "criteria": {
          "true": "A problem with the order is described",
          "false": "No problem is described"
        }
      },
      "topic": {
        "type": "choice",
        "instructions": "What is the main topic of the message?",
        "criteria": {
          "shipping": "Delivery timing or packaging",
          "billing": "Charges, refunds or invoices",
          "other": null
        }
      },
      "satisfaction": {
        "type": "score",
        "instructions": "How satisfied is the customer overall?",
        "criteria": ["Unhappy", "Neutral", "Satisfied"]
      }
    }
  }'

import { Orq } from "@orq-ai/node";

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

const result = await orq.router.classify.create({
  model: "typesafe/jev-latest",
  state:
    "The package arrived two days late and the box was damaged, but support refunded me right away.",
  questions: {
    is_complaint: {
      type: "noul",
      instructions: "Does the customer report a problem with their order?",
      criteria: {
        true: "A problem with the order is described",
        false: "No problem is described",
      },
    },
    topic: {
      type: "choice",
      instructions: "What is the main topic of the message?",
      criteria: {
        shipping: "Delivery timing or packaging",
        billing: "Charges, refunds or invoices",
        other: null,
      },
    },
    satisfaction: {
      type: "score",
      instructions: "How satisfied is the customer overall?",
      criteria: ["Unhappy", "Neutral", "Satisfied"],
    },
  },
});

console.log(result.answers);
console.log(result.usage);

from orq_ai_sdk import Orq
import os

orq = Orq(api_key=os.environ.get("ORQ_API_KEY", ""))

result = orq.router.classify.create(
    model="typesafe/jev-latest",
    state="The package arrived two days late and the box was damaged, but support refunded me right away.",
    questions={
        "is_complaint": {
            "type": "noul",
            "instructions": "Does the customer report a problem with their order?",
            "criteria": {
                "true": "A problem with the order is described",
                "false": "No problem is described",
            },
        },
        "topic": {
            "type": "choice",
            "instructions": "What is the main topic of the message?",
            "criteria": {
                "shipping": "Delivery timing or packaging",
                "billing": "Charges, refunds or invoices",
                "other": None,
            },
        },
        "satisfaction": {
            "type": "score",
            "instructions": "How satisfied is the customer overall?",
            "criteria": ["Unhappy", "Neutral", "Satisfied"],
        },
    },
)

print(result.answers)
print(result.usage)

Request

Field	Type	Required	Description
`model`	string	Yes	One of the supported models.
`state`	string, object or array	Yes	The content to classify. Objects and ordinary arrays are serialized as JSON. Native OpenAI also accepts user-message arrays with text and inline images.
`questions`	object	Yes	Maps each question key to its definition. The response uses the same keys in `answers`.
`name`	string	No	Name shown on the trace. A default name is used when omitted.
`metadata`	object	No	Key-value pairs attached to the trace, for filtering later.
`fallbacks`	array	No	Up to 10 ordered fallback models, each with a `model` ID. Every model must support classification and pass access checks. Inline-image requests require native OpenAI fallbacks.
`retry`	object	No	Retry configuration for this request: `count` (1 to 5) and `on_codes`, the status codes that trigger a retry.
`identity`	object	No	Attributes the request to an end user, like the other gateway endpoints: the body identity takes precedence over `X-ORQ-IDENTITY-ID` and the API-key owner. See Request Metadata.

Each question has a type and instructions, which can be a string, object, or array. The shape of criteria depends on the question type.

Question types

`noul`

Returns the probability that the statement in instructions is true for state. The probability is calibrated on typesafe/jev-latest and model-reported on chat models. The optional criteria object can define what counts as true and false.

JSON

{
  "type": "noul",
  "instructions": "Does the customer report a problem with their order?",
  "criteria": {
    "true": "A problem with the order is described",
    "false": "No problem is described"
  }
}

`choice`

Selects one option from a rubric. The required criteria object maps each option name to a description. Set a description to null when the option name is enough for the model to interpret it.

JSON

{
  "type": "choice",
  "instructions": "What is the main topic of the message?",
  "criteria": {
    "shipping": "Delivery timing or packaging",
    "billing": "Charges, refunds or invoices",
    "other": null
  }
}

`score`

Returns a position on an ordered scale. Set criteria to an array with at least two level descriptions, ordered from lowest to highest. The answer index refers to this array.

JSON

{
  "type": "score",
  "instructions": "How satisfied is the customer overall?",
  "criteria": ["Unhappy", "Neutral", "Satisfied"]
}

Response

Native providers return their own confidence and score. Emulated classification uses one structured-output call. OpenAI Decisions returns a probability-weighted score and preserves its own confidence. The fields below describe these provider differences.

JSON

{
  "model": "typesafe/jev-latest",
  "answers": {
    "is_complaint": { "type": "noul", "noul": 0.97 },
    "topic": {
      "type": "choice",
      "choice": "shipping",
      "probabilities": { "shipping": 0.79, "billing": 0.2, "other": 0.01 },
      "confidence": 0.68
    },
    "satisfaction": {
      "type": "score",
      "score": 1.41,
      "legend": { "0": "Unhappy", "1": "Neutral", "2": "Satisfied" },
      "probabilities": { "0": 0.03, "1": 0.52, "2": 0.45 },
      "confidence": 0.28
    }
  },
  "usage": {
    "input_tokens": 412,
    "output_tokens": 0,
    "input_cost": 0.000017304,
    "output_cost": 0,
    "total_cost": 0.000017304
  },
  "telemetry": {
    "trace_id": "4f2294c4bd55372a354be496871aa917",
    "span_id": "a354be496871aa91"
  }
}

Field	Description
`model`	The requested ID of the model that answered, including a fallback model when one was used.
`answers`	One entry for each question key. Each entry repeats the question `type`.
`answers.<key>.noul`	`noul` only. Probability in the range `[0, 1]` that the statement holds.
`answers.<key>.choice`	`choice` only. The selected option name.
`answers.<key>.score`	`score` only. Position on the scale, not an index. On emulated chat models and OpenAI Decisions it is the weighted index: each level index multiplied by that level’s probability, summed, so a three-level answer lands on a fraction such as `1.42` for the distribution above. `typesafe/jev-latest` returns its own score instead, which is why that answer shows `1.41` beside a distribution whose weighted index is `1.42`.
`answers.<key>.type`	`noul`, `choice`, `score`, or `refusal`. Refusals contain no scored fields.
`answers.<key>.legend`	`score` only. Maps each level index to its description in the `criteria` array.
`answers.<key>.probabilities`	`choice` and `score`. Probability for each option name or level index.
`answers.<key>.confidence`	`choice` and `score`. How sure the model is of the answer it selected. On emulated chat models it is the largest value in `probabilities`, so it carries no information beyond them. `typesafe/jev-latest` returns its own calibrated value instead, which can sit below the largest probability: in the example above, `0.68` against `0.79` for the `choice` answer and `0.28` against `0.52` for the `score` answer.
`usage.input_tokens`	Total input tokens, including cached tokens.
`usage.input_tokens_details`	Optional provider-reported `cached_tokens` and `cache_write_tokens`. OpenAI Decisions does not charge for these tokens.
`usage.output_tokens`	Output tokens. Free for native classify providers, billed at the model rate for emulated chat models.
`usage.input_cost`	Cost in USD of the input tokens. Present when billing was computed.
`usage.output_cost`	Cost in USD of the output tokens. `0` for native classify providers. Present when billing was computed.
`usage.total_cost`	Total cost in USD. This follows the same format as the Responses API `usage` fields.
`telemetry.trace_id` / `telemetry.span_id`	Identifiers of the trace and root span recorded for the request. The same values are returned in the `x-orq-trace-id` and `x-orq-trace-span-id` headers.

The response includes optional telemetry. Read x-orq-trace-id and x-orq-trace-span-id from the response headers when older SDKs or deployments omit it. The handler sets those once the request is traced, so a request rejected before that point carries neither: authentication and authorization (401, and 403 for a missing classify permission or a model that is not enabled for the workspace or shared with the project), plan and budget limits (429), and request-body validation (the 400 for a malformed body, the 422 for an invalid request). Everything rejected after tracing carries them, including the 400 for a model that does not support classify. The telemetry object itself is optional and returned by builds newer than some deployments run, so fall back to the headers when it is absent. Emulated chat models return the same scored fields, but the numbers do not mean the same thing: their probabilities are the model’s own estimates and are not calibrated, and their confidence is simply the largest of them. Compare choice and score across models, not confidence. See the Create Classify API reference for the full request and response schema, including the fields accepted alongside the ones above.

Fallbacks, retries and identity

Use the same options on /decisions and /classify:

{
  "model": "openai/gpt-6-luna",
  "state": "The customer loves the product.",
  "questions": {
    "positive": { "type": "noul", "instructions": "Is the sentiment positive?" }
  },
  "fallbacks": [{ "model": "openai/gpt-5.6-luna" }],
  "retry": { "count": 2, "on_codes": [429, 502, 503, 504] },
  "identity": { "id": "customer-demo", "display_name": "Sample customer" }
}

retry.count is the number of retries after the first attempt, from 1 to 5. Retries happen only for status codes in on_codes; omitting retry disables gateway retries. The gateway honors Retry-After or waits one second when it is absent. After retries are exhausted, it tries the next fallback. A request accepts at most 10 fallbacks. The response reports the successful model and that model’s costs. A chat fallback pays the chat model’s input and output rates. For inline-image requests, every fallback must support native OpenAI image classification; incompatible chains are rejected with 422 before a provider call. An inaccessible fallback stops the remaining fallback chain. Session keys must allow every requested model under their factory policy.

Enforcement during the Beta

Enforced on every request:

What	Effect
Authentication	A missing or invalid key is rejected with `401`.
The `classify` permission	A key without it is rejected with `403`. The standard gateway key preset grants it.
Model access	The model must be enabled for the workspace or shared with the project, otherwise the request is rejected with `403`; it must also support classify, otherwise the request is rejected with `400`.
Plan rate limits and budgets	The request counts toward both, and a rejection returns `429` exactly as on other endpoints. See Rate limits and quotas.
Tracing, usage, and cost	The request is traced and billed, and the response reports `usage`; `telemetry` is optional.
Trace masking	Masks configured through workspace plugins apply to the stored trace. On chat models, the instructions that drive the structured answer are always scrubbed from the model span.
Request-level `retry`	Retries each model for matching `on_codes` before moving to its fallback.
Request-level `fallbacks`	Tries models in the supplied order when the previous model fails. Every model must support classify and pass access checks. A refusal is a successful answer and does not trigger fallback.
Identity	Body `identity.id`, then `x-orq-identity-id`, then the API-key owner identity determine trace attribution. Body identity details are published for upsert through the standard gateway identity middleware.

Not applied during the Beta:

PII plugins. state and instructions reach the provider exactly as sent, even when a redaction plugin is configured for traffic that would otherwise match.
Guardrails and evaluators. They do not run, so a matching guardrail rule cannot block a Classify request.
Routing rules. A rule does not rewrite the model, add fallbacks, or serve from cache.
Request-level load_balancer, timeout, cache, plugins, and guardrails. They are not part of this contract. Unknown body fields are ignored rather than rejected, so sending them has no effect and returns no error.

Pricing and limits

Model	Input	Output	Limits
`typesafe/jev-latest`	$0.042 per 1M tokens	Free	64k context window, and `state` plus the longest question must fit within 32k tokens
OpenAI Decisions	$0.10 per million input tokens;$ 0.20 above 272K input tokens. EU rates include a 10% premium	Free, including cache reads and writes	Only `gpt-6-luna`
Emulated chat models	The model’s own rate	The model’s own rate	The model’s limits from the Model Garden. The structured answer adds a few hundred output tokens per request

Errors

Status	Cause
`400`	Malformed JSON body, an invalid retry configuration, an empty fallback model, more than 10 fallbacks, or a model is not a supported model.
`401`	The API key is missing, invalid, or revoked.
`403`	The key is valid but lacks the `classify` permission, or the model is not enabled for the workspace or shared with the project.
`422`	The JSON is valid, but the classification structure is not. For example, a `choice` question has no `criteria`, or a `score` question has fewer than two levels, or an image request has an incompatible fallback.
`429`	A plan rate limit or a budget limit was reached before the provider was called. See Rate limits and quotas.
`429` / `529`	The upstream provider reached a rate limit or is overloaded. The response keeps the upstream status and `Retry-After` header. Retry after the specified delay.
`500`	An internal model-resolution error occurred. Internal infrastructure details are logged without being returned in the response.

Overview

APIs

MCP Portal

Routing

Security & Privacy

Model Capabilities

Server Tools

Common Scenarios

Overview

Use cases

Supported models

Quick start

Request

Question types

`noul`

`choice`

`score`

Response

Fallbacks, retries and identity

Enforcement during the Beta

Pricing and limits

Errors

​Overview

​Use cases

​Supported models

​Quick start

​Request

​Question types

​noul

​choice

​score

​Response

​Fallbacks, retries and identity

​Enforcement during the Beta

​Pricing and limits

​Errors

Overview

Use cases

Supported models

Quick start

Request

Question types

`noul`

`choice`

`score`

Response

Fallbacks, retries and identity

Enforcement during the Beta

Pricing and limits

Errors