Decisions

Create decision

Get typed answers to named questions about a state

POST/alpha/decisions

Preview. The /alpha path and the request and response shape may change before this API is marked stable. See release stages.

Evaluates a state against a map of typed questions with TypeSafe's Jev model (typesafe/jev-latest) and returns one answer per question: a yes/no probability (noul), a pick from your options (choice), or a rating on your levels (score). Answers are never free text, so your code can branch on them directly.

The bodies follow TypeSafe's System One API, with Inworld model ids and a routing metadata block added. See the Decisions guide for question types, differences from TypeSafe's API, limits, and billing.

Authorizations

Authorizationstringrequired

Your authentication credentials. For Basic authentication, please populate Basic $INWORLD_API_KEY.

Please make sure your API Key has write permissions for the Router API in order to create, update, and delete routers. You can create a key in one command with the Inworld CLI: inworld workspace add-key.

Body

application/json

modelstringrequired

The System One model. Use typesafe/jev-latest. The bare TypeSafe id (jev-latest) is also accepted.

stateoneOfrequired

The content to evaluate: a plain string for text, or an object or array for structured data such as chat logs, records, or application state. Text only; images, audio and video are not supported.

questionsobjectrequired

The questions to answer, keyed by ids you choose. Each answer comes back under the same id. The ids are not sent to the model and do not affect inference.

Response

200 - application/json

modelstring

The exact model version that answered, provider-qualified (for example typesafe/jev-1.13.0).

answersobject

One answer per question, keyed by the ids used in questions.

usageobject

Token usage. Decisions are billed on input_tokens only; output tokens are not billed.

Show child attributes

input_tokensinteger

output_tokensinteger

metadataobject

Inworld routing metadata, with the same keys as on chat completions.

Show child attributes

attemptsobject[]

Show child attributes

modelstring

status_codeinteger

duration_msnumber

successboolean

generation_idstring

Unique identifier for this request.

total_duration_msinteger

Total request duration in milliseconds.

Create decision

curl -X POST 'https://api.inworld.ai/alpha/decisions' \
  -H "Authorization: Basic $INWORLD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "typesafe/jev-latest",
    "state": "Help! My payouts have been failing for 3 days.",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "Does this convey urgency?"
      },
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {
          "billing": "Payments, invoicing, refunds",
          "technical": "Bugs, outages, integrations",
          "sales": "Pricing, upgrades, new accounts"
        }
      }
    }
  }'

One question of each type

{
  "model": "typesafe/jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    },
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {
        "billing": 0.88,
        "technical": 0.12,
        "sales": 0
      },
      "confidence": 0.81
    },
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": {
        "0": "Calm",
        "1": "Frustrated",
        "2": "Very angry"
      },
      "probabilities": {
        "0": 0,
        "1": 0.95,
        "2": 0.05
      },
      "confidence": 0.92
    }
  },
  "usage": {
    "input_tokens": 402,
    "output_tokens": 69
  },
  "metadata": {
    "attempts": [
      {
        "model": "typesafe/jev-1.13.0",
        "status_code": 200,
        "duration_ms": 212.4,
        "success": true
      }
    ],
    "generation_id": "0f5d3c4e-8f0b-4a53-9a55-2f3a6f0d8a1b",
    "total_duration_ms": 212
  }
}