# Jev API

> Hosted API for Jev, TypeSafe AI's System One model. Send a state and typed questions to one endpoint; get back Noul (yes/no probability), Choice (one option plus a probability for every option), or Score (a position on your scale). This site is an independent API service, not TypeSafe's own console.

## Docs

- [Jev API Docs](https://jev-api.org/docs): endpoint, authentication, request body, question types, response, limits, errors, differences from TypeSafe's API
- [Quickstart](https://jev-api.org/docs#quickstart): cURL, JavaScript, and Python examples
- [Pricing](https://jev-api.org/pricing): credit plans; 1 credit per successful call

## API contract

- Endpoint: POST https://jev-api.org/api/v1/decisions
- Auth: Authorization: Bearer <key>. Create keys at https://jev-api.org/dashboard/api-keys. Keep the key server-side.
- Models: GET https://jev-api.org/api/v1/models. Send model "jev-1.13" ("jev-latest" is an alias). Versioned ids such as "jev-1.13.0" return 422.
- Body: { "model", "state", "questions" }
  - state: string, JSON object, or array of text; up to 60,000 characters
  - questions: map of 1 to 6 lowercase snake_case ids; the id is only a label, the question goes in "instructions" (text, 1 to 2,000 characters)
- noul: needs "instructions". Answer: { "type": "noul", "noul": <0..1> }
- choice: needs "instructions" and "criteria", an object of 2 to 8 snake_case option ids mapped to descriptions (up to 300 characters). Answer: "choice", "probabilities" for every option, "confidence"
- score: needs "instructions" and "criteria", an array of 2 to 10 level descriptions, lowest first. Answer: "score", "legend", "probabilities", "confidence"
- Response: { "model": "jev-1.13", "answers": { ...keyed by your ids }, "usage": { "input_tokens", "output_tokens" }, "credits_used": 1 }
- Errors: 401 missing or rejected key; 402 not enough credits; 422 invalid body (the message names the field); 429 rate limited, retry later; 502 upstream returned no answers (no credit used)
- Billing: 1 credit per successful call, whatever the number of questions; validation errors and upstream failures are free. There are no free credits — the cheapest way to try is the smallest one-time top-up on https://jev-api.org/pricing; one-time credits do not expire.
- No streaming and no chat-completions path.

## TypeSafe-compatible API contract

- Endpoint: POST https://jev-api.org/v1/systemone — accepts the same body TypeSafe AI's api.typesafe.ai/v1/systemone takes: { "model", "state", "questions" }.
- Models list: GET https://jev-api.org/v1/models (no auth). The TypeSafe SDK's client.models.list() reads it.
- Accepted model ids: jev-latest, jev-preview, jev-1.13, jev-1.13.0, typesafe/jev-1.13.
- state: string, JSON object, or array; 1 to 250,000 serialized characters.
- questions: map of 1 to 256 ids (any non-empty string up to 128 characters; no snake_case requirement).
- instructions: a non-blank string OR a non-null object/array.
- noul: criteria optional, a plain object if present. choice: criteria object with 2 to 255 options; option values may be string, object, array, or null. score: criteria array of 2 to 10 items (non-blank strings or objects/arrays).
- Response: { "model": "jev-1.13.0", "answers": { ... }, "usage": { "input_tokens", "output_tokens" } } — the exact shape the official TypeSafe SDKs parse.
- Errors: { "detail": <message>, "error": { "message", "type", "code?" } }; 401 missing key, 422 invalid or model-rejected body, 429 rate limited, 402 not enough credits, 502 upstream failure (no credit used).
- SDK setup: pip install typesafe-sdk, then TypeSafeClient(api_key=<jev-api.org key>, base_url="https://jev-api.org") — or env TYPESAFE_API_KEY + TYPESAFE_BASE_URL=https://jev-api.org. JS: new TypeSafeClient({ apiKey, baseURL: "https://jev-api.org" }) from @typesafe-ai/sdk. jev-mcp: JEV_PROVIDER=compatible, JEV_API_BASE_URL=https://jev-api.org/v1/systemone, JEV_API_KEY=<key>.
- Token limits per request: 64k tokens total; 32k for state plus the longest question.
- Billing is the same as /api/v1/decisions: 1 credit per successful call; failures are free.

## Example

POST https://jev-api.org/api/v1/decisions
{"model":"jev-1.13","state":"I was charged twice for my subscription.","questions":{"refund":{"type":"noul","instructions":"Is the customer asking for money back?"}}}

## Guides

- [What is Jev](https://jev-api.org/what-is-jev): the model, its maker, the three question types, and its limits
- [Jev models](https://jev-api.org/jev-models): every model id and alias, price, rate limits, and which ids each endpoint accepts
- [Is Jev free](https://jev-api.org/is-jev-free): pricing, free credits, and ways to try
- [Jev Python](https://jev-api.org/jev-python): official SDK setup, first call, async, and errors
- [Jev MCP](https://jev-api.org/jev-mcp): the community MCP server with 12 typed judgment tools
- [Jev on GitHub](https://jev-api.org/jev-github): official SDKs and community clients
- [Jev use cases](https://jev-api.org/use-cases): eight request bodies you can run today

## Optional

- [Home](https://jev-api.org/): examples, limits, FAQ
- [TypeSafe AI](https://typesafe.ai): the company that builds and serves Jev