Skip to navigation
API ReferenceDecisions

Create a decision

Answer typed questions about a state with calibrated probabilities. A decision model reads the state (text, a JSON object or array, and any images, audio, or video inside it) and answers each entry in questions independently. Every answer carries probabilities and a confidence value; decision models never generate text.

  • noul: a yes/no question. Returns the probability of yes.
  • choice: 2 to 255 named options. Returns the most likely option and the probability of each.
  • score: 2 to 10 ordered levels. Returns the expected level and the probability of each level.
  • tool: 1 to 254 function definitions. Returns the function to call, the probability of each, and a distribution for every enum and boolean argument.

Usage counts input tokens only: the state once, the text of each question, and each media item. output_tokens is always 0.

For a state longer than 131,072 tokens, long_context sets how it is read: fast (the default) answers faster, and full reads every token. Usage counts the whole state in both modes, and long_context in the response shows which one was used.

Authentication

AuthorizationBearer

Pass your EmpirioLabs API key as a bearer token. The Anthropic-style x-api-key header is also accepted on every endpoint.

Request

This endpoint expects an object.
modelstringRequired

Decision model ID, for example aplomb-1. An unknown ID returns 404 model_not_found.

statestring or object or map from strings to any or list of anyRequired

The content to decide about: text, a JSON object, or a JSON array. Put images, audio, or video anywhere inside it as media nodes, for example {"type": "image", "url": "https://example.com/photo.png"}.

The state is counted once per request, however many questions refer to it.

questionsmap from strings to objectsRequired

Questions keyed by an ID you choose, 1 to 128 per request. Each question has a type (noul, choice, score, or tool) and instructions. A choice question takes criteria as an object of option name to description or null, a score question takes criteria as an array of 2 to 10 ordered levels, and a tool question takes tools, a list of function definitions.

IDs cannot contain control characters. A request evaluates at most 512 questions in total, where each tool question counts as one plus one per enum or boolean argument.

Each question is answered independently, and answers come back under the same IDs. IDs are not shown to the model.

long_contextenumOptionalDefaults to fast

How a state longer than 131,072 tokens is read. fast answers faster. full reads every token of the state; use it when an answer can depend on details anywhere in a long state. Images, audio, and video are read in full in both modes.

A state of 131,072 tokens or fewer is always read in full. Usage counts the whole state in both modes.

Allowed values:

Response headers

X-Request-IDstringOptional
Request identifier. Include it when requesting support.

Response

One answer per question, keyed by the question IDs from the request.
modelstring
The model ID from the request.
answersmap from strings to objects
One answer per question, keyed by the question IDs from the request.
usageobject

Tokens counted for a decision request. Only input is counted: the state once, the text of each question, and each media item. There are no output tokens.

long_contextenum

How the state was read: fast or full. A state of 131,072 tokens or fewer is always read in full, and a fast request can also be read in full.

Allowed values:

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
404
Not Found Error
413
Content Too Large Error
422
Unprocessable Entity Error
429
Too Many Requests Error
503
Service Unavailable Error