Reference

The whole API on one page

One endpoint, three question types, four error codes. Jev’s surface area is small enough to hold in your head — which is arguably the most underrated thing about it.

Endpoint#

HTTP

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <API_KEY>
Content-Type: application/json

One evaluation endpoint. All models are served from it; the model field selects which. The only other documented route is GET /v1/models. There is no streaming, batch or async job endpoint.

Request body#

Field	Type	Required	Notes
`state`	`string` \| `object` \| `array`	Yes	The content to evaluate. Text only.
`model`	`string`	Yes	e.g. `jev-latest`, or a versioned ID like `jev-1.13.0`.
`questions`	`map<string, Question>`	Yes	Keys are yours. Answers return under the same keys. The key is not sent to the model and plays no part in inference.

There are no other documented top-level fields — no temperature, max_tokens, stream, system or metadata.

Question types#

Noul — <code>type: "noul"</code>#

Field	Required	Shape
`instructions`	Yes	`string` \| `object` \| `array`
`criteria`	No	`{ "true": string, "false": string }` — the only optional criteria of the three

Choice — <code>type: "choice"</code>#

Field	Required	Shape
`instructions`	Yes	`string` \| `object` \| `array`
`criteria`	Yes	`map<string, string \| null>` — option to rubric description; `null` when an option needs no extra detail. Up to 255 options.

Score — <code>type: "score"</code>#

Field	Required	Shape
`instructions`	Yes	`string` \| `object` \| `array`
`criteria`	Yes	`array` of level descriptions, low end first. At least 2, at most 10.

request

{
  "state": "Hi, I've been trying to connect my Stripe account for 3 days and it keeps failing. I'm losing sales. Please help ASAP.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this",
      "criteria": {
        "billing": "Payment or subscription issues",
        "technical": "Bugs or integration problems",
        "sales": "Pricing or account questions"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated the customer appears",
      "criteria": [
        "Calm, just stating facts",
        "Frustrated but civil",
        "Very angry, strong language"
      ]
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "The message conveys urgency or time-sensitivity"
    }
  }
}

Response body#

Field	Type	Notes
`model`	`string`	The versioned ID that actually answered. Log it.
`answers`	`map<string, Answer>`	Keyed by your question IDs.
`usage`	`object`	`input_tokens`, `output_tokens`. Only input is charged.

Answer type	Fields
`noul`	`type`, `noul` — the yes/no answer from 0 (no) to 1 (yes). No `confidence`.
`choice`	`type`, `choice` (highest-probability option), `probabilities` (floats summing to 1), `confidence`
`score`	`type`, `score` (probability-weighted; can land between levels), `legend`, `probabilities` (string level-index keys), `confidence`

response

{
  "model": "jev-latest",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "probabilities": { "billing": 0.08, "technical": 0.85, "sales": 0.07 },
      "confidence": 0.82
    },
    "frustration": {
      "type": "score",
      "score": 1.6,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0.05, "1": 0.3, "2": 0.65 },
      "confidence": 0.78
    },
    "is_urgent": {
      "type": "noul",
      "noul": 0.92
    }
  },
  "usage": { "input_tokens": 312, "output_tokens": 48 }
}

Models#

Name	Kind	Resolves to
`jev-1.13.0`	Versioned model ID	itself
`jev-latest`	Alias — most recent stable release; the SDK default	`jev-1.13.0`
`jev-preview`	Alias — most recent release, official or not	`jev-1.13.0` (no preview build right now)

Jev is not fine-tuned or LoRA-adapted with customer data — the same weights serve every account, and there is no fine-tuning API.

Limits and pricing#

	jev-1.13.0
Price	$42 / Btok — $0.042 / MTok input. Output tokens free.
Rate limits	250,000 tokens/second, 1,200 requests/minute. Either exceeded returns `429`.
Context	64k tokens per request; 32k for `state` plus the longest single question.
Questions per request	No documented cap — bounded by tokens only.
Input modality	Text only. String, JSON object, or array of text values.
Language	English primary; others accepted with lower accuracy.
Latency	70–500ms (launch blog only — not in the docs, no SLA, no percentiles).

Errors#

Status	Meaning	Retry?
`401`	Missing or invalid API key	No
`422`	Body failed validation; the response names the offending field	No
`429`	Rate limited	Yes — honour `retry-after`
`529`	Overloaded (non-standard code)	Yes — exponential backoff

The SDKs also define 400, 403 and 404 errors, which do not appear in the HTTP API's documented table. The error body's JSON schema is not published.

SDKs#

	Python	JavaScript / TypeScript
Install	`pip install typesafe-sdk`	`npm install @typesafe-ai/sdk`
Runtime	Python ≥ 3.10	Node ≥ 20
Client	`TypeSafeClient`, `AsyncTypeSafeClient`	`TypeSafeClient`
Method	`client.system_one(state=…, questions=…)`	`client.systemOne({ state, questions })`
Question builders	`Choice`, `Noul`, `Score` (classes)	`choice()`, `noul()`, `score()` (functions)
Reading answers	`response.answers[id]`, or `.nouls` / `.choices` / `.scores`	`response.answers.<id>` (types inferred)

Python constant	Default
`API_KEY_ENV`	`TYPESAFE_API_KEY`
`BASE_URL_ENV`	`TYPESAFE_BASE_URL`
`DEFAULT_MODEL_ENV`	`TYPESAFE_DEFAULT_MODEL`
`DEFAULT_BASE_URL`	`https://api.typesafe.ai`
`DEFAULT_MODEL`	`jev-latest`
`DEFAULT_TIMEOUT`	`10.0` seconds per HTTP operation

There is also an official agent skill for Claude Code, Codex and similar environments — claude plugin marketplace add typesafe-ai/skills then claude plugin install typesafe@typesafe-ai, or npx skills add typesafe-ai/skills --skill typesafe-ai.

Not documented anywhere#

A free tier, trial credits, plan tiers or spend caps. typesafe.ai/pricing returns 404; the Models table is the only pricing artefact.
The formula behind confidence.
The error response body schema.
Streaming, batching or async endpoints.
Any fine-tuning or custom-model API.
Latency percentiles, an SLA, or regional data.
A paper, preprint or algorithm spec for RLCD.
Any expansion of the word “Noul”.

Start the tutorials Official docs ↗