API reference

This page is the complete reference for the systemone endpoint, field-for-field with the official API docs (verified 2026-09-22). The official SDK types are generated from the same contract.

Endpoint & auth

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

One endpoint. Every question type and every judgment goes through it.

Request body

Field	Type	Notes
model	string	jev-latest / jev-preview / jev-1.13.0
state	string | object | array	The context; objects/arrays are serialized per official rules
questions	object	Named question map, values below

Common fields per question:

Field	Type	Notes
type	"choice" | "score" | "noul"	See Capabilities
instructions	string	The question, in natural language
criteria	per type	Choice: option map (≤255); Score: ordered levels (2–10); Noul: optional {true, false}

Size limits (official): ≤ 64k tokens per request; state + the longest single question ≤ 32k tokens.

One request, all three question types

{
  "model": "jev-latest",
  "state": "Hi, my Stripe integration keeps failing for 3 days. Please refund my subscription.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this",
      "criteria": { "billing": "Payment or subscription issues", "technical": "Bugs or integration problems" }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated the customer appears",
      "criteria": ["Calm", "Frustrated but civil", "Very angry"]
    },
    "asks_refund": {
      "type": "noul",
      "instructions": "The customer explicitly requests a refund"
    }
  }
}

Response body

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "probabilities": { "technical": 0.85, "billing": 0.15 },
      "confidence": 0.78
    },
    "frustration": {
      "type": "score",
      "score": 1.0,
      "legend": { "0": "Calm", "1": "Frustrated but civil", "2": "Very angry" },
      "probabilities": { "0": 0.0, "1": 1.0, "2": 0.0 },
      "confidence": 1.0
    },
    "asks_refund": { "type": "noul", "noul": 0.91 }
  },
  "usage": { "input_tokens": 412, "output_tokens": 67 }
}

• answers keys mirror the request’s questions one-for-one
• Noul has no confidence; values above are illustrative in shape
• usage is the sole billing basis (output is free)

Errors & retries

Status	Meaning	Handling
401	Auth failed	Check the key and Authorization header; do not retry
422	Validation failed	Fix the payload against the tables above; do not retry
429	Rate limited	Exponential backoff; official limits 250k tok/s + 1200 req/min (subject to change)
529	Overloaded	Exponential backoff; circuit-break on sustained failure

Our advice

Both official SDKs ship a configurable RetryPolicy (attempts, retryable statuses, backoff). With raw HTTP, back off 429/529 on a 1s → 2s → 4s curve with jitter, and set an overall request timeout.

Clients

• Official Python SDK: pip install typesafe-sdk → Python guide
• Official JS/TS SDK: npm i @typesafe-ai/sdk → JavaScript guide
• Agent skill (for Claude Code, Codex, etc.): typesafe-ai/skills in Ecosystem

Related pages

Get started · Limitations · Use cases