# Jein

> Jein is a hosted API that answers named, typed questions about a state (a string, object or array) with the open Laya model: each question comes back as a typed decision with probabilities. It takes the same requests as Jev (TypeSafe), so the TypeSafe SDKs work with a Jein base URL and API key. Free preview: a free account with 500,000 free input tokens a month; no credit card.

- Base URL: https://app.jein.dev (the service root; the SDKs append `/v1/systemone` and `/v1/models`)
- Authentication: `Authorization: Bearer <API key>`. Create a key at https://app.jein.dev/app/keys. Read the base URL from `TYPESAFE_BASE_URL` and the key from `TYPESAFE_API_KEY`; never hard-code, print or commit the key.
- SDKs: Python `typesafe-sdk==0.7.1` (`client.system_one(...)`); JavaScript `@typesafe-ai/sdk@0.6.0` on Node.js 20+ (`client.systemOne({...})`). Plain HTTP works too.
- Errors: every non-200 has the header `x-jein-error-code`; the body is `{"detail": "..."}`, or FastAPI-style `detail[]` entries with `loc` for 422 validation errors.

## Request

`POST https://app.jein.dev/v1/systemone` with a JSON body: a `model`, the `state` (a string, object or array), and up to 32 named `questions`.

```json
{
  "model": "laya-latest",
  "state": "Hi, I was billed twice for March. Please refund the duplicate.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {"billing": "Payment issues", "technical": "Bugs", "sales": "Sales questions"}
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this?",
      "criteria": ["Low", "Medium", "High"]
    },
    "wants_refund": {"type": "noul", "instructions": "The customer asks for a refund"}
  }
}
```

## Response

Each question comes back under its own name in `answers`. `model` names the checkpoint that ran; `usage.input_tokens` is what the request used of the free allowance. Illustrative response, recorded from a real run of the request above; your numbers will differ.

```json
{
  "model": "laya-0.3.20",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.8725,
      "probabilities": {
        "billing": 0.9736,
        "technical": 0.0147,
        "sales": 0.0117
      }
    },
    "urgency": {
      "type": "score",
      "score": 1.1095,
      "confidence": 0.1797,
      "legend": {
        "0": "Low",
        "1": "Medium",
        "2": "High"
      },
      "probabilities": {
        "0": 0.1311,
        "1": 0.6282,
        "2": 0.2406
      }
    },
    "wants_refund": {
      "type": "noul",
      "noul": 0.8793
    }
  },
  "usage": {
    "input_tokens": 44,
    "output_tokens": 0
  }
}
```

## Question types

- `choice`: `criteria` is an object of option name → description. The answer has `choice` (the selected option), `probabilities` for every option, and `confidence`.
- `score`: `criteria` is an ordered array of levels. The answer has `score` (the probability-weighted level index from 0; it can fall between levels), `legend`, `probabilities` and `confidence`.
- `noul`: `instructions` is a statement. The answer has `noul`, the probability that the statement is true, and no confidence.
- `confidence` is 1 minus the normalized entropy of `probabilities`: 1.0 when all probability sits on one option, 0.0 when all options are equally likely. It is not the top probability.

## Models

`GET /v1/models` lists every accepted name. Use `laya-latest`: English state goes to `laya-0.3.20`, other languages to `laya-multilingual-0.3.20`. Pin `laya-0.3.20` to stay on English, or `laya-multilingual` for non-English. `jev-latest` (the SDK default), `jev-preview` and `jev-1.13.0` are accepted as aliases of `laya-latest`.

## Limits

- At most 32 questions per request, and 3500 processed tokens per request on the English model (questions × the longest per-question sequence); the multilingual model's cap is reported in the `request_too_large` error.
- Each question's state room is about 437–478 tokens in English and 1975–2014 multilingual. Jein never truncates: a state that does not fit is rejected with 422 `state_too_long`, whose text gives the room.
- Rate limit per account: up to 40 requests at once, then 4 per second (240 per minute). Requests rejected as invalid count too. Over the limit: 429 `rate_limited` with `Retry-After`.
- Up to 4 requests running at once per account (429 `too_many_inflight`).
- 500,000 free input tokens a month per account; then 402 until the UTC month resets.
- Workers busy or starting: 529 with `Retry-After`. The SDKs retry 429 and 529; set an overall deadline.

## Docs

- [Quickstart](https://app.jein.dev/docs/quickstart): first request in curl, Python and JavaScript
- [Models](https://app.jein.dev/docs/models): model names, language routing and per-model limits
- [Migrating from Jev](https://app.jein.dev/docs/migrating): checklist for existing Jev code
- [Limits](https://app.jein.dev/docs/limits): every limit and its error code
- [Errors](https://app.jein.dev/docs/errors): every `x-jein-error-code`
- [OpenAPI](https://app.jein.dev/openapi.yaml): the machine-readable contract

Support: laya@snblago.com