Run Inference
Run inference on JSON state with one or more typed questions. Use a supported base model
with inline questions, or a repository model such as acme/support-triage.
Task-specific repository models load their saved questions and must be called
without questions. Non-task-specific repositories have no saved questions and
must be called with questions on every request.
/v1/systemoneAuthorization
Send a Modaic bearer token in the Authorization header.
Headers
Optional key between 8 and 255 characters. Reuse it when retrying this exact request. For approved ZDR workspaces using covered direct base-model inference, the key is ignored and every call is treated as a new operation. If omitted, each call is treated as a new request.
Body
The state to evaluate. For images, use OpenAI-compatible image blocks
anywhere in the state: {"type":"image_url","image_url":{"url":"..."}}, with
an https:// URL or an inline data:image/...;base64, URL. mo and mo-fast
read up to 4 images (PNG, JPEG, GIF, or WebP, 20 MB each) per decision; more
than that, or bytes that are not an image, return 422 invalid_image.
A base model such as mo or mo-fast, or an accessible repository path
in workspace/model form.
Optional reasoning for mo-fast. Omit for no reasoning.
Maximum thinking tokens per question: low = 512, medium = 1,024,
high = 2,048, xhigh = uncapped. Generated reasoning tokens are
charged at the model's output-token rate.
Repository models only. A branch, tag, or commit SHA. Defaults to the model's default branch. Pin a commit SHA for reproducible decisions.
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 at least one option required. An empty criteria object returns
422 with code validation_error. 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.
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.
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-fast",
"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"]
}
}
}
Enable reasoning
curl https://modaic.dev/api/v1/systemone \
-H "Authorization: Bearer $MODAIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mo-fast",
"reasoning_effort": "low",
"state": {"message": "I was charged twice for the same order."},
"questions": {
"action": {
"type": "choice",
"instructions": "Choose the appropriate next action.",
"criteria": {
"review_refund": "Review the duplicate charge for a refund.",
"close": "Close without further action."
}
}
}
}'
Omit reasoning_effort for no reasoning. Reasoning tokens are charged at the
model's output-token rate and included in usage.output_tokens. You pay for
actual tokens generated, not the maximum budget.
Response
The model name supplied in the request.
One answer for every requested question. Answer IDs and types exactly match the questions.
Token usage with integer input_tokens and output_tokens fields.
With reasoning enabled, reasoning_tokens reports thinking-token usage.
output_tokens includes generated thinking, any natural closing token,
and one final decision token per question. Do not add reasoning_tokens
again when calculating output usage.
Present only with reasoning enabled. Diagnostics keyed by question ID include the budget, generated and reasoning token counts, finish reason, generation and scoring times, and cached tokens. Raw reasoning text is not returned.
The captured example. Present for repository models when capture succeeds.
The captured decision. Present for repository models when capture succeeds.
The repository model checkpoint used for the decision.
The resolved revision for a repository model.
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. A repository model with no manifest yet returns
409 model_manifest_missing. A base model that is still in development returns
503 model_in_development. A base model called without questions returns
422 questions_required; invalid questions or answers return 422. Reusing an
Idempotency-Key with a different request body returns
409 idempotency_key_reused outside covered ZDR direct inference. Changing
reasoning_effort changes the request body for idempotency purposes where
replay applies. See Zero Data Retention for
the exception and coverage requirements.