HTTP API: POST /v1/systemone and GET /v1/models

TL;DR POST https://api.typesafe.ai/v1/systemone with Authorization: Bearer <API_KEY>, Content-Type: application/json, and a body of {state, model, questions}. You get back {model, answers, usage} where answers is keyed by the question ids you chose. GET /v1/models lists the model names your key may send.

Endpoints

OpenAPI operationIds: systemone_v1_systemone_post, models_v1_v1_models_get (raw/site/openapi.json). See OpenAPI component schemas for every component schema.

Authentication

Get a key at https://console.typesafe.ai/keys (raw/docs/introduction__quickstart.md; changed 2026-09-21 — the quickstart previously linked https://console.typesafe.ai/settings/keys, and raw/docs/agent-skill.md already used /keys, so the two sources now agree). The SDKs read it from TYPESAFE_API_KEY; see TYPESAFE_* environment variables across SDKs.

Headers the official SDKs also send or read (raw/github/typesafe-sdk-python/src/typesafe_sdk/_core/constants.py, raw/github/typesafe-sdk-js/src/client.ts): request User-Agent: typesafe-sdk/<version>, Accept, X-TypeSafe-SDK, X-TypeSafe-Runtime, X-TypeSafe-Retry-Count; response x-typesafe-request-id (surfaced as request_id / requestId on errors), retry-after, retry-after-ms. None of these are documented as required in raw/docs/api.md.

Request body (SystemOneRequest)

state and the questions share one budget: 64k tokens per request, and 32k tokens for state plus the single longest question (raw/docs/models.md). See Models, aliases, pricing, rate limits, context.

Minimal example request (verbatim, raw/docs/api.md)

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?"
    }
  }
}

Question types

A Question is one of three types, selected by its type field. All three share type and instructions; each adds its own criteria. The OpenAPI discriminator is type with mapping noul → NoulQuestion, choice → ChoiceQuestion, score → ScoreQuestion.

Common fields

Structured instructions (added to raw/docs/api.md on 2026-09-21)

instructions has always been typed string | object | array; the API reference now documents what the object form is for. "You can break up a long question that has extra context, or data it needs to reference, into a structured object. Put the question in one field and the data in the others, and refer to the data fields by name in backticks, the same way you point a question at a nested state value":

"instructions": {
  "potential_duplicate": {
    "name": "John Smith",
    "location": "Oakland, California",
    "last_employer": "Google"
  },
  "question": "Is the resume for the same person as `potential_duplicate`?"
}

No field name inside the object is reserved — you choose them. See Structured instructions, options, levels, criteria and How to build software with System One.

Noul (type: "noul")

A yes/no question. Returns the probability the answer is yes.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?",
      "criteria": {
        "true": "Explicitly time-sensitive",
        "false": "No urgency expressed"
      }
    }
  }
}

Choice (type: "choice")

Picks one option from a set you define. Returns the chosen option and the full probability distribution.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

Score (type: "score")

Rates the state along a rubric you define. Returns a probability-weighted value across your levels.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    }
  }
}

Response body (SystemOneResponse)

Answer types

Every answer carries a type matching its question. Choice and Score answers also carry a confidence between 0 and 1, derived from the answer's probability distribution (raw/docs/api.md). Discriminator mapping: noul → NoulAnswer, choice → ChoiceAnswer, score → ScoreAnswer.

Noul answer

A Noul answer carries no confidence field.

Choice answer

Score answer

Verbatim example response (raw/docs/api.md)

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 296, "output_tokens": 20 }
}

Choice answer (raw/docs/api.md):

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 },
      "confidence": 0.81
    }
  },
  "usage": { "input_tokens": 318, "output_tokens": 34 }
}

Score answer (raw/docs/api.md):

{
  "model": "jev-1.13.0",
  "answers": {
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 },
      "confidence": 0.92
    }
  },
  "usage": { "input_tokens": 304, "output_tokens": 18 }
}

All three examples were re-run upstream on 2026-09-21. Two observable changes for anyone who copied the old ones: the model field now shows the resolved version jev-1.13.0 rather than the jev-latest alias that was sent, and each example carries its own usage numbers instead of the placeholder {"input_tokens": 312, "output_tokens": 48} that all three shared before.

cURL example (verbatim, raw/docs/introduction__quickstart.md)

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
  {
    "state": "Hi, I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP.",
    "model": "jev-latest",
    "questions": {
      "urgency": {
        "type": "noul",
        "instructions": "Does this message express urgency?"
      }
    }
  }
EOF

Mixed-type request and response (verbatim, raw/docs/introduction__quickstart.md)

{
  "state": "Hi, I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this",
      "criteria": {
        "billing": "Payment or subscription issues",
        "technical": "Bugs or integration problems",
        "sales": "Pricing or account questions"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated the customer appears",
      "criteria": [
        "Calm, just stating facts",
        "Frustrated but civil",
        "Very angry, strong language"
      ]
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "The message conveys urgency or time-sensitivity"
    }
  }
}

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "confidence": 0.78,
      "probabilities": {
        "technical": 0.85,
        "sales": 0.0,
        "billing": 0.15
      }
    },
    "frustration": {
      "type": "score",
      "score": 1.0,
      "confidence": 1.0,
      "legend": {
        "0": "Calm, just stating facts",
        "1": "Frustrated but civil",
        "2": "Very angry, strong language"
      },
      "probabilities": {
        "0": 0.0,
        "1": 1.0,
        "2": 0.0
      }
    },
    "is_urgent": {
      "type": "noul",
      "noul": 1.0
    }
  },
  "usage": {
    "input_tokens": 392,
    "output_tokens": 65
  }
}

Superseded note. Until 2026-09-21 this quickstart response omitted probabilities on the Score answer, and this page flagged it as an abridged sample. The refreshed sample includes probabilities, so all three sources now agree the field is always present. The same refresh flipped department from billing (0.84) to technical (0.85) on a slightly reworded state — another reminder that documented answers are illustrations, not expected outputs.

GET /v1/models

Returns the names your account can send in the model field, with a description and release date for each. It currently lists the aliases. Versioned IDs such as jev-1.13.0 are accepted by the model field whether or not they appear in the list (raw/docs/models.md).

curl https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

Response (ModelMetadataList):

Example from the OpenAPI examples (raw/site/openapi.json):

{
  "models": [
    {
      "name": "jev-latest",
      "description": "General-purpose system one model.",
      "release_date": "2026-09-15"
    }
  ]
}

Errors

Errors use standard HTTP status codes with a JSON body describing what went wrong (raw/docs/api.md).

This list is not exhaustive; the SDK-level mapping incl. 400/403/404/408/5xx is in HTTP status codes, rate limits, retry semantics. The 422 body is {"detail": [ValidationError, ...]}; each entry has loc, msg, type, and optionally input and ctx. Full shape in OpenAPI component schemas. For the complete status → SDK exception → retry mapping see HTTP status codes, rate limits, retry semantics.

Handling rate limits

Verbatim guidance (raw/docs/api.md): "When you receive a 429 Too Many Requests or 529 Overloaded response, retry the request with exponential backoff instead of retrying immediately. Our client SDKs handle this automatically, so no extra handling is needed if you use one of our SDKs with its default retry policy."

Additional facts for direct HTTP callers:

• Limits are 250,000 tokens per second and 1,200 requests per minute; exceeding either returns 429 (raw/docs/models.md).
• The SDKs "honor the retry-after header when the response carries one" (raw/docs/models.md). The SDK implementations also read retry-after-ms, preferring it over retry-after (raw/github/typesafe-sdk-js/src/retry.ts, raw/github/typesafe-sdk-python/src/typesafe_sdk/_core/errors.py). If you implement your own client, read both.
• Reference backoff, matching the SDK defaults: initial 500 ms, doubling, capped at 5,000 ms, 25% jitter, 2 retries after the initial attempt; cap any honored server delay at 60,000 ms before falling back to backoff (raw/github/typesafe-sdk-js/src/retry.ts).
• Rate limits are stated to be "adjusting dynamically" and can change without notice; higher limits are on custom and enterprise plans via sales@typesafe.ai (raw/docs/models.md).

Source disagreements

Caveat on the OpenAPI column. raw/site/openapi.json is a 2026-09-17 snapshot: the 2026-09-21 refresh of api.typesafe.ai/openapi.json returned 503, so the machine-readable schema has not been re-checked against the prose changes made on 2026-09-21. Where the two disagree below, the prose is the newer statement.

Version notes

• OpenAPI document version 0.2.0, OpenAPI spec version 3.1.0 (raw/site/openapi.json).
• This is the v1 API. The preview endpoint POST /preview/evaluation is replaced by POST /v1/systemone; field names changed. See Migrating from /preview/evaluation to /v1/systemone.
• document is no longer accepted; a request with document fails validation (raw/docs/migrating-to-v1.md).

Related

• OpenAPI component schemas — every component schema, field by field
• Models, aliases, pricing, rate limits, context — model IDs, aliases, price, limits, context
• HTTP status codes, rate limits, retry semantics — status → exception → retry table
• Migrating from /preview/evaluation to /v1/systemone — what changed from /preview/evaluation
• TYPESAFE_* environment variables across SDKs — TYPESAFE_API_KEY and friends
• Primitives: Choice, Score, Noul — what Choice, Score, and Noul mean
• Python SDK: install, clients, system_one() — the typed Python client over this wire format
• JavaScript/TypeScript SDK: install, client, choice/score/noul — the typed JS/TS client over this wire format
• Quickstart: first call in HTTP, Python, JS — first call end to end

Sources

• raw/docs/api.md (https://docs.typesafe.ai/api)
• raw/site/openapi.json (https://docs.typesafe.ai/openapi.json)
• raw/docs/introduction__quickstart.md (https://docs.typesafe.ai/introduction/quickstart)
• raw/docs/models.md (https://docs.typesafe.ai/models)
• raw/docs/migrating-to-v1.md (https://docs.typesafe.ai/migrating-to-v1)
• raw/github/typesafe-sdk-js/src/retry.ts, raw/github/typesafe-sdk-python/src/typesafe_sdk/_core/constants.py