---
title: "Classify"
method: POST
path: "/v3/router/classify"
tags: ["Classify"]
---

# Classify

`POST /v3/router/classify`

**Beta.** Runs typed classification questions (`noul`, `choice`, `score`) against the native classify model `typesafe/jev-latest` or a chat model that supports classify. Chat models answer through one structured-output call and their probabilities are model-reported rather than calibrated. The request and response follow the TypeSafe classification contract; `model` in the response echoes the request and `usage` carries the computed cost like the Responses API. This endpoint currently does not apply PII plugins or guardrails.

## Request body

- object
  - `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 the model to use: the native classify model typesafe/jev-latest, or a chat model that supports classify.
  - `name` string — The name to display on the trace. If not specified, the default system name will be used.
  - `questions` object, required — Typed questions keyed by an identifier of your choice. Each answer is returned under the same key.
  - `retry` ClassifyRetryConfig
    - `count` integer, required — Number of retry attempts (1-5).
    - `on_codes` integer[], nullable, required — HTTP status codes that trigger retry logic.
  - `state` union, required — The content to evaluate. A string, an object or an array.
    - string
    - object
    - unknown[]
      - unknown

## Response `200`

Returns one answer per question.

- object
  - `answers` object, required — Answers keyed by the question identifiers from the request.
  - `model` string, required — The model ID from the request.
  - `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.
    - `output_cost` number, double — Cost (USD) of output tokens. 0 for typesafe/jev-latest. Present when billing was computed for this request.
    - `output_tokens` integer, required — The number of output tokens generated. Free for typesafe/jev-latest, billed at the model rate for 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 or missing model.
- `422` — The state or a question violates the classification contract.
- `429` — Rate limited by the provider.

## Changes

> 350 revisions in range; 136 not diffed.

- **2026-09-21** `8f82880fa08a` — 1 warning
  - removed the optional property `telemetry` from the response with the `200` status

[Change history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v3/router/classify/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/3c7d859558ee?raw)