TypeSafe API

HTTP evaluation endpoint

The request body has three top-level fields. state is required and may be a string, object, or array of text. model is required; docs examples use jev-latest. questions is a map of typed Question objects. You choose each key. The matching answer returns under the same id. The key is not sent to the underlying model and is not used in inference.

A minimal Noul looks like {"state": "Help! My payouts have been failing for 3 days.", "model": "jev-latest", "questions": {"is_urgent": {"type": "noul", "instructions": "Does this convey urgency?"}}}. Choice adds a criteria map of option name to description. Score adds an ordered criteria array of levels. All three share type and instructions; each adds its own criteria shape.

Get an API key from https://console.typesafe.ai/settings/keys. If you call HTTP directly, handle 429 with retry-after. Rate limits on Jev 1.13 are 250,000 tokens per second and 1,200 requests per minute, and they can change without notice. The SDKs retry with backoff by default. Listing models is GET /v1/models with the same Bearer token.

Official SDKs

Python: pip install typesafe-sdk. Import TypeSafeClient from typesafe_sdk. With TypeSafeClient() as client: client.system_one(state, questions). Constructors such as Noul, Choice, and Score live in the package so you do not hand-write the JSON type field. The default model is jev-latest. Python 3.10 or newer is required.

JavaScript: npm install @typesafe-ai/sdk. Import { TypeSafeClient } from "@typesafe-ai/sdk". The client talks to the same endpoint. Runtime is Node.js 20+. The repo is https://github.com/typesafe-ai/typesafe-sdk-js. Both SDKs expose models.list() for the alias catalog.

The playground at https://console.typesafe.ai/playground is a logged-in console, not a public embed. Paste text as state, add a Noul such as "Does this message express urgency?", then mix more questions in one call. It is the fastest way to feel parallel evaluation before you wire production keys.

A first curl

curl -X POST https://api.typesafe.ai/v1/systemone with Authorization: Bearer $TYPESAFE_API_KEY and Content-Type: application/json. Body: state as a Stripe-connect failure message, model jev-latest, questions.urgency as type noul with instructions "Does this message express urgency?". That is the quickstart sample. Add a Choice named department with billing / technical / sales criteria, and a Score named frustration with ordered levels, without a second round trip.

When something fails, read jaggedness before you add more prose to instructions. Literal reading wants the exact condition in instructions and criteria. Math wants counting in code. Generation wants a different model. The API will still return a typed payload if you ask Jev to write a paragraph via chained Choice; it will be slow and poor. Use regex or a generative model to propose options, then let Jev pick.

Cloudflare Workers AI lists typesafe/jev as a catalog name. That is a third-party listing, not a replacement for api.typesafe.ai. Steam has no Jev app. Keep keys on TypeSafe's console and treat community SDKs on Awesome Jev as unofficial unless they track the github.com/typesafe-ai org.

Errors, retries, and IDs

429 Too Many Requests is the documented response when you exceed tokens per second or requests per minute. Honor retry-after. The official SDKs already back off. If you wrap HTTP yourself, do not hammer the endpoint on 429; you will sit in the same limit window.

Question IDs are for your traces. They never enter inference. You can generate item_0 through item_n in a loop and still get one Noul each. Keep those keys unique inside a request. Reusing a key silently overwrites the question in the map.

Authorization is a Bearer TypeSafe API key from the dashboard. There is no cookie session on api.typesafe.ai. Rotate keys in the console, not by emailing this wiki. The playground login wall is separate: it is a browser console, not an alternate HTTP API.

Copy the quickstart curl once, then delete it from your repo in favor of the SDK. The SDK owns retries and typed constructors. Raw HTTP is for languages without an official client. Either path still sends Bearer keys and the same JSON body to POST /v1/systemone.

GET /v1/models lists aliases your account may send. It may omit jev-1.13.0 even while that ID works in POST /v1/systemone. Do not treat the list as the allowlist for versioned IDs. Treat it as the alias catalog and keep the versioned ID in your own config.

Never commit TYPESAFE_API_KEY. Rotate it in the dashboard if it leaks. contact@jevai.wiki is the wrong inbox for a leaked secret — use TypeSafe's own channels.

Python 3.10 and Node.js 20 are the documented floors. Older runtimes are outside the official clients.