> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valarhq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a decision

> Ask a decision model typed questions about an input and get a probability for every option. Decision models (joey-1, elephant-1) generate no text and are served on this endpoint only. Choose the asap, priority or standard completion window with metadata.completion_window.

> [!NOTE]
>
> 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`.


## OpenAPI

````yaml POST /decisions
openapi: 3.1.0
info:
  title: Valar API
  version: '2026-08-14'
  description: >-
    Valar exposes Responses and Chat Completions endpoints that match the OpenAI
    shape. This reference documents the fields Valar supports today.
servers:
  - url: https://api.valarhq.ai/v1
security:
  - BearerAuth: []
tags:
  - name: Models API
    description: Discover which models you can call.
  - name: Responses API
    description: Responses endpoints that follow the OpenAI interface.
  - name: Chat Completions API
    description: Chat Completions endpoints that follow the OpenAI interface.
  - name: Decisions API
    description: >-
      Answer typed questions with a probability for every option, using decision
      models.
  - name: Batches API
    description: Submit request batches and track their progress.
paths:
  /decisions:
    post:
      tags:
        - Decisions API
      summary: Create a decision
      description: >-
        Ask a decision model typed questions about an input and get a
        probability for every option, in one synchronous call with no generated
        text. Use it for classification, routing, guardrails and scoring.
      operationId: createDecision
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - name: X-Valar-Completion-Window
          in: header
          required: false
          schema:
            type: string
            enum:
              - asap
              - priority
              - standard
          description: >-
            Sets the completion window when the body has no
            `metadata.completion_window`. The body value wins.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDecisionRequest'
            example:
              model: elephant-1
              state: >-
                I was charged twice for my subscription. Please refund the
                duplicate charge.
              questions:
                route:
                  type: choice
                  instructions: Which team should handle this request?
                  criteria:
                    billing: Billing, payments, and refunds
                    technical_support: Technical troubleshooting
                refund:
                  type: noul
                  instructions: Is the customer asking for a refund?
                urgency:
                  type: score
                  instructions: How urgent is the request?
                  criteria:
                    - Routine request
                    - Needs attention today
                    - Immediate emergency
      responses:
        '200':
          description: The answers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionResponse'
              example:
                id: resp_01JC4Z8Q5M3W7K9T2X6V1B0N4P
                object: decision
                created: 1793376000
                model: elephant-1
                answers:
                  route:
                    type: choice
                    choice: billing
                    confidence: 0.998
                    probabilities:
                      billing: 0.999
                      technical_support: 0.001
                  refund:
                    type: noul
                    noul: 0.99
                  urgency:
                    type: score
                    score: 0.51
                    confidence: 0.23
                    legend:
                      '0': Routine request
                      '1': Needs attention today
                      '2': Immediate emergency
                    probabilities:
                      '0': 0.509
                      '1': 0.47
                      '2': 0.021
                usage:
                  input_tokens: 231
                  output_tokens: 3
        '400':
          description: >-
            The request was malformed: a missing state or question, an unknown
            field, an unsupported completion window, a model that is not a
            decision model, or a question definition the model rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Your organization's prepaid credit balance is exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The model does not exist or is not available to your organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            The Idempotency-Key is still in use by a request in progress, or was
            already used for a different kind of request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: The request body or a question's prompt is too large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: >-
            A rate limit or spend limit was reached, or decision capacity is
            briefly exhausted. Retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Decisions are temporarily unavailable. Retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: The request exceeded the gateway timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
      description: >-
        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](/idempotency) for the complete rules.
  schemas:
    CreateDecisionRequest:
      type: object
      required:
        - model
        - state
        - questions
      properties:
        model:
          type: string
          description: >-
            A decision model id, such as `joey-1` or `elephant-1`. Generation
            models are refused on this endpoint.
          example: joey-1
        state:
          description: >-
            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.
          oneOf:
            - type: string
            - type: object
            - type: array
              items: {}
          example: I was charged twice this month. Please refund the duplicate charge.
        questions:
          type: object
          minProperties: 1
          additionalProperties:
            $ref: '#/components/schemas/DecisionQuestion'
          description: >-
            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:
          type: integer
          minimum: 1
          description: >-
            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.
        metadata:
          $ref: '#/components/schemas/DecisionRequestMetadata'
      additionalProperties: false
    DecisionResponse:
      type: object
      required:
        - id
        - object
        - created
        - model
        - answers
        - usage
      properties:
        id:
          type: string
          description: >-
            The request id. A retry with the same Idempotency-Key returns the
            same id and answers.
        object:
          type: string
          enum:
            - decision
        created:
          type: integer
          description: Unix seconds.
        model:
          type: string
          description: The decision model that answered.
        answers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DecisionAnswer'
          description: One answer per question, under the question's name.
        usage:
          $ref: '#/components/schemas/DecisionUsage'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
      additionalProperties: false
    DecisionQuestion:
      type: object
      required:
        - type
      description: >-
        One question about the state. Each question is answered on its own and
        cannot see another question's answer. A question takes only `type`,
        `instructions` and `criteria`; any other field, or a type other than the
        three below, is refused with a 400.
      properties:
        type:
          type: string
          enum:
            - choice
            - noul
            - score
          description: >-
            `choice` picks one of the named options in `criteria`. `noul` is a
            yes/no question answered with the probability of yes. `score` places
            the state on the scale of levels in `criteria`.
        instructions:
          description: >-
            The question itself, usually a string. If you leave it out, send
            null or send an empty value, a default question for the type is
            used, such as "Which option applies to the state?" for `choice`.
          oneOf:
            - type: string
            - type: object
            - type: array
              items: {}
            - type: 'null'
        criteria:
          description: >-
            For `choice`, required: an object mapping 1 to 255 option names to
            their descriptions. For `score`, required: an array of 1 to 10 level
            descriptions, lowest first, numbered from 0. For `noul`, optional:
            an object with exactly the keys `"true"` and `"false"`, or null for
            the yes/no defaults. A description is usually a string; an object or
            array is rendered as text, and a null `choice` description uses the
            option name.
          oneOf:
            - type: object
              additionalProperties: {}
            - type: array
              items: {}
              minItems: 1
              maxItems: 10
            - type: 'null'
      additionalProperties: false
    DecisionRequestMetadata:
      type: object
      description: >-
        Optional metadata. Only completion_window is read; other string keys are
        accepted and ignored.
      properties:
        completion_window:
          type: string
          enum:
            - asap
            - priority
            - standard
          description: >-
            The [completion window](/inference-modes#completion-windows) for
            this decision. `asap` (the default) answers at once. `priority` and
            `standard` cost less and hold the answer on the same connection for
            their window, up to about 10 seconds and 60 seconds. `flex` and
            batch are not available for decisions. You can also set it with the
            `X-Valar-Completion-Window` header.
      additionalProperties:
        type: string
    DecisionAnswer:
      type: object
      required:
        - type
      description: >-
        The answer to one question. Which fields are present depends on the
        question's type.
      properties:
        type:
          type: string
          enum:
            - choice
            - noul
            - score
        choice:
          type: string
          description: '`choice` only: the most likely option name.'
        noul:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            `noul` only: the probability that the answer is yes. Apply your own
            threshold.
        score:
          type: number
          description: >-
            `score` only: the expected level on the 0-based scale. 1.5 sits
            between levels 1 and 2.
        probabilities:
          type: object
          additionalProperties:
            type: number
          description: >-
            `choice` and `score`: the probability of each option name or level
            number. To threshold a choice, use `probabilities[choice]`.
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            `choice` and `score`: how concentrated the distribution is. It is
            not the probability of the chosen option.
        legend:
          type: object
          additionalProperties:
            type: string
          description: '`score` only: each level number mapped to its description.'
    DecisionUsage:
      type: object
      required:
        - input_tokens
        - output_tokens
      properties:
        input_tokens:
          type: integer
          description: >-
            The shared state counted once, plus each question's tokens. This is
            what a decision is billed on.
        output_tokens:
          type: integer
          description: One per question, priced at zero.
    ErrorObject:
      type: object
      required:
        - message
        - type
      properties:
        message:
          type: string
        type:
          type: string
        param:
          oneOf:
            - type: string
            - type: 'null'
        code:
          oneOf:
            - type: string
            - type: integer
            - type: 'null'
      additionalProperties: true
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.