---
title: "Evaluate state against typed questions"
method: POST
path: "/v1/evaluate"
tags: ["Gateway"]
---

# Evaluate state against typed questions

`POST /v1/evaluate`

## Request

- Base URL: `https://api.roar-ai.com`
- URL: `https://api.roar-ai.com/v1/evaluate`
- Auth: HTTP bearer

Evaluation models: shared `state` plus typed `questions` in, calibrated probabilities out. A `boolean` answers with a probability, a `choice` with the selected option and a probability per option, a `score` with an interpolated value and a probability per rung. Several questions are answered in one round trip against the same state. NOT an OpenAI-compatible shape — there is no `messages` and no completion. Billed on input tokens. Requires `inference`.

## Request body

- EvaluateRequest
  - `model` string, required
  - `state` union, required: What is being judged. A string, an object or an array — passed through as given.
    - string
    - object
    - unknown[]
      - unknown
  - `questions` object, required: Each key names an answer in the response. `criteria` differs per type: an optional true/false gloss for `boolean`, a record of option name to description for `choice` (two or more), an ordered array lowest-to-highest for `score` (two or more).

## Response `200`

An answer per question key

## Other responses

- `400`: Malformed question, or a model that is not an evaluation model
- `401`: Missing or invalid key

---

[API](https://skmtc.dev/roar-ai/apis/roar-ai-api.md) · [All operations](https://skmtc.dev/roar-ai/apis/roar-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/roar-ai/apis/roar-ai-api/revisions/37e4d0d5a7fe?raw)