How to use the Jev AI API

Before you start

You need access to the official TypeSafe console, an API key, and a terminal with cURL. The official quick start also links to the playground, which is useful for trying questions before writing code.

Keep the key in your local environment as TYPESAFE_API_KEY. Do not put it in a public repository or a browser-side application. Still waiting for access? Read the access guide. Using a Gateway key instead? Follow the separate Vercel integration.

1. Define one small decision

Save this as request.json. Our example routes a payment complaint to a team. It does not authorize a refund or send a reply.

{
  "model": "jev-latest",
  "state": "My annual plan renewed twice today. Please check the duplicate payment.",
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "Which team should investigate this message?",
      "criteria": {
        "payments": "Duplicate charges, invoices, or payment problems.",
        "product": "App behavior or broken features.",
        "other": "A request that fits neither team."
      }
    }
  }
}

Make the criteria distinct. The “other” option gives the model somewhere to put messages outside the two named teams. Read the Choice reference for the complete contract.

2. Send the request

From the directory containing your file, run:

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

The official endpoint is POST /v1/systemone. The bearer token authenticates the request. The response groups answers under your question IDs; here, inspect answers.team. See the HTTP reference for the full response structure.

3. Inspect before you automate

For this Choice question, inspect choice, probabilities, and confidence. Do not treat the chosen team alone as permission to perform an account action.

Our suggested first evaluation includes: a clear duplicate charge, a broken app screen, an unrelated request, and a message that mentions both payments and product behavior. Record the expected route before you run them. If the ambiguous case is forced into a confident answer, improve the criteria and evaluation set before connecting the workflow.

For repeatable comparisons, record the model ID returned with each run. See the limitations guide.

If the call fails

• Authentication: confirm the environment variable is set in the terminal that runs cURL; check that the key has access.
• Invalid request: validate your JSON, field names, and question type against the API reference.
• Rate limiting: reduce concurrency and respect any retry guidance in the response.
• Unexpected classification: inspect the input and criteria. A successfully parsed response can still make the wrong decision.

Once the request works, explore three practical workflow patterns.

Use an official SDK when you are ready

TypeSafe documents a Python package, typesafe-sdk, and a JavaScript / TypeScript package, @typesafe-ai/sdk. They are client libraries for the hosted API. Our GitHub and SDK guide connects each package with the official repository and documentation.

Keep the language-specific method names straight: the Python client uses system_one; the JavaScript client uses systemOne. Refer to the SDK index for the appropriate reference instead of mechanically translating examples between languages.

Sources checked September 23, 2026. This is an independent guide; access, packages, and provider terms can change.