API reference

Base URL and authentication

Use the main application origin followed by /v1, for example https://your-deployment.example.com/v1. Send a platform API key as Authorization: Bearer YOUR_API_KEY. Keys belong to an account and use that account’s credit balance. The documentation host is separate from the inference API.

POST /v1/systemone

Send Content-Type: application/json and an optional, client-generated Idempotency-Key. The request is ordinary JSON; there is no streaming response.

This page describes contract typesafe-2026-09-18. In typesafe-native mode, an explicit model keeps the validated request's original UTF-8 JSON text, including formatting, key order and extension fields. Observational response validation checks the result without rebuilding it. The errors and replay pages describe safety exceptions and older caches.

{
  "model": "jev-latest",
  "state": { "message": "I was charged twice for one order." },
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "Choose the reviewing team.",
      "criteria": { "billing": "Payments and refunds", "support": "Technical help" }
    },
    "urgency": {
      "type": "score",
      "instructions": "Evaluate urgency with the ordered rubric.",
      "criteria": ["Normal review", "Timely response", "Immediate human attention"]
    },
    "duplicate": {
      "type": "noul",
      "instructions": "Does the message report a duplicate charge?"
    }
  }
}

Save the body as request.json. This shell example makes a real request when supplied with your deployment and key:

curl "$SYSTEM_ONE_BASE_URL/systemone" \
  -H "Authorization: Bearer $SYSTEM_ONE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-order-001' \
  --data-binary @request.json

On Windows PowerShell, use curl.exe with PowerShell environment syntax, or use the SDK example. Generate a different idempotency key for each new logical operation; the literal key above is illustrative.

Request fields

Question and option names must contain non-whitespace characters and be no more than 128 characters long. Native request, question and Noul criteria extensions are preserved, subject to the size/depth bounds and the provider's validation. Descriptions may contain nested JSON. Nullable state, omitted/null instructions and nullable Noul criteria follow the official @typesafe-ai/sdk@0.6.0 declarations; an omitted state field is still invalid. Final acceptance belongs to the upstream. The project SDK 0.3.0 has stricter input validation; use native HTTP or the official client for these forms.

A supplied model overrides the deployment default. Omitting it inserts the default into the root JSON text without reserializing existing values. An alias can resolve differently over time; use a provider-supported fixed version when reproducibility matters. The model list is not a local allowlist for versioned names.

Numeric tokens such as 9007199254740993 and 1e-400 are preserved on the native transport, including when a default model is inserted. Duplicate object keys (also after escape decoding) and numbers outside the supported finite range are rejected. Playground constructs compact JSON directly from its editors with exact decimal values. Billing uses the parsed canonical request; idempotency compares exact numeric values so distinct high-precision inputs cannot share a cached answer.

Platform limits

Rate limits are shared across the account’s API keys and playground requests. All attempts reaching this account counter, including replays, consume rate-limit capacity. Deployments can change the rate with SYSTEM_ONE_RATE_LIMIT. A separate API authentication guard limits attempts per hashed IP to 600 per minute. These are platform bounds, not claims about every provider or Jev version.

Response

The following values illustrate the response shape; they are not a recorded model output:

{
  "model": "jev1.13.0",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.8, "support": 0.2 },
      "confidence": 0.6
    },
    "urgency": {
      "type": "score",
      "score": 1.5,
      "probabilities": { "0": 0.1, "1": 0.3, "2": 0.6 },
      "confidence": 0.3,
      "legend": { "0": "Normal review", "1": "Timely response", "2": "Immediate human attention" }
    },
    "duplicate": { "type": "noul", "noul": 0.8 }
  },
  "usage": { "input_tokens": 120, "output_tokens": 0 }
}

model reports the upstream's resolved name; the version and values above are illustrative. Native TypeSafe Choice requires type, choice, probabilities and confidence. Score requires type, score, probabilities, confidence and legend. Probability keys match the request, and the score matches the probability-weighted rubric within the validation tolerance. See primitives.

The TypeSafe response retains the same Fetch-visible JSON text, status and extension fields. Missing usage, token counts, warnings and rounding are not added; missing or null token counts remain unknown in the ledger. The reported zero above is an example of an actual field, not a default. A two-decimal Jev tolerance may be used to validate distributions without changing numbers or inserting rounding.

Successful bodies receive no platform billing, request_id or replayed fields. The provider may itself return those names; retain them as provider data and never use them for platform accounting. Platform credits and identifiers come from the response headers below.

The project SDK 0.3.0 converts Noul to { type: 'boolean', probability } and token usage to camelCase, may add its own defaults, and does not expose every raw field. Use Fetch or the official client's withResponse() for the HTTP headers; its requestId convenience value is the TypeSafe tracking ID, not the platform ledger ID. Read X-Request-Id explicitly.

Response headers

Responses use Cache-Control: no-store. The explicit server-side idempotency cache has separate 24-hour semantics.

Only Content-Type, Retry-After and documented tracking/rate headers are forwarded. Provider cookies, redirects, authorization and arbitrary headers are not. Platform security/CORS headers remain authoritative. OpenRouter uses explicit /decisions adaptation and returns openrouter-adapted; it does not promise TypeSafe byte fidelity. Old caches use legacy-cache as described on the replay page.

GET /v1/models

Send a platform Bearer key. The gateway queries the configured TypeSafe provider with the operator credential and returns the real { "models": [...] } body, including each model's name, description, release_date and any extensions. It does not fabricate an OpenAI-style { "data": [...] } list or serve anonymous capability metadata.

curl "$SYSTEM_ONE_BASE_URL/models" \
  -H "Authorization: Bearer $SYSTEM_ONE_API_KEY" \
  -H 'Accept: application/json'

This authenticated request reads the live list without reserving credits or creating a decision record. It has a separate 60-request/account/minute guard. Missing provider configuration returns 503; an OpenRouter deployment returns 501 model_listing_not_supported. A valid version ID need not appear in the list. Playground takes a model name directly and does not depend on this protected endpoint.

Other endpoints

Browser management endpoints use the existing Better Auth session, not a Bearer API key. Mutations require the exact configured application Origin. There are at most 20 active keys per account; key creation is limited to 10 requests per minute. Revoked or unknown keys cannot authenticate.

See errors for native upstream errors, stable classification headers and safe replacement exceptions. Read idempotency before enabling retries.