TypeSafe Jev API Reference: Endpoints, Schemas, and SDKs

The TypeSafe Jev API exposes a single synchronous evaluation endpoint (POST https://api.typesafe.ai/v1/systemone) engineered to evaluate unstructured application state against typed questions in a single parallel forward pass. Unlike autoregressive LLMs, Jev does not stream tokens, execute tools, or accept chat conversational histories. Authenticated via Authorization: Bearer <TYPESAFE_API_KEY>, requests accept a state payload up to 32,000 tokens and a questions dictionary containing typed definitions (choice, score, or noul), returning calibrated probabilities and selections in 70ms to 500ms according to TypeSafe specifications.

Endpoint Specification

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

All requests require an API key generated from console.typesafe.ai. Official documentation specifies HTTP 401 Unauthorized for authentication failure. In production edge proxies, requests omitting the Authorization header entirely may receive HTTP 403 Forbidden, while invalid or revoked keys return HTTP 401 Unauthorized.

Request Body Schema

The root request body accepts three primary fields:

Field	Type	Required	Description
`model`	string	Optional	Model identifier. Defaults to `"jev-latest"`. Explicit pinned version: `"jev-1.13.0"`.
`state`	string \| object \| array	Required	Unstructured context payload (raw text, parsed JSON, or string array). Total request budget is 64,000 tokens; `state` combined with the longest question cannot exceed 32,000 tokens.
`questions`	object	Required	Map of question keys to typed primitive definitions. Evaluated concurrently.

{
  "model": "jev-latest",
  "state": {
    "account_tier": "enterprise",
    "incident_description": "Production database latency spiked to 4200ms following migration script 084. Connection pool saturated."
  },
  "questions": {
    "routing_target": {
      "type": "choice",
      "instructions": "Determine the primary engineering owner for this incident.",
      "options": ["database_reliability", "platform_infra", "core_backend", "networking"],
      "criteria": {
        "database_reliability": "Connection pool, query degradation, schema migrations, lock contention.",
        "platform_infra": "Kubernetes pod restarts, CPU throttle, hardware failures.",
        "core_backend": "Application code exceptions, third-party API timeouts.",
        "networking": "DNS resolution errors, VPC peering packet drops."
      }
    },
    "severity_level": {
      "type": "score",
      "instructions": "Grade incident severity from minor disruption to total service outage.",
      "levels": [
        "Negligible impact or internal-only alert",
        "Minor latency elevation within SLA buffers",
        "Degraded performance affecting user transactions",
        "Critical production outage causing continuous data loss"
      ]
    },
    "requires_page": {
      "type": "noul",
      "instructions": "Should an on-call engineer be paged immediately?",
      "criteria": {
        "true": "Active user transactions are failing or latency violates enterprise SLA.",
        "false": "The issue is contained, self-healing, or non-production."
      }
    }
  }
}

Primitive Question Schemas

Jev accepts three typed primitives. It rejects open-ended string generation questions.

1. `choice` (Multiclass Selection)

Selects a single option from a discrete set of up to 255 predefined values.

type: "choice" (required)
instructions: string (required) — Clarifies the evaluation objective.
options: array of strings (required) — List of valid categorical outputs.
criteria: object (optional) — Key-value dictionary providing bounding definitions for each option. Supplying criteria significantly tightens calibration on borderline decisions.

2. `score` (Ordinal Rubric)

Evaluates state against an ordered scale from 2 to 10 distinct levels.

type: "score" (required)
instructions: string (required) — Defines the evaluation criterion.
levels: array of strings (required) — 2 to 10 descriptions ordered strictly from lowest to highest. Jev computes an expected value across this ordinal continuum.

3. `noul` (Boolean Probability)

Evaluates whether a declarative statement is true or false.

type: "noul" (required)
instructions: string (required) — Binary evaluation statement.
criteria: object (optional) — Keyed by "true" and "false" to anchor boundary definitions.

Response Body Schema

Jev returns a JSON object containing the evaluated answers, usage metrics, and calibrated confidence levels.

{
  "id": "sys1_req_01j8k7m9n3p2r",
  "model": "jev-1.13.0",
  "created": 1726819200,
  "answers": {
    "routing_target": {
      "choice": "database_reliability",
      "confidence": 0.942,
      "probabilities": {
        "database_reliability": 0.942,
        "platform_infra": 0.038,
        "core_backend": 0.016,
        "networking": 0.004
      }
    },
    "severity_level": {
      "score": 3.14,
      "confidence": 0.887,
      "probabilities": [0.005, 0.048, 0.752, 0.195]
    },
    "requires_page": {
      "type": "noul",
      "noul": 0.963
    }
  },
  "usage": {
    "input_tokens": 184,
    "output_tokens": 3,
    "latency_ms": 112
  }
}

Error Codes and Handling

HTTP Status	Trigger Condition	Recommended Workaround
`400 Bad Request`	Question schema is invalid (unknown primitive type, missing instructions, option count outside 2–255), or request body is malformed/missing `state`.	Validate question payloads against primitive schemas before submission.
`401 Unauthorized`	Invalid, expired, or revoked API key in `Authorization` header.	Verify and regenerate API key in `console.typesafe.ai`.
`403 Forbidden`	Missing `Authorization` header at edge gateway or blocked organization account.	Ensure `Authorization: Bearer <key>` header is attached to all outbound requests.
`413 Payload Too Large`	Context limit exceeded (total request exceeds 64,000 tokens, or `state` plus longest question exceeds 32,000 tokens).	Truncate or pre-filter context state in application code before API submission.
`429 Too Many Requests`	Concurrency ceiling exceeded (dynamic early-access limits of 1,200 req/min or 250,000 tokens/sec).	Implement exponential backoff or request quota expansion via TypeSafe console.
`500 Internal Server Error`	Transient inference cluster failure or execution timeout.	Retry request once with randomized exponential backoff.

Official SDKs

TypeSafe maintains official client libraries for Python and TypeScript that wrap the /v1/systemone endpoint with native type definitions.

Python SDK (`typesafe-sdk`)

pip install typesafe-sdk

import os
from typesafe_sdk import TypeSafeClient, Choice, Score, Noul

client = TypeSafeClient(api_key=os.environ["TYPESAFE_API_KEY"])

response = client.system_one(
    model="jev-latest",
    state={"query": "return item within 30 days unopened"},
    questions={
        "action": Choice(
            instructions="Determine return eligibility",
            criteria={
                "approve": "Meets return policy guidelines",
                "reject": "Violates return policy window",
                "manual_review": "Borderline or ambiguous request"
            }
        ),
        "is_fraud_risk": Noul(
            instructions="Does this request indicate return fraud?"
        )
    }
)

# Access typed result collections
print(response.choices["action"].choice)
print(response.choices["action"].confidence)
print(response.nouls["is_fraud_risk"].noul)

TypeScript SDK (`@typesafe-ai/sdk`)

npm install @typesafe-ai/sdk

import { choice, score, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient({
  apiKey: process.env.TYPESAFE_API_KEY!,
});

const response = await client.systemOne({
  model: "jev-latest",
  state: { ticket: "Customer reports card charged twice on checkout" },
  questions: {
    category: choice("Classify support category", {
      billing: "Payment or subscription issue",
      technical: "System or platform bug",
      account: "Credentials or security",
    }),
    urgency: score("Assess support urgency", [
      "low",
      "normal",
      "urgent",
      "critical",
    ]),
  },
});

console.log(response.answers.category.choice);
console.log(response.answers.urgency.score);

Rate Limits and Service Boundaries

TypeSafe operates Jev 1.13 under dynamic early-access concurrency envelopes:

Context Window: 64,000 tokens total per request budget. The state payload combined with the longest single question definition cannot exceed 32,000 tokens.
Throughput Envelopes: 1,200 requests per minute and 250,000 tokens per second per organization during early access (quotas are dynamic and subject to infrastructure demand).

Endpoint Specification

Request Body Schema

Primitive Question Schemas

1. choice (Multiclass Selection)

2. score (Ordinal Rubric)

3. noul (Boolean Probability)

Response Body Schema

Error Codes and Handling

Official SDKs

Python SDK (typesafe-sdk)

TypeScript SDK (@typesafe-ai/sdk)