---
title: "Answer typed questions with probabilities"
method: POST
path: "/api/v1/decisions"
tags: ["AI"]
---

# Answer typed questions with probabilities

`POST /api/v1/decisions`

## Request

- Base URL: `https://your-deployment.example.com`
- URL: `https://your-deployment.example.com/api/v1/decisions`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Evaluates each question independently against the same `input` and returns calibrated probabilities - no generated text. Question types: `predicate` (probability a statement is true), `choice` (pick one value) and `score` (an ordered scale; `score` is the probability-weighted mean of 0-based level indices). `confidence` is computed by B4M with one published formula for every model. Answers come back in question order; a question the model declines is a `refusal` answer and does not fail the request. `input` is a string or a list of `text`, `json` and `image` parts; an image is a `file_id` you can read or a base64 `data:` URL (http(s) URLs are rejected). Platform ceilings: 50 questions, 64 choices, 2-10 levels and 8 images; each model's own caps are listed by `GET /api/v1/decision-models` and a request over one is a 422 naming the cap and `param`. Probabilities are not comparable across models: tune thresholds per model against labelled examples, and pin a versioned model id when you do. A busy provider is retried once on the same model, never another; after that the response is a 503 with `Retry-After`. Billed per input and output token at the model's rate, settled to the exact expected cost (most calls charge 0 credits, some 1). Authenticate with an API key (`b4m_live_`) carrying `ai:decide` or `ai:generate`, or a JWT.

## Request body

- CreateDecisionRequest
  - `model` string, required: A decision model id from `GET /api/v1/decision-models`.
  - `input` union, required
    - string
    - union[]
      - union
        - object
          - `type` 'text', required
          - `text` string, required
        - object
          - `type` 'json', required
          - `json` union, required: Structured state. Sent natively to models that accept it, otherwise serialized to text.
            - object
            - unknown[]
              - …
        - object
          - `type` 'image', required
          - `file_id` string: A Files entry the caller can read. Exactly one of file_id or image_url.
          - `image_url` string: A base64 data: URL. http(s) URLs are rejected; upload the image and pass file_id instead.
  - `questions` union[], required
    - union
      - object
        - `type` 'predicate', required
        - `name` string, required: Unique within the request; answers carry it back.
        - `instructions` string, required: A statement to judge true or false against the input.
      - object
        - `type` 'choice', required
        - `name` string, required: Unique within the request; answers carry it back.
        - `instructions` string, required
        - `choices` object[], required
          - `value` string, required
          - `description` string
      - object
        - `type` 'score', required
        - `name` string, required: Unique within the request; answers carry it back.
        - `instructions` string, required
        - `levels` object[], required: Ordered lowest to highest; the answer score is a 0-based index into this list.
          - `label` string, required
          - `description` string
  - `safety_identifier` string: A stable, non-identifying id for your end user. Defaults to a hash of the B4M user id.

## Response `200`

One answer per question, in question order.

- CreateDecisionResponse200
  - `id` string, required: Unique per decision.
  - `object` 'decision', required
  - `model` string, required: The resolved model version. Pin it when you tune thresholds.
  - `answers` union[], required: One per question, in question order.
    - union
      - object
        - `type` 'predicate', required
        - `name` string, required
        - `probability` number, required: Probability that the statement is true.
      - object
        - `type` 'choice', required
        - `name` string, required
        - `choice` string, required: The most probable value.
        - `probabilities` object[], required: In request order.
          - `value` string, required
          - `probability` number, required
        - `confidence` number, required: (n * p_max - 1) / (n - 1), computed by B4M for every model.
      - object
        - `type` 'score', required
        - `name` string, required
        - `score` number, required: Probability-weighted mean of the 0-based level indices.
        - `probabilities` object[], required: In level order; value is the level index.
          - `value` integer, required
          - `label` string, required
          - `probability` number, required
        - `confidence` number, required: Distance-aware: 1 - sum(p_i * |i - peak|) / mean_i(|i - (n-1)/2|).
      - object
        - `type` 'refusal', required
        - `name` string, required
  - `usage` object, required
    - `input_tokens` integer, required
    - `output_tokens` integer, required
    - `total_tokens` integer, required

## Other responses

- `400`: The billing user or organization could not be resolved, or the API key bills an organization its owner is no longer a member of.
- `401`: Missing/invalid credentials, or the provider refused the configured key (`errorCode: "provider_rejected"`).
- `403`: The API key holds neither `ai:decide` nor `ai:generate`.
- `404`: An image `file_id` does not exist or is not readable by the caller. Reading one also needs the `files:read` scope; a key without it gets 403.
- `405`: The path does not serve this HTTP method.
- `422`: The body failed validation, or the request exceeds a per-model cap (`limit_exceeded`), sends an image to a text-only model (`unsupported_input`), repeats a question name or choice value (`invalid_request`), names a model this deployment does not serve (`model_unavailable`), overflows the model context (`context_length_exceeded`), or the caller cannot afford it (`insufficient_credits`). `param` names the offending field when there is one.
- `429`: Per-key or per-user decisions rate limit exceeded.
- `502`: The provider failed or answered something that does not fit the questions (`provider_error`).
- `503`: The provider stayed overloaded through one same-model retry (`errorCode: "provider_overloaded"`), or this deployment has no credential for the model (`errorCode: "provider_not_configured"`).

---

[API](https://skmtc.dev/bike4mind/apis/bike4mind-api.md) · [All operations](https://skmtc.dev/bike4mind/apis/bike4mind-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bike4mind/apis/bike4mind-api/revisions/db47495b892f?raw)