Create decision

Send a state and a map of typed questions to the selected decision model. It 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.

Choose an API model ID from the model catalog. The Decisions guide explains how to choose a model, run examples, and use the answers in your application. The reference examples use typesafe/jev-latest, a text-only model.

Errors

Request validation returns 400 with error.type: "invalid_request_error" before sending the request to a model. For question validation, error.param names the field to fix. Other errors can omit param.

For example, a request to an available model with state present and "questions": {"q": {"type": "rank"}} returns:

{
  "error": {
    "message": "questions.q.type: unknown question type \"rank\"; expected noul, choice or score",
    "type": "invalid_request_error",
    "param": "questions.q.type"
  }
}

Model errors relayed to your application keep their HTTP status and use {"error": {"message": "...", "type": "..."}}. Input that passes request validation can still be rejected by the model, including with 422. A relayed 429 uses rate_limit_error; relayed 5xx errors use api_error, except 504, which uses timeout_error. These rate-limit and server errors have generic messages, such as the model failed to answer. When Inworld cannot reach the model, the 502 uses upstream_error. Retry transient errors with exponential backoff and honor Retry-After when present.

Check the HTTP status and content type before parsing: errors for authentication, credits and your account's rate limit use a different body. 401 and 429 are plain text, and 402 has a numeric error.code. See Errors in the Decisions guide for status codes and next steps.

Image input

Use the List models API with output_modalities=decisions to find decision models. In the response, check models[].spec.inputModalities. Choose a model whose spec.inputModalities includes image. Sending an image to a text-only model returns 400.

Put image parts directly in the state array alongside text:

{
  "state": [
    "Evaluate this screenshot.",
    {
      "type": "image_url",
      "image_url": {
        "url": "data:image/png;base64,<BASE64_IMAGE>",
        "detail": "auto"
      }
    }
  ]
}

This fragment illustrates state; a complete request also requires model and questions.

Image-count and request-size limits depend on the selected model. The text-only example model's limits do not apply to all image requests. See Evaluate an image for a complete Python request using a checkout screenshot.