01 / Implementation

Jev API key, console access, and endpoints.

You can access Jev directly through the official TypeSafe API (api.typesafe.ai) or immediately through major provider platforms including OpenRouter, Vercel AI Gateway, and Cloudflare Workers AI.

Direct TypeSafe access uses a secret API key (TYPESAFE_API_KEY) managed in the TypeSafe Console (console.typesafe.ai/keys ↗). Provider routes require no TypeSafe account or key—they authenticate via your existing provider credentials and route to their respective Jev endpoints.

Key compatibility rule: Credentials are provider-specific. A TypeSafe API key works only at api.typesafe.ai, an OpenRouter key works only at openrouter.ai, and a Vercel key works only with Vercel AI Gateway. Furthermore, Jev is a System One decision engine, not a chat LLM: send state and typed questions to POST /v1/systemone, never chat completion prompts to conversational endpoints.
POSThttps://api.typesafe.ai/v1/systemoneDirect Endpoint

First Working Request (Official Quickstart)

If you have a TypeSafe API key, run this sample request from TypeSafe's official quickstart guide to evaluate Choice, Score, and Noul questions in a single round-trip:

cURL (TypeSafe Official Quickstart)
curl -X POST "https://api.typesafe.ai/v1/systemone" \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Hi, I'''ve been trying to connect my Stripe account for 3 days and the integration 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"
      }
    }
  }'

Documented response from TypeSafe's quickstart specification, showing typed answers, probability distributions, confidence scores, and token accounting:

Documented JSON Response (TypeSafe Quickstart)
{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "confidence": 0.78,
      "probabilities": {
        "technical": 0.85,
        "sales": 0.0,
        "billing": 0.15
      }
    },
    "frustration": {
      "type": "score",
      "score": 1.0,
      "confidence": 1.0,
      "legend": {
        "0": "Calm, just stating facts",
        "1": "Frustrated but civil",
        "2": "Very angry, strong language"
      },
      "probabilities": {
        "0": 0.0,
        "1": 1.0,
        "2": 0.0
      }
    },
    "is_urgent": {
      "type": "noul",
      "noul": 1.0
    }
  },
  "usage": {
    "input_tokens": 392,
    "output_tokens": 65
  }
}

Getting a Direct TypeSafe API Key

Direct TypeSafe API credentials and visual testing tools are centralized in the official web console:

01Sign in to TypeSafe Console: Navigate to console.typesafe.ai ↗ to sign in to your account.
02Generate your API key: Open the API Keys area at console.typesafe.ai/keys ↗. If key creation is available to your account, create a new secret key, store it securely, and export it into your development environment:
export TYPESAFE_API_KEY="ts_live_..."
03Interactive Playground: After logging in, you can test state strings and write Choice, Score, or Noul questions directly in the browser workbench at console.typesafe.ai/playground ↗ without writing code.
04Early-access capacity & custom limits: The service is operating in early access with dynamically adjusting rate limits as capacity expands and more users are admitted. Teams requiring higher or custom quota limits beyond defaults can contact sales@typesafe.ai. Developers who need immediate access can alternatively route through third-party provider platforms (OpenRouter, Vercel, Cloudflare).

Credential & Endpoint Matrix

Match your credentials to the exact endpoint and model string supported by each platform. Keys cannot be interchanged across providers:

Route / ProviderEndpoint URLRequired CredentialModel IdentifierContext BudgetStatus & Notes
TypeSafe Direct ↗https://api.typesafe.ai/v1/systemoneBearer $TYPESAFE_API_KEYjev-latest or jev-1.13.064k total / 32k state+QProduction · Lowest latency, official SDK default
OpenRouter (System One) →https://openrouter.ai/api/v1/systemoneBearer $OPENROUTER_API_KEYtypesafe/jev-1.13 or ~typesafe/jev-latest32k flatProduction · Instant access with OpenRouter credits
OpenRouter (Jev Router) →https://openrouter.ai/api/v1/chat/completionsBearer $OPENROUTER_API_KEYtypesafe/jev-router1M tokensChat Router · Dispatches completions to downstream LLMs
Vercel AI Gateway →https://ai-gateway.vercel.sh/typesafeBearer $AI_GATEWAY_API_KEYtypesafe-ai/jev32k flatProduction · Edge caching, AI SDK, unified Vercel bill
Cloudflare Workers AI →env.AI.run / Cloudflare RESTCloudflare API Token / Bindingtypesafe/jev32k flatProduction · Serverless edge execution on Cloudflare

SDK baseURL override: The official TypeSafe SDKs point to https://api.typesafe.ai by default, but can be redirected to OpenRouter by setting baseURL: "https://openrouter.ai/api" with an OpenRouter API key, or to Vercel by setting baseURL: "https://ai-gateway.vercel.sh/typesafe" with a Vercel gateway key.

Code Quickstarts

Choose your preferred client implementation. Each example queries parallel questions in a single round-trip:

TypeSafe Direct cURL

Endpoint: https://api.typesafe.ai/v1/systemone

Evaluate Choice and Noul primitives simultaneously over an application state string:

cURL (Direct TypeSafe)
curl -X POST "https://api.typesafe.ai/v1/systemone" \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Customer account balance: $450. Order amount: $120. Shipping to billing address: Yes. Card CVV matched: Yes. Velocity: 1 order in 7 days.",
    "questions": {
      "order_risk_tier": {
        "type": "choice",
        "instructions": "Evaluate order transaction risk level",
        "criteria": {
          "low": "Standard domestic order with verified CVV and shipping match",
          "medium": "Unusual shipping mismatch or minor velocity spike",
          "high": "High-risk signals or multiple failed payment attempts"
        }
      },
      "require_manual_review": {
        "type": "noul",
        "instructions": "This transaction requires manual underwriter review before fulfillment."
      }
    }
  }'

TypeScript SDK (@typesafe-ai/sdk)

npm install @typesafe-ai/sdk

Full TypeScript support with typed question schemas and inferred answer types. See the complete TypeScript SDK guide:

TypeScript (@typesafe-ai/sdk)
import { TypeSafeClient } from "@typesafe-ai/sdk";

// Reads process.env.TYPESAFE_API_KEY automatically
const client = new TypeSafeClient();

async function evaluateTicket() {
  const response = await client.systemOne({
    model: "jev-latest",
    state: "Account status: Active. Issue: API 429 rate limit exceeded. Usage: 10,000 req/min (Limit: 5,000 req/min). Plan: Growth.",
    questions: {
      is_abuse: {
        type: "noul",
        instructions: "The client is executing a deliberate denial-of-service pattern rather than legitimate surge load.",
      },
      action: {
        type: "choice",
        instructions: "Recommended immediate action",
        criteria: {
          temporary_block: "Malicious abuse or credential stuffing",
          offer_quota_increase: "Legitimate customer scaling beyond current quota",
          ignore: "Transitory spike within acceptable tolerance",
        },
      },
    },
  });

  const abuseProbability = response.answers.is_abuse.noul; // 0.0 to 1.0
  const recommendedAction = response.answers.action.choice;
  const confidence = response.answers.action.confidence;

  console.log({ abuseProbability, recommendedAction, confidence });
}

evaluateTicket();

Python SDK (typesafe_sdk)

pip install typesafe-sdk

Python client library supporting synchronous and asynchronous workflows with typed Choice, Score, and Noul classes:

Python (typesafe_sdk)
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

# Reads TYPESAFE_API_KEY from environment by default
client = TypeSafeClient()

response = client.system_one(
    model="jev-latest",
    state="Ticket: User reports error 500 when saving preferences. Browser: Chrome 128. Account tier: Enterprise. Service logs indicate timeout in user-prefs DB replica.",
    questions={
        "routing_queue": Choice(
            instructions="Select target escalation tier",
            criteria={
                "tier1_general": "Routine UI or configuration questions",
                "tier2_database": "Replica lag, storage errors, or DB timeout issues",
                "tier3_sre": "Widespread system outages or cluster failures",
                "account_executive": "Contractual disputes or enterprise renewal discussions",
            },
        ),
        "churn_risk": Score(
            instructions="Estimate account churn risk",
            criteria=[
                "No churn risk; routine issue",
                "Minor frustration",
                "High risk of contract cancellation",
            ],
        ),
        "is_urgent": Noul(
            instructions="The customer expresses active urgency or ongoing downtime",
        ),
    },
)

# Inspect calibrated answers
print("Selected Queue:", response.answers["routing_queue"].choice)
print("Confidence:", response.answers["routing_queue"].confidence)
print("Churn Score (0-2):", response.answers["churn_risk"].score)
print("Urgency Probability:", response.answers["is_urgent"].noul)

OpenRouter System One Route

Endpoint: https://openrouter.ai/api/v1/systemone

Call Jev using your OpenRouter API key without an official TypeSafe Console account:

cURL (OpenRouter System One Route)
curl -X POST "https://openrouter.ai/api/v1/systemone" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.13",
    "state": "Customer account balance: $450. Order amount: $120. Shipping to billing address: Yes. Card CVV matched: Yes. Velocity: 1 order in 7 days.",
    "questions": {
      "order_risk_tier": {
        "type": "choice",
        "instructions": "Evaluate order transaction risk level",
        "criteria": {
          "low": "Standard domestic order with verified CVV and shipping match",
          "medium": "Unusual shipping mismatch or minor velocity spike",
          "high": "High-risk signals or multiple failed payment attempts"
        }
      },
      "require_manual_review": {
        "type": "noul",
        "instructions": "This transaction requires manual underwriter review before fulfillment."
      }
    }
  }'

Rate Limits, Quotas & Context Budgets

•Throughput limits (100,000 tok/sec, 80 req/sec): TypeSafe officially documents default rate limits of 100,000 tokens per second and 80 requests per second. These limits are adjusting dynamically as new GPU capacity lands during early access. Enterprise accounts requiring custom quotas or dedicated throughput should contact sales@typesafe.ai.
•Context length (64,000 / 32,000 tokens): The combined token count of state plus all questions in a single request must not exceed 64,000 tokens. The tokens in state plus the single longest individual question must not exceed 32,000 tokens. (Provider routes such as OpenRouter, Vercel, and Cloudflare enforce a flat 32,000-token limit.)
•Output tokens are free: Jev pricing is billed strictly on input tokens ($0.042 per million input tokens, or $42 per billion tokens). Output tokens carry zero charge across TypeSafe direct and provider routes. See pricing breakdowns & calculations.
•Discover account models: You can inspect active model aliases on your account by sending a GET request to https://api.typesafe.ai/v1/models:
List Account Models (GET /v1/models)
curl https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

Documented response schema: TypeSafe documents that GET /v1/models returns a models array listing the active aliases available to the account. Each entry includes:
• name (string): The model identifier or alias accepted by the model parameter (e.g. jev-latest, jev-preview).
• description (string): What the model is for.
• release_date (string): When the model or alias was released.
Pinned version identifiers such as jev-1.13.0 are accepted by the API whether or not they appear in the list.

Troubleshooting Common Access Errors

401Unauthorized: Missing or invalid API key. Ensure your header is formatted exactly as Authorization: Bearer $TYPESAFE_API_KEY with no leading spaces. Also verify you are not sending an OpenRouter or Vercel key to api.typesafe.ai.
422Unprocessable Entity: The request body failed JSON schema validation. Verify that required root keys (model, state, questions) are present, and that each question specifies a valid type and instructions. Choice questions require a non-empty criteria map (max 255 options); Score questions require an ordered array of 2 to 10 level descriptions.
429Too Many Requests: You exceeded the 100k tokens/sec or 80 req/sec limit. The official Python (typesafe_sdk) and TypeScript (@typesafe-ai/sdk) SDKs automatically retry with exponential backoff and respect the Retry-After header. If writing custom HTTP clients, implement exponential backoff.
529Overloaded: The TypeSafe inference cluster is experiencing a transient capacity spike during early access. Back off and retry after a brief delay.
400Bad Request on Chat Endpoints: Occurs when sending typesafe/jev-1.13 to POST /api/v1/chat/completions. Jev is a decision model, not a conversational LLM. For chat completions routing, switch your model identifier to typesafe/jev-router.

Frequently Asked Questions

QCan I use Jev immediately without a TypeSafe Console account?
Yes. If you do not have an active TypeSafe key, you can call Jev immediately through OpenRouter (typesafe/jev-1.13), Vercel AI Gateway (typesafe-ai/jev), or Cloudflare Workers AI (typesafe/jev) using existing account balances on those platforms.
QWhere do I create or rotate my TypeSafe API key?
Sign in to console.typesafe.ai ↗ and navigate to console.typesafe.ai/keys ↗. You can generate multiple named keys and revoke compromised keys instantly.
QDoes my TypeSafe API key work against OpenRouter or Vercel?
No. Each platform authenticates with its own proprietary key. You do not need a TypeSafe API key to call Jev through OpenRouter or Vercel, and your TypeSafe API key cannot be used on provider endpoints.
QWhich model string should I specify in the API request?
On direct TypeSafe (api.typesafe.ai), use "jev-latest" (recommended rolling stable alias) or pinned version "jev-1.13.0". On OpenRouter, use "typesafe/jev-1.13". On Vercel, use "typesafe-ai/jev". On Cloudflare, use "typesafe/jev".
QHow can I use Jev for LLM evaluation or LangSmith?
TypeSafe Jev can be used as an online evaluator in LangSmith using your direct TYPESAFE_API_KEY. Check our guide to LangSmith evaluators & Jev-as-a-Judge.