The field to get right first
criteria is a different shape for each question type
Every model in our System One models directory answers the same three kinds of question, and each kind describes its permitted answers differently. The field is called criteria every time, so the shape is the thing that changes. The forms below are from TypeSafe's API reference for Jev; the limits and prices later on are Jev's alone.
| Question type | criteria must be | Is criteria required? |
|---|---|---|
| choice | An object mapping each option name to a description of when it applies, up to 255 options | criteria is required for choice |
| score | An ordered array of level descriptions, between two and ten levels | criteria is required for score |
| noul, the yes or no type | An object with a true key and a false key | criteria is optional for noul |
A widely circulated list of gotchas says noul takes no criteria. The documentation allows it and makes it optional. System One Harness, the decision loop we build and open-source under Apache 2.0, omits it on the questions it generates and permits it on the guard questions an operator writes.
Package names
typesafe-sdk means something different on PyPI and on npm
The same name resolves to a different package on each registry. This is what each showed on 28 September 2026.
| Registry | What typesafe-sdk resolves to | The package TypeSafe documents |
|---|---|---|
| PyPI | Version 0.7.2, described as the Python SDK for TypeSafe AI API | typesafe-sdk, the same name |
| npm | Version 0.0.0, with no description and a maintainer handle that does not appear in TypeSafe's documentation | @typesafe-ai/sdk, version 0.6.0, described as the TypeScript SDK for the TypeSafe API |
So an instruction that is correct in Python is wrong in JavaScript. Check the registry, not the name.
Limits
Two token budgets, and the second one is easy to miss
TypeSafe documents two limits for Jev 1.13: 64k tokens per request, and 32k tokens for the state plus the longest question.
The first covers everything you send. The second is the one that catches people, because it does not count all your questions. It counts the state together with whichever single question is longest. Adding a short question leaves it where it was. Adding a question longer than your current longest raises it.
The published rate limits are 250,000 tokens per second and 1,200 requests per minute. Input is priced at $0.042 per million tokens and output is not charged.
Errors
Retry 429 and 529 with exponential backoff
The documentation is direct about this. On a 429 Too Many Requests or a 529 Overloaded, retry with exponential backoff rather than retrying immediately, and the official SDKs do it for you.
The pair matters if you are calling the endpoint yourself. 429 is the familiar one. 529 means the service is overloaded rather than that you sent too much, and code written to handle only 429 will pass it through as a failure. System One Harness retries both, with exponential backoff, on TypeSafe's guidance.
Where to reach the model
Two ways in, and only one of them needs a client
TypeSafe serves Jev at /v1/systemone, and everything above describes what a client posting there has to get right. Jev is not the only option: our System One models directory lists four models with published evidence of typed, non-generative decisions, three of them open-weight and self-hosted under Apache 2.0. Their limits differ from Jev's, and inclusion there describes the decision interface rather than equal capability.
The other way is not to write a client at all. System One Harness is the decision loop for these models, built and open-sourced by HarnessRouter under Apache 2.0, and everything above is already handled inside it. Run it yourself from the repository, or send a task to HarnessRouter with harness ID systemone, where it is one of fifteen harnesses behind a single contract.
Integration advice for this ecosystem goes stale quickly. Availability, endpoints and limits have all moved since the first week of guides, so re-check any list against the current documentation before acting on it, including this one.
Not checked
Four warnings we could not verify
We could not confirm the following, so they are recorded as claims rather than repeated as facts.
- That a third-party gateway renames the noul type to boolean and returns a probability field in its place. We did not verify this against that gateway.
- That the model rejects calls made to a chat completions endpoint with an error naming it an evaluation model. TypeSafe's documentation describes the dedicated endpoint and does not mention this.
- Three billing behaviours attributed to a third-party platform: a card required before any request succeeds, free credits counting down from the first request, and monthly free credits ending once credits are purchased. We verified none of them. Billing terms also change.
- That one JavaScript framework needs a specific minimum version for its evaluate helper. We could not establish which version introduced it.
Getting it right
The System One model integration checklist
If you are writing the client yourself, this is the shape that works. Post to TypeSafe at /v1/systemone. Send the state once, with every question beside it in the same request. Give each question a type and its instructions. Give a choice question an object of option names and descriptions, and a score question an ordered array of levels. Keep the state plus your longest question under 32k tokens, and the whole request under 64k. Retry 429 and 529 with exponential backoff.
If you would rather not maintain a client, none of the above is yours to get right. HarnessRouter runs System One as one of fifteen harnesses behind a single contract, selected per task by ID.
What the model returns, and how to read the probabilities on it, is in what is a System One model. The loop that turns those answers into finished work is a System One agent.
FAQ
Common questions
Why does my Jev request fail with a criteria error?
Check the shape against the question type. A choice question needs criteria as an object mapping option names to descriptions, and it is required. A score question needs criteria as an ordered array of two to ten level descriptions, and it is required. A noul question may omit criteria, and if you send it, TypeSafe documents it as an object with true and false keys.
Which typesafe-sdk package is the official one?
They are different packages. On PyPI, typesafe-sdk is version 0.7.2, described as the Python SDK for TypeSafe AI API. On npm, the same name resolves to version 0.0.0 with no description; the package TypeSafe documents for JavaScript is @typesafe-ai/sdk. Checked on 28 September 2026.
What are the Jev token limits?
Two of them. 64k tokens for the whole request, and 32k tokens for the state plus the single longest question. The second counts only one question, whichever is longest, so a short extra question leaves it unchanged while a question longer than your current longest raises it.
How should I handle rate limits?
Retry with exponential backoff on both 429 Too Many Requests and 529 Overloaded, which is what TypeSafe's documentation instructs and what its official SDKs already do. Code written for 429 alone will pass 529 through as a failure. The published limits are 250,000 tokens per second and 1,200 requests per minute.
Do I have to write a client to use Jev?
Only if you want one. TypeSafe serves Jev at /v1/systemone, and the checklist above is what a client posting there has to handle. The alternative is System One Harness, the decision loop HarnessRouter builds and open-sources under Apache 2.0, which already handles the question compiling, the confidence gate and the 429 and 529 retries. Run it from the repository yourself, or send a task to HarnessRouter with harness ID systemone and maintain none of it.
The same contract runs the rest of your work
System One is one of fifteen complete agent harnesses behind a single HarnessRouter contract. Once a decision loop is a task you send, so is everything else, and the harness becomes a request parameter rather than an architectural commitment.
Start building free