Skip to main content
POST
Create a decision
This endpoint is also served at POST /v1/alpha/decisions and POST /v1/systemone, for AI gateways whose built-in decision integrations append their own path to a custom host. Use the custom host https://api.valarhq.ai/v1 for an integration that appends /alpha/decisions, and https://api.valarhq.ai for one that appends /v1/systemone. Both paths take the same request and return the same response as POST /v1/decisions.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

Lets you retry safely. Valar records a reservation under the combination of organization, API key, and Idempotency-Key, so sending the same value again hands back the stored response rather than running inference a second time. Values can be up to 255 characters. See Idempotent Requests for the complete rules.

Maximum string length: 255
X-Valar-Completion-Window
enum<string>

Sets the completion window when the body has no metadata.completion_window. The body value wins.

Available options:
asap,
priority,
standard

Body

application/json
model
string
required

A decision model id, such as joey-1 or elephant-1. Generation models are refused on this endpoint.

Example:

"joey-1"

state
required

The input to evaluate: a string, a JSON object or a JSON array (structured data is rendered as text for you), or a conversation as {"messages": [...]} with user and assistant roles. A user message may include images as image_url content parts (base64 data URLs recommended, at most 16 per request). Numbers, booleans and null are not accepted.

Example:

"I was charged twice this month. Please refund the duplicate charge."

questions
object
required

The questions to answer, keyed by a name you choose. Answers come back under the same names. A request may carry at most 512 options across all questions, where each noul question counts as 2.

max_len
integer

An optional token cap on each question's full prompt (state, question, criteria and images). As served today, each question's prompt is limited to 16,000 tokens on joey-1 and elephant-1. That is a serving limit: the models themselves were trained on sequences of up to 16,384 tokens. max_len can lower the serving limit but not raise it. A prompt over the limit is refused with a 413 rather than truncated, and is not billed. Occasionally the cap can be checked only against the request's prompts on average rather than each prompt: the response then carries the header X-Valar-Max-Len-Enforced: false, the request was refused (413, not billed) only if its prompts averaged over max_len, and one long question among short ones may have been answered over its cap.

Required range: x >= 1
metadata
object

Optional metadata. Only completion_window is read; other string keys are accepted and ignored.

Response

The answers.

id
string
required

The request id. A retry with the same Idempotency-Key returns the same id and answers.

object
enum<string>
required
Available options:
decision
created
integer
required

Unix seconds.

model
string
required

The decision model that answered.

answers
object
required

One answer per question, under the question's name.

usage
object
required