Decisions

Use the OpenGateway Decisions endpoint to submit typed questions about a state and receive probabilities, selected options, scores, usage, and validation errors.

POST https://apis.opengateway.ai/v1/decisions evaluates one or more typed questions against a state and returns structured answers. This endpoint does not generate prose or support streaming.

Endpoint and authentication#

Item	Value
Method and path	`POST https://apis.opengateway.ai/v1/decisions`
Authentication	Required: `Authorization: Bearer <key>`
Content type	`application/json`

Request schema#

Send a JSON object. model, state, and questions are required.

Top-level fields#

Field	Type	Required	Limits and semantics
`model`	string	Yes	Non-blank model ID that supports the `decisions` endpoint.
`state`	string, JSON object, or JSON array	Yes	Must not be `null`. The content being judged; preserve object/array structure when questions refer to its fields.
`questions`	object mapping question IDs to question objects	Yes	Must contain 1–64 entries. Each question ID must be non-blank.
`images`	string[]	No	Up to 8 base64-encoded or data-URL items. Supported by `sionic-ai/jev-omni`; not by text-only `sionic-ai/decider-4b`.
`audio`	string[]	No	Up to 1 base64-encoded or data-URL item. No current model takes audio: requests with `audio` are rejected.
`videos`	Video[]	No	Up to 1 video object. The current public catalog lists video input for `sionic-ai/jev-omni`. See the Video schema below.
`extra`	object	No	OpenGateway request extensions. See the extension fields below.

Each media item is limited to 20 MiB; all media in a request combined are limited to 32 MiB. These limits also apply to video frames. The live model catalog lists sionic-ai/jev-omni input modalities as text, image, and video; sionic-ai/decider-4b is text-only. Check the model catalog for current model availability and modalities.

Common question fields#

Every value in questions is an object with these fields:

Field	Type	Required	Limits and semantics
`type`	string	Yes	Question kind: `noul`, `choice`, or `score`.
`instructions`	string, object, or array	Yes	Non-null directions for the judgment. Use a string, object, or array; reference state fields with backtick paths such as `support.tickets[0].message`.

`noul` question#

Field	Type	Required	Limits and semantics
`criteria`	object	No	Optional definitions for the yes and no outcomes.
`criteria.true`	string or null	No	Describes what should count as yes.
`criteria.false`	string or null	No	Describes what should count as no.

instructions must still be non-null. If it is blank, provide meaningful criteria.true or criteria.false content. The model returns the probability that the answer is yes in the noul answer field.

`choice` question#

Field	Type	Required	Limits and semantics
`criteria`	object mapping option names to string or null descriptions	Yes	Must define at least 2 options. Each key is an option name; its value describes that option or is `null`.

The answer's choice field is the option with the highest probability.

`score` question#

Field	Type	Required	Limits and semantics
`criteria`	string[]	Yes	Must define at least 2 levels, ordered from low to high. Each string describes one level. The gateway enforces the minimum; the TypeSafe upstream may reject more than 10 levels.

Video object#

Field	Type	Required	Limits and semantics
`frames`	string[]	Yes	Non-empty list of up to 16 base64-encoded or data-URL frame items. Shared media size limits apply.
`fps`	number or null	No	Frame rate; defaults to `1.0` when omitted.

`extra` fields#

Field	Type	Required	Limits and semantics
`extra.fallbacks`	string[]	No	Explicit fallback model IDs to try if the primary attempt fails. Values must not be blank.
`extra.debug`	string[]	No	Debug categories: `normalizations`, `deprecations`, and/or `routing`. Requested categories may appear in the response's `debug` object.
`extra.input_type`	string	No	`document` or `query`; defaults to `document`. This extension is for embeddings and does not affect Decisions.

Response schema#

The response contains one answer for each question ID. The values are typed by the corresponding question's type.

Top-level fields#

Field	Type	Semantics
`model`	string	Model ID used for the response.
`answers`	object mapping question IDs to answer objects	Each question ID maps to an answer with the matching type.
`usage`	object	Input, output, and total token counts.
`debug`	object, optional	Present when debug metadata is requested with `extra.debug`; contains only applicable requested categories.

`noul` answer#

Field	Type	Semantics
`type`	`"noul"`	Answer type discriminator.
`noul`	number from 0 to 1	Probability that the answer is yes. This is the judgment itself; there is no separate `confidence` field.

`choice` answer#

Field	Type	Semantics
`type`	`"choice"`	Answer type discriminator.
`choice`	string	Option with the highest probability (argmax).
`probabilities`	object mapping option names to numbers	Probability assigned to each defined option.
`confidence`	number	Confidence value returned by the model.

`score` answer#

Field	Type	Semantics
`type`	`"score"`	Answer type discriminator.
`score`	number	Expected level: the probability-weighted average of the ordered level indices, so it may be fractional.
`legend`	object mapping numeric level strings to descriptions	Maps level indices to the corresponding `criteria` text. Indices start at `"0"`.
`probabilities`	object mapping numeric level strings to numbers	Probability assigned to each level index.
`confidence`	number	Confidence value returned by the model.

Usage fields#

Field	Type	Semantics
`input_tokens`	integer	Billed input token count.
`output_tokens`	integer	Always `0` for Decisions.
`total_tokens`	integer	Sum of input and output tokens.

Debug fields#

When returned, debug can contain the following optional arrays:

Field	Entry fields
`debug.normalizations[]`	`param`, `action`, and optional `before` and `after` values.
`debug.deprecations[]`	`param`, `message`.
`debug.routing[]`	`provider`, `region`, `status`, and optional `target`.

Sample request and response#

The request asks the same three questions about a support ticket: whether a refund is requested, which team should handle it, and how urgent it is.

JSON

{
  "model": "sionic-ai/decider-4b",
  "state": {
    "ticket": "I was charged twice for my subscription this month. Please refund the duplicate payment."
  },
  "questions": {
    "is_refund": {
      "type": "noul",
      "instructions": "Is the customer asking for a refund?"
    },
    "category": {
      "type": "choice",
      "instructions": "Which team should handle `ticket`?",
      "criteria": {
        "billing": "Billing, payment, and subscription issues",
        "technical": "Product problems and technical support",
        "sales": "Purchasing and sales inquiries"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is `ticket`?",
      "criteria": ["Not urgent", "Somewhat urgent", "Very urgent"]
    }
  }
}

Sample response from the live smoke test:

JSON

{"model":"sionic-ai/decider-4b","answers":{"is_refund":{"type":"noul","noul":0.9825},"category":{"type":"choice","choice":"billing","probabilities":{"billing":0.9961,"technical":0.0036,"sales":3.0E-4},"confidence":0.9942},"urgency":{"type":"score","score":1.19,"legend":{"0":"Not urgent","1":"Somewhat urgent","2":"Very urgent"},"probabilities":{"0":0.1504,"1":0.5063,"2":0.3433},"confidence":0.2595}},"usage":{"input_tokens":152,"output_tokens":0,"total_tokens":152}}

Usage and billing#

The endpoint does not stream. Billing is based on input tokens only; output tokens are 0. Check the model catalog for current pricing.

Errors#

Errors use an OpenAI-style envelope: {"error":{"message":"...","type":"...","param":"...","code":"..."}}. The optional param and code fields appear when applicable.

HTTP status	Cause	Example
`400 Bad Request`	Invalid question or request fields. For example, a `choice` question with fewer than two options fails validation.	`{"error":{"message":"choice criteria must define at least 2 options","type":"invalid_request_error","param":"questions[q].hasAtLeastTwoOptions"}}`
`400 Bad Request`	Media was sent to a model that does not accept it. For example, `sionic-ai/decider-4b` does not accept images, audio, or video on this endpoint.	Message: `Model 'sionic-ai/decider-4b' does not accept images, audio or videos on /v1/decisions.`
`401 Unauthorized`	API key is missing or invalid.	`{"error":{"message":"Invalid or missing API key.","type":"invalid_request_error","code":"invalid_api_key"}}`

For additional validation guidance and plain HTTP examples, see the Decisions concept guide.

Decisions

Endpoint and authentication#

Request schema#

Top-level fields#

Common question fields#

noul question#

choice question#

score question#

Video object#

extra fields#

Response schema#

Top-level fields#

noul answer#

choice answer#

score answer#

Usage fields#

Debug fields#

Sample request and response#

Usage and billing#

Errors#

`noul` question#

`choice` question#

`score` question#

`extra` fields#

`noul` answer#

`choice` answer#

`score` answer#