Jev API quickstart: copy-paste System One requests

TypeSafe AI hosts this Decisions API. Estimate tokens on the pricing calculator. Recorded OpenRouter model ids, and what this handbook will not guess, are on Jev AI on OpenRouter.

Endpoint and auth

Create and rotate keys in the TypeSafe key console. Keep the key on the server.

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <API_KEY>
Content-Type: application/json

Required body fields

One call, three question types

The following request mixes noul, choice, and score. Marked as an illustrative example from the TypeSafe docs.

{
  "state": "Customer email: My invoice charged twice this month and I cannot download the PDF.",
  "model": "jev-latest",
  "questions": {
    "is_support": {
      "type": "noul",
      "instructions": "Is this a customer support request that needs a human or bot reply?"
    },
    "department": {
      "type": "choice",
      "instructions": "Route this message to the best department.",
      "criteria": {
        "billing": "Payments, invoices, refunds, subscriptions",
        "technical": "Bugs, outages, API errors, product failures",
        "sales": "Pricing questions, upgrades, new purchases"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is a reply?",
      "criteria": [
        "low",
        "medium",
        "high"
      ]
    }
  }
}

Illustrative response

{
  "model": "jev-1.13.0",
  "answers": {
    "is_support": {
      "type": "noul",
      "noul": 0.97
    },
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {
        "billing": 0.88,
        "technical": 0.12,
        "sales": 0
      },
      "confidence": 0.81
    },
    "urgency": {
      "type": "score",
      "score": "medium",
      "legend": [
        "low",
        "medium",
        "high"
      ],
      "probabilities": {
        "low": 0.1,
        "medium": 0.62,
        "high": 0.28
      },
      "confidence": 0.55
    }
  },
  "usage": {
    "input_tokens": 318,
    "output_tokens": 34
  }
}

Python sketch

import os, requests

API_KEY = os.environ["TYPESAFE_API_KEY"]  # server-side only

payload = {
  "state": "Customer email: My invoice charged twice this month and I cannot download the PDF.",
  "model": "jev-latest",
  "questions": {
    "is_support": {
      "type": "noul",
      "instructions": "Is this a customer support request that needs a human or bot reply?"
    },
    "department": {
      "type": "choice",
      "instructions": "Route this message to the best department.",
      "criteria": {
        "billing": "Payments, invoices, refunds, subscriptions",
        "technical": "Bugs, outages, API errors, product failures",
        "sales": "Pricing questions, upgrades, new purchases"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is a reply?",
      "criteria": [
        "low",
        "medium",
        "high"
      ]
    }
  }
}

res = requests.post(
    "https://api.typesafe.ai/v1/systemone",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
res.raise_for_status()
print(res.json())

Confidence-gated routing

answers = res.json()["answers"]
dept = answers["department"]
if dept["confidence"] < 0.55:
    route_to_human(dept)
else:
    route_to_queue(dept["choice"])

Errors and backoff

• 401Authentication failed
• 422Request body validation failed
• 429Rate limited — exponential backoff
• 529Overloaded — exponential backoff

Official SDKs retry 429 and 529 with exponential backoff by default. Mirror that behavior if you call HTTP directly.

Official Python and JavaScript SDKs are in the Jev GitHub projects directory.

instructions as structured data

instructions may be a string, object, or array. Put the question in one field and reference data fields with backticks inside the question text. Useful when you must keep payload data out of prose.