JEV Decision API

Classify a message

Send a message and category options to POST /v1/systemone. This example uses jev-latest to choose a team for a customer inquiry.

curl https://api.sukidata.com/v1/systemone \
  -H "Authorization: Bearer $SUKIDATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: decision-example-1' \
  --data '{
  "model": "jev-latest",
  "state": "We plan to integrate your API next month, with around 100,000 requests per month. Which plan would fit our team?",
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "Which team should handle this message?",
      "criteria": {
        "billing": "Payments and invoices",
        "support": "Technical issues",
        "sales": "Pricing and purchasing"
      }
    }
  }
}'

{
  "id": "dec_example",
  "model": "jev-1.13.0",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "sales",
      "confidence": 0.9,
      "probabilities": {
        "billing": 0.01,
        "support": 0.02,
        "sales": 0.97
      }
    }
  },
  "usage": {
    "input_tokens": 400,
    "output_tokens": 40,
    "cost": 0.0000168
  }
}

Read the category from answers.team.choice. Here, sales selects the sales team. Answers are returned synchronously.

Requests require an API key and sufficient AI balance. Use a new Idempotency-Key for each evaluation; reuse it for retries.

Understand the result

Each entry in answers matches a question name, such as team. A choice answer contains the selected category and its probability distribution:

• probabilities gives each option's probability; choice is the option with the highest value.
• confidence summarizes how concentrated the distribution is. It is not the selected option's probability or a guarantee of correctness.
• model identifies the version used. id identifies the request, and usage reports its token usage and USD cost.

Choose a question type

Add more questions to the same request

To also check purchase intent and urgency, add these two entries to questions. All three questions use the same message in state.

{
  "plan_inquiry": {
    "type": "noul",
    "instructions": "Is this customer evaluating a plan for their team?"
  },
  "urgency": {
    "type": "score",
    "instructions": "How urgent is this message?",
    "criteria": [
      "Routine request with no time pressure or blocked work",
      "An active issue needs attention, but work can continue",
      "Critical work is blocked and needs immediate attention"
    ]
  }
}

The additional entries in answers could look like this:

{
  "plan_inquiry": {
    "type": "noul",
    "noul": 0.99
  },
  "urgency": {
    "type": "score",
    "score": 0.2,
    "confidence": 0.7,
    "legend": {
      "0": "Routine request with no time pressure or blocked work",
      "1": "An active issue needs attention, but work can continue",
      "2": "Critical work is blocked and needs immediate attention"
    },
    "probabilities": {
      "0": 0.85,
      "1": 0.1,
      "2": 0.05
    }
  }
}

• noul: 0.99 indicates a likely yes. Values near 0 indicate no; near 0.5 means uncertainty. Noul measures probability, not intensity, and has no separate confidence field.
• score uses zero-based level indices, so three levels give a 0–2 scale, not 0–1. It is the probability-weighted mean: 0 × 0.85 + 1 × 0.1 + 2 × 0.05 = 0.2. legend maps the indices to your criteria.
• Score also returns confidence. A low score can be confident, and a high score can be uncertain; check both when deciding how to act.

For a condition that can have several independent labels, use one noul per label. Use choice when one category should win.

Write useful criteria

• Supply the facts. Include the message and any relevant product or document context in state. It can be text, a JSON object or an array.
• Ask one thing at a time. Put the actual question in instructions; question names only identify returned answers. Evaluate topic, intent and urgency separately, then combine them in code.
• Define clear boundaries. Explain what belongs in each choice category, and include an “other” option when needed. Score levels should describe observable differences, not just “Low”, “Medium” and “High”.

Every question is evaluated independently against the same state. If a question needs another answer as input, make a follow-up request with that answer included in the context.

A request supports up to 1,024 questions and a UTF-8 JSON body up to 1 MiB. instructions also accepts text, objects or arrays. See the API reference for complete field constraints.

Use the answers

With the successful response in result, use the selected category to route the message. Send uncertain classifications for review:

const { team } = result.answers;
const route = team.confidence >= 0.8
  ? team.choice
  : 'manual_review';

console.log({ route });

The 0.8 threshold is illustrative. Test your criteria and thresholds against labeled cases from your own application, including ambiguous examples. Request more context or human review when the result is uncertain; keep confirmation steps for consequential actions.

Try representative cases in the Playground, inspect the probabilities and export the request. Agents can use evaluate_decision through MCP.

For further model guidance, see TypeSafe's choice, noul, score and confidence guides.

Models and pricing

JEV is the currently available System One model. Choose a moving alias or pin a specific version in the model field.

Both aliases currently resolve to jev-1.13.0; they are not separate models. The response's model reports the version used. Use GET /v1/models to discover model IDs; a versioned ID can be callable even when only aliases are listed.

Input costs $0.042 per million tokens; output is free. Read usage.input_tokens for input usage and usage.cost for the USD cost. See the pricing guide for billing details.

Retries and errors

A timeout does not confirm failure. Retry with the same Idempotency-Key, API key and input. Successful requests return their original result without another execution or charge; changing the key creates a new request.

Limit retry attempts and increase the delay between them. If the problem persists, save the error response and X-Sukidata-Request-ID, when present, and contact support@sukidata.com.