# Jev API on TokenRa

Model ID: `jev-latest`
Get an API key: https://tokenra.io/register?utm_source=llms-agent&utm_medium=model-llms
Updated: 2026-10-30

> Jev is TypeSafe AI's decision model. It does not write text: you send a state (the text or JSON to judge) plus named questions, and every answer comes back typed, with probabilities and a confidence value.

- Provider: TypeSafe AI
- Type: Decision model
- Input: Text or JSON state
- Output: Typed answers
- Latency: Under 1 s

## Pricing

Rates in the TokenRa console when this file was last updated, in US dollars for the default group. The live price list is authoritative: https://tokenra.io/pricing (JSON: https://tokenra.io/api/pricing).

- `jev-latest`: $0.042 per 1M tokens, input and output at the same rate

## Capabilities & endpoints

One synchronous endpoint. Jev does not use the chat format, so the OpenAI and Anthropic SDKs do not apply; send plain HTTPS requests. Calling `jev-latest` on `/v1/chat/completions` returns an error.

- `POST https://tokenra.io/v1/decisions`: Send a `state` and named `questions`; every answer comes back typed. Auth: `Authorization: Bearer`.

## Example

Set `TOKENRA_API_KEY` to your API key first. The docs page has the same example in Python, JavaScript and Java.

```bash
curl https://tokenra.io/v1/decisions \
  -H "Authorization: Bearer $TOKENRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Help! My payouts have been failing for 3 days.",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "Does this message convey urgency?",
        "criteria": {
          "true": "Explicitly time-sensitive",
          "false": "No urgency expressed"
        }
      },
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {
          "billing": "Payments, invoicing, refunds",
          "technical": "Bugs, outages, integrations",
          "sales": "Pricing, upgrades, new accounts"
        }
      },
      "frustration": {
        "type": "score",
        "instructions": "How frustrated is the customer?",
        "criteria": [
          "Calm",
          "Frustrated",
          "Very angry"
        ]
      }
    }
  }'
```

## Question types

Each question has a name you choose, a `type`, `instructions` and, depending on the type, `criteria`. All three types were answered on 2026-10-23.

| type | criteria | Answer fields |
| --- | --- | --- |
| `noul` | Optional. Object with exactly the keys `"true"` and `"false"`, each describing when it applies. | `noul`: probability (0-1) that the answer is true. |
| `choice` | Required. Object that maps each option key to its description, at least one option. | `choice` (the most likely key), `probabilities` per option, `confidence`. |
| `score` | Required. Array of at least two level descriptions, from the lowest to the highest. | `score` (0 to number of levels - 1, can be fractional), `legend`, `probabilities` per level, `confidence`. |

## Request parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | `jev-latest`. The response reports the version that answered, for example `typesafe/jev-1.14-20261014` or `jev-1.14.0`. |
| `state` | string / object / array | Yes | What to judge, shared by every question: text, or JSON such as a ticket or a record. Chinese text was tested. |
| `questions` | object | Yes | Your question names mapped to question objects; at least one. Each answer comes back under the same name. |
| `questions.*.type` | string | Yes | `noul`, `choice` or `score`. |
| `questions.*.instructions` | string / object / array | Yes | The question itself. |
| `questions.*.criteria` | object / array | No | Depends on the type, see the table above. Required for `choice` and `score`. |
| `stream` | boolean | No | Not supported. Leave it out; `true` returns an error. |

## Response format

**Response from the example request (2026-10-24)**

```json
{
  "model": "typesafe/jev-1.14-20261014",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {
        "billing": 0.88,
        "technical": 0.12,
        "sales": 0
      },
      "confidence": 0.82
    },
    "frustration": {
      "type": "score",
      "score": 1.02,
      "legend": {
        "0": "Calm",
        "1": "Frustrated",
        "2": "Very angry"
      },
      "probabilities": {
        "0": 0,
        "1": 0.98,
        "2": 0.02
      },
      "confidence": 0.97
    },
    "is_urgent": {"type": "noul", "noul": 0.95}
  },
  "usage": {"input_tokens": 427, "output_tokens": 73},
  "id": "gen-dec-1792772733-dG0LU2uG8E83JEMaXCmh",
  "provider": "TypeSafe"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `model` | string | The Jev version that answered. |
| `answers.<name>.type` | string | The question type. |
| `answers.<name>.noul` | number | noul only: probability that the answer is true. |
| `answers.<name>.choice` | string | choice only: the most likely option key. |
| `answers.<name>.score` | number | score only: expected level, from 0 to the number of levels - 1. |
| `answers.<name>.probabilities` | object | choice and score: probability of each option or level; they add up to 1. |
| `answers.<name>.legend` | object | score only: level index to your level description. |
| `answers.<name>.confidence` | number | choice and score: confidence from 0 to 1. Use it to route unsure cases to a person. |
| `usage` | object | `input_tokens` and `output_tokens` used for billing. |
| `id / provider` | string | Request ID and serving provider, when the upstream includes them. |

The answers are keyed by your question names; do not rely on their order. In testing they came back sorted by name, not in request order.

During testing the upstream answered in two shapes: with `model` like `typesafe/jev-1.14-20261014` plus `id` and `provider`, or with `model` like `jev-1.14.0` and no extra fields. `answers` and `usage` were the same in both, so read only the fields you need.

## Errors & limits

### Request validation

Invalid requests return HTTP `400` with `error.code` `invalid_request` and one of these messages. Do not retry them; fix the request.

| Message | Cause |
| --- | --- |
| `questions must not be empty` | `questions` is missing or empty. |
| `state must be a string, object or array` | `state` is missing, for example when a chat `messages` body is sent instead. |
| `unsupported question type; expected noul, choice or score` | Unknown `type`. |
| `choice criteria must be a nonempty object of choices` | A choice question without options. |
| `score criteria must contain at least two string levels` | A score question with fewer than two levels. |
| `noul criteria must contain only true and false string descriptions` | Other keys in noul criteria. |
| `decisions do not support streaming` | `stream: true` was sent. |

### Common errors

| HTTP | error.code | Meaning | What to do |
| --- | --- | --- | --- |
| `401` | - | Missing, wrong or deleted API key. The message is `Invalid token`. | Check the `Authorization: Bearer` header and the key in the console. |
| `400` | - | The body is not valid JSON. | Fix the JSON and send `Content-Type: application/json`. |
| `403` | `insufficient_user_quota` | Your balance or plan quota is used up. | Top up in the console, then retry. |
| `503` | `model_not_found` | Unknown model ID, or no channel serves it for your group. | Check the ID in the model list or with `GET /v1/models`. |
| `429` | - | Too many requests. | Back off exponentially and retry. |
| `5xx` | - | The upstream provider failed or timed out. | Retry a few times; keep the request id if it persists. |

### Limits and notes

- Requests took 0.35 to 1 second in testing.
- Billing: input and output tokens are both charged at $0.042 per 1M tokens (checked 2026-10-24). A test request with 358 input and 60 output tokens was charged 9 quota units, that is $0.000018. Question definitions count as input tokens. Rates can change; the live rate is on the Model Square.
- A one-sentence state with the three example questions used 427 input and 73 output tokens; question definitions count as input.

## More

- [Jev API docs page](https://tokenra.io/docs/jev-latest.html): parameter tables and code samples in cURL, Python, JavaScript and Java
- [Jev overview and pricing page](https://tokenra.io/models/jev-api.html)
- [API basics](https://tokenra.io/docs/common.html): base URL, authentication, errors, retries
- [Quickstart](https://tokenra.io/docs/quickstart.html): create a key and send a first request
- [All models](https://tokenra.io/docs/models.html): every model ID
- [Chinese version of this guide](https://tokenra.io/zh/docs/jev-latest/llms.txt)
- [Site index for agents](https://tokenra.io/llms.txt)

---

Canonical version of this document: https://tokenra.io/docs/jev-latest/llms.txt