Calling the TypeSafe API from an agent: request shape, errors, retries and version pinning

Goal

Make a first correct call, handle the documented failure statuses, and keep results reproducible across model releases.

Prerequisites

An API key from the vendor console (early access at the time of writing), exported as TYPESAFE_API_KEY, which both official SDKs read by default. Python: pip install typesafe-sdk or uv add typesafe-sdk. JavaScript (Node.js 20 or newer): npm install @typesafe-ai/sdk. Direct HTTP works without an SDK.

Steps

1. Build the request: POST https://api.typesafe.ai/v1/systemone with Authorization: Bearer <key> and a JSON body with state (string, object or array), model (jev-latest or a versioned ID such as jev-1.13.0) and questions, a map from a key you choose to a typed question (type of noul, choice or score, instructions, and criteria as the type requires).
2. Read the response: model (the versioned ID that answered), answers under the same keys (a noul value; or choice, probabilities and confidence; or score, legend, probabilities and confidence) and usage with input_tokens and output_tokens. In the Python SDK the same answers are reachable as response.nouls[...], response.choices[...] and response.scores[...].
3. Handle errors by status: 401 means a missing or invalid key; 422 means the body failed validation and the body names the field; 429 means a rate limit was exceeded; 529 means the service is overloaded. The reference says to retry 429 and 529 with exponential backoff, never immediately.
4. If you use the Python SDK, know its defaults: a RetryPolicy with two retries, initial backoff 0.5 s up to 5 s with jitter, retryable statuses 408, 429 and 5xx, respect_retry_after on, and a 30 s timeout; override it when the agent's own deadline is shorter.
5. Stay within the documented budgets: 64k tokens per request, 32k for state plus the longest question, at most 255 Choice options and 10 Score levels. Exceeding them is a 422, not a truncated answer.
6. Pin the model once thresholds are tuned: aliases move on release; GET /v1/models lists the aliases your account can send, and versioned IDs are accepted whether or not they appear there.
7. For a coding agent, install the vendor's skill (<coding-agent> plugin marketplace add typesafe-ai/skills and <coding-agent> plugin install typesafe@typesafe-ai for the coding agent, npx skills add typesafe-ai/skills --skill typesafe-ai elsewhere) and update it before use; the vendor attributes invented request or response fields to a stale skill.

Expected result

A request that validates first time, a client that backs off on 429 and 529 without hammering the endpoint, and logs that name the versioned model behind every decision.

Limits and test basis

Everything above is the vendor's documentation as of September 2026; rate limits are stated to change without notice during early access, so treat 429 as expected rather than exceptional. No latency or accuracy measurement is claimed.