Classification & scoring

TypeSafe System One evaluates text or structured context against named questions. Use it to detect intent, route a support request, or score urgency. Opper preserves TypeSafe’s native answers, including probabilities, confidence, and score legends. Send requests to POST https://api.opper.ai/v3/compat/v1/systemone with your project-scoped Opper API key. TypeSafe credentials are managed by Opper. A paid plan is required, and your project’s model access rules and provider access requirements apply. Existing TypeSafe HTTP clients can change their base URL to https://api.opper.ai/v3/compat and authenticate with Authorization: Bearer $OPPER_API_KEY. Send the native state and questions format to /v1/systemone.

Question types

Type	Use it for	Answer
`noul`	A yes/no question	`noul`: the probability of yes, between 0 and 1.
`choice`	Choosing a category	`choice`, `confidence`, and a `probabilities` map.
`score`	Scoring against ordered levels	A probability-weighted `score`, `confidence`, `probabilities`, and a `legend`. Levels start at zero; the score can be fractional.

Every request contains:

model: a TypeSafe model ID.
state: the context to evaluate, as a string, object, or array.
questions: a nonempty object of named questions. Each question requires type and instructions.

choice requires a criteria object with 1–255 categories. score requires an ordered criteria array with 2–10 levels. noul does not require criteria; you can optionally describe the true and false outcomes in a criteria object. You can include several questions in one request. Answers use the same keys as your questions.

Examples

Set a project API key from the platform:

export OPPER_API_KEY="op-your-project-api-key"

Detect a refund request

curl --fail-with-body -sS \
  https://api.opper.ai/v3/compat/v1/systemone \
  -H "Authorization: Bearer $OPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "typesafe/jev-1.13.0",
  "state": "I was charged twice for my subscription. Please return the duplicate payment.",
  "questions": {
    "refund_requested": {
      "type": "noul",
      "instructions": "Is the customer requesting a refund?"
    }
  }
}'

Example response:

{
  "model": "jev-1.13.0",
  "answers": {
    "refund_requested": {
      "type": "noul",
      "noul": 0.98
    }
  },
  "usage": {
    "input_tokens": 287,
    "output_tokens": 21
  }
}

Choose a probability threshold in your application if you need a Boolean decision. Opper returns the probability without applying a threshold.

Route a support request

curl --fail-with-body -sS \
  https://api.opper.ai/v3/compat/v1/systemone \
  -H "Authorization: Bearer $OPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "typesafe/jev-1.13.0",
  "state": {
    "subject": "Cannot authenticate",
    "message": "Our integration started returning 401 errors after rotating our API key."
  },
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "Choose the team best suited to resolve this request.",
      "criteria": {
        "finance": "Charges, payments, and invoices",
        "engineering": "API and integration issues",
        "account_management": "Contracts and subscriptions"
      }
    }
  }
}'

An example answers.team:

{
  "type": "choice",
  "choice": "engineering",
  "confidence": 1.0,
  "probabilities": {
    "engineering": 1.0,
    "account_management": 0.0,
    "finance": 0.0
  }
}

Score urgency

curl --fail-with-body -sS \
  https://api.opper.ai/v3/compat/v1/systemone \
  -H "Authorization: Bearer $OPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "typesafe/jev-1.13.0",
  "state": "Our production checkout is unavailable. Every customer payment has failed for the last 20 minutes.",
  "questions": {
    "urgency": {
      "type": "score",
      "instructions": "Rate the operational urgency.",
      "criteria": [
        "Low: informational request with no operational impact",
        "Medium: degraded functionality with a workaround",
        "High: production outage preventing customer payments"
      ]
    }
  }
}'

An example answers.urgency:

{
  "type": "score",
  "score": 2.0,
  "confidence": 1.0,
  "probabilities": {
    "0": 0.0,
    "1": 0.0,
    "2": 1.0
  },
  "legend": {
    "0": "Low: informational request with no operational impact",
    "1": "Medium: degraded functionality with a workaround",
    "2": "High: production outage preventing customer payments"
  }
}

With these three levels, scores range from 0 to 2. Answers and token counts can vary between calls.

Choose a model

Discover evaluation models with:

curl --fail-with-body -sS "https://api.opper.ai/v3/models?type=evaluation"

Use typesafe/jev-1.13.0 to select the catalog endpoint for Jev 1.13. Native names such as jev-1.13.0, jev-latest, and jev-preview also resolve to TypeSafe catalog entries. The qualified aliases typesafe/jev-latest and typesafe/jev-preview are supported too. Aliases follow Opper’s approved catalog mapping. They do not automatically follow a new upstream TypeSafe release. The response’s model identifies the upstream model that answered. Jev 1.13 has a 64k total context limit, with a separate 32k limit for the state plus the longest question. TypeSafe enforces these limits using its own tokenizer.

Use the System One endpoint for evaluation models. Chat Completions and the other generation protocols do not accept these models. This endpoint accepts synchronous text and structured context; streaming, tools, and additional request fields are unsupported.

Usage, cost, and traces

The native response contains model, answers, and usage.input_tokens / usage.output_tokens. Opper does not add a response envelope. Billing uses the selected endpoint’s catalog input and output token prices. See the model catalog for current pricing. Add -i to a curl call to see these response headers:

Header	Meaning
`X-Opper-Cost` / `X-Generation-Cost`	The call’s cost in USD.
`X-Generation-Id`	Opper’s generation ID.
`X-Opper-Trace-Id`	The trace UUID.

Usage and billing are recorded for successful calls. Full input/output traces depend on your Opper retention rule. Provider data policies are configured separately through model access; EU gateway hosting does not make every provider EU-hosted.

Errors

Status	Meaning
`400`	An unknown, unavailable, or wrong-type model, or an upstream bad request.
`401`	Missing or invalid project API key.
`402`	Evaluation is unavailable on the free plan, or billing access is blocked.
`403`	Model access rules or required provider access prevent the request.
`413`	The upstream provider rejected an oversized request.
`422`	Invalid input, unsupported question types or fields, or upstream validation failure.
`429`	Upstream rate limiting.
`502`	An upstream service or authentication failure prevented completion.
`503`	The provider or model configuration is unavailable.
`504`	The request timed out.
`529`	TypeSafe is temporarily overloaded.

See the API reference for the request and response schemas, or TypeSafe’s API documentation for the native protocol.

Get started

Platform

Build

Observe & Control

Integrations

Tutorials

Tooling

Classification & scoring

Question types

Examples

Detect a refund request

Route a support request

Score urgency

Choose a model

Usage, cost, and traces

Errors

​Question types

​Examples

​Detect a refund request

​Route a support request

​Score urgency

​Choose a model

​Usage, cost, and traces

​Errors

Question types

Examples

Detect a refund request

Route a support request

Score urgency

Choose a model

Usage, cost, and traces

Errors