Create decision

Run one or more typed questions against a JSON state. Use a supported base model with inline questions, or a repository model such as acme/support-triage.

Repository models load their saved questions. Any questions supplied in the request override saved questions with the same ID and add new IDs for this call.

POST /v1/systemone is an alias with the same request, response, authentication, and retry behavior.

POST/v1/decision

Authorization

Authorizationstringrequired

Send a Modaic bearer token in the Authorization header.

Parameters

Idempotency-Keystring

Optional key between 8 and 255 characters. Reuse it when retrying this exact request. If omitted, each call is treated as a new request.

stateany JSON valuerequired

The state to evaluate. For images inside message arrays, use OpenAI-compatible image blocks: {"type":"image_url","image_url":{"url":"..."}}.

modelstringrequired

A base model (mo, mo-reasoning, modaic/mo, modaic/mo-reasoning, jev-latest, or jev-1.13.0) or an accessible repository path in owner/model form.

revisionstring

Repository models only. A branch, tag, or commit SHA. Defaults to the model's default branch. Pin a commit SHA for reproducible decisions.

questionsRecord<string, Question>

Required for base models. Optional for repository models. When supplied, the object must contain at least one question. Question IDs may be any string, including "", and are returned unchanged as answer keys.

For every question type, instructions is optional and accepts any JSON value, including null. Criteria descriptions may be strings, objects, or arrays; objects and arrays can contain nested JSON values.

Boolean likelihood question

Use type: "noul". criteria may be omitted or null. criteria.true and criteria.false are optional descriptions and may be null. The answer's noul field is the probability of true from 0 to 1.

Choice question

Use type: "choice". criteria maps non-empty option keys to a description or null, with no minimum number of options. The answer includes the selected key, a probability for every key, and confidence.

Score question

Use type: "score". criteria is an ordered array of one or more rubric descriptions; individual descriptions cannot be null. Levels are zero-indexed: five levels span 0 through 4. The returned score may be fractional. The answer includes the score, legend, probabilities, and confidence. Legend values preserve the string, object, or array descriptions.

example_idUUID

Repository models only. Groups this decision under an example you identify. When omitted, Modaic derives the example ID from the canonical state so identical states share an example.

capturebooleandefault: true

Repository models only. Set to false to skip recording the example and decision. A model's capture sample rate may also choose not to record a call.

Question example

{
  "state": {"message": "Please cancel and refund my annual plan."},
  "model": "mo",
  "questions": {
    "intent": {
      "type": "choice",
      "instructions": "Classify the customer's primary intent.",
      "criteria": {
        "refund": {"description": "The customer wants money returned.", "examples": ["Refund my plan."]},
        "cancel": "The customer only wants future service stopped.",
        "other": null
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "Score how quickly a human should respond.",
      "criteria": ["not urgent", "routine", "urgent", "critical"]
    }
  }
}

Response

modelstringrequired

The model name supplied in the request.

answersRecord<string, Answer>required

One answer for every requested question. Answer IDs and types exactly match the questions.

usageobjectrequired

Token usage with integer input_tokens and output_tokens fields.

example_idUUID

The captured example. Present for repository models when capture succeeds.

decision_idUUID

The captured decision. Present for repository models when capture succeeds.

checkpointinteger

The repository model checkpoint used for the decision.

revisionstring

The resolved revision for a repository model.

capturedboolean

Whether this repository-model call was recorded.

Unknown base models or inaccessible repository models return 404 model_not_found. An unreadable explicit revision returns 404 revision_not_found. Invalid questions or answers return 422.

Was this page helpful?