Help guides

Decision models use the native System One protocol to answer one or more classification, scoring, or open-ended questions from structured state.

Endpoint and authentication

Item	Value
Request endpoint	`POST https://routerbrain.ai/decision/v1/systemone`
Authentication	`Authorization: Bearer <API-Key>`
Content-Type	`application/json`
Response mode	Synchronous JSON; streaming is not supported

Find model codes in the decision model catalog.

Quick example

curl -X POST https://routerbrain.ai/decision/v1/systemone \
  -H 'Authorization: Bearer sk-xxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-review-20260930-001' \
  -d '{
    "model": "jev",
    "state": {
      "order": { "amount": 1280, "currency": "CNY" },
      "customer": { "risk_level": "medium" }
    },
    "questions": {
      "review": {
        "type": "choice",
        "instructions": "Decide whether this order can be approved.",
        "criteria": {
          "approve": "Approve when the risk is acceptable.",
          "reject": "Reject when the risk is unacceptable."
        }
      }
    }
  }'

Request body

Field	Type	Required	Description
`model`	`string`	Yes	Decision model code, up to 128 characters.
`state`	`null` \| `string` \| `object` \| `array`	Yes	Business state supplied to the model.
`questions`	`object`	Yes	1–32 questions. Each key is a non-blank question ID up to 128 characters.
`session_id`	`string`	No	Cache-affinity session ID, up to 256 characters. Used for platform routing and not forwarded upstream.

System One extension fields outside these platform fields are forwarded using the native protocol. The request body limit is 64 KB.

Question types

Each question must contain type and may contain instructions. The supported types are:

`type`	`criteria`	Use
`choice`	Object with 1–255 choices	Select a named result. Choice names must be non-blank and no longer than 128 characters.
`score`	Array with 2–10 levels	Score against an ordered set of levels.
`noul`	Omitted, `null`, or an object	Return an open-ended, unconstrained answer. The literal type name is `noul`.

Successful response

The gateway preserves the upstream System One response. A successful response contains at least:

{
  "model": "<resolved-upstream-model>",
  "answers": {
    "review": { "...": "System One answer fields" }
  },
  "usage": {
    "input_tokens": 123,
    "output_tokens": 18
  }
}

The fields inside each answers entry are native to the selected System One model; clients should not assume a fixed nested shape. usage is used for billing. Input and output token prices are shown in the decision model catalog.

Optional headers

Header	Description
`Idempotency-Key`	Up to 255 characters. Reuse a stable value when retrying the same business request. The gateway derives an upstream idempotency key but does not cache or replay responses.
`x-session-id`	Cache-affinity session ID, used only when the request body does not contain `session_id`.
`x-trace-id`	Business trace ID recorded with request and usage data.
`x-user-id`	End-user ID from your application.
`x-agent-name`	Calling agent or service name.

Error response

Errors use the OpenAI-style envelope:

{
  "error": {
    "message": "model is required and must not exceed 128 characters",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

HTTP status	Meaning
`400`	Invalid JSON or request body parsing failure.
`401`	Missing, malformed, or invalid API key.
`422`	Invalid `state`, `model`, `questions`, question type, idempotency key, or session identifier.
`502`	All eligible upstream routes failed, or the upstream response was invalid.