Documentation / API reference

Make a decision

Send one typed question and receive a structured answer.

The fields, schemas, and errors below are generated from the gateway OpenAPI file. The API accepts one decision per request. Its response contains the resolved model, probabilities, routing action, and usage.

Numerical examples elsewhere in these docs are illustrative. A successful response is not evidence that your workflow is ready for automation.

The gateway also exposes the public OpenAPI document. This site includes a local snapshot so reference generation does not require an API connection.

POST `/v1/decide`

Choose one offered option

Complete formatted model input is limited to 2048 tokens; inference checks its exact tokenizer before encoding and never truncates (413). Body limit is 4 MB compressed and decompressed (413). JSON nesting is limited to 64 (400). Supports gzip, x-gzip and zstd, one layer only. Choice takes 2 to 255 options and score 2 to 10 levels (422 outside). Probabilities cover offered options only. probability is the chosen option's probability. The routing gate acts when probability >= threshold (default 0.9), otherwise asks a human. This configurable routing rule is not a certified precision guarantee. One question per request: send situation (text) or state (JSON), a question, a type and its options or levels. Unknown fields are rejected at every level. Requests that can never succeed are rejected before rate limiting and never get 429. Every response carries X-Request-Id; error bodies are {code, message} and never repeat request content.

Authentication: [{"ApiKey":[]}]

Request body (required)

application/json

DecideRequestschema

oneOf · ChoiceRequest

ChoiceRequestobjectadditionalProperties: false

model required

stringpattern: "^ren-(?:\\d+\\.\\d+\\.\\d+|latest|preview)$"

situation optional

Plain-text situation. Send exactly one of situation or state.

stringminLength: 1

state optional

Structured situation as any non-null JSON value; a string must be nonblank. Send exactly one of situation or state.

schema

question required

The single question the model answers about the situation.

stringminLength: 1

type required

stringconst: "choice"

options required

arrayminItems: 2maxItems: 255

Array items

OptionobjectadditionalProperties: false

id required

stringminLength: 1maxLength: 128

description optional

string

threshold optional

Routing threshold; defaults to 0.9 unless configured by the operator.

numberminimum: 0maximum: 1

oneOf · variant 1

schema

oneOf · variant 2

schema

oneOf · ScoreRequest

ScoreRequest

Levels have unique numeric string IDs from 1 through 10, ordered strictly increasingly. At least two levels are required by the engine.

objectadditionalProperties: false

model required

stringpattern: "^ren-(?:\\d+\\.\\d+\\.\\d+|latest|preview)$"

situation optional

Plain-text situation. Send exactly one of situation or state.

stringminLength: 1

state optional

Structured situation as any non-null JSON value; a string must be nonblank. Send exactly one of situation or state.

schema

question required

The single question the model answers about the situation.

stringminLength: 1

type required

stringconst: "score"

levels required

arrayminItems: 2maxItems: 10

Array items

OptionobjectadditionalProperties: false

id required

stringminLength: 1maxLength: 128

description optional

string

threshold optional

Routing threshold; defaults to 0.9 unless configured by the operator.

numberminimum: 0maximum: 1

oneOf · variant 1

schema

oneOf · variant 2

schema

oneOf · NoulRequest

NoulRequestobjectadditionalProperties: false

model required

stringpattern: "^ren-(?:\\d+\\.\\d+\\.\\d+|latest|preview)$"

situation optional

Plain-text situation. Send exactly one of situation or state.

stringminLength: 1

state optional

Structured situation as any non-null JSON value; a string must be nonblank. Send exactly one of situation or state.

schema

question required

The single question the model answers about the situation.

stringminLength: 1

type required

stringconst: "noul"

threshold optional

Routing threshold; defaults to 0.9 unless configured by the operator.

numberminimum: 0maximum: 1

oneOf · variant 1

schema

oneOf · variant 2

schema

Schema illustration (replace placeholder values)

json

"string"

Responses and error codes

200 Decision with typed fields, routing gate and exact input-token usage

X-Request-Id

Unique request ID; quote it when contacting support.

stringpattern: "^req_[0-9a-f]{32}$"

X-RateLimit-Limit

Requests allowed in the current one-minute window by the tightest limit (key or account).

integerminimum: 1

X-RateLimit-Remaining

Requests left in the current window by the tightest limit.

integerminimum: 0

X-RateLimit-Reset

Seconds until the current window resets.

integerminimum: 0

application/json

DecideResponseobjectadditionalProperties: false

id required

string

model required

stringpattern: "^ren-\\d+\\.\\d+\\.\\d+$"

choice required

string

probabilities required

object

Additional values

numberminimum: 0maximum: 1

action required

stringenum: ["act","ask_human"]

gate required

objectadditionalProperties: false

threshold required

numberminimum: 0maximum: 1

type required

stringenum: ["choice","score","noul"]

threshold required

numberminimum: 0maximum: 1

expected_score optional

numberminimum: 1maximum: 10

probability required

Calibrated probability of the chosen option. The gate acts when probability >= threshold. For noul, the probability of true is probabilities.true.

numberminimum: 0maximum: 1

usage required

UsageobjectadditionalProperties: false

input_tokens required

integerminimum: 1maximum: 2048

output_tokens required

integerconst: 0

model required

stringpattern: "^ren-\\d+\\.\\d+\\.\\d+$"

Schema illustration (replace placeholder values)

json

{
  "id": "string",
  "model": "string",
  "choice": "string",
  "probabilities": {},
  "action": "act",
  "gate": {
    "threshold": 0
  },
  "type": "choice",
  "threshold": 0,
  "probability": 0,
  "usage": {
    "input_tokens": 1,
    "output_tokens": 0,
    "model": "string"
  }
}

400 Malformed JSON or compression, or JSON nested deeper than 64 levels; unknown model IDs return unknown_model and name ren-1.1.0, ren-latest, ren-preview

X-Request-Id

Unique request ID; quote it when contacting support.

stringpattern: "^req_[0-9a-f]{32}$"

application/json

ErrorobjectadditionalProperties: false

code required

string

message required

string

Schema illustration (replace placeholder values)

json

{
  "code": "string",
  "message": "string"
}

401 Invalid authentication

X-Request-Id

Unique request ID; quote it when contacting support.

stringpattern: "^req_[0-9a-f]{32}$"

application/json

ErrorobjectadditionalProperties: false

code required

string

message required

string

Schema illustration (replace placeholder values)

json

{
  "code": "string",
  "message": "string"
}

402 Insufficient organization credits when BILLING_ENFORCED is enabled. Charging is off by default.

X-Request-Id

Unique request ID; quote it when contacting support.

stringpattern: "^req_[0-9a-f]{32}$"

application/json

ErrorobjectadditionalProperties: false

code required

string

message required

string

Schema illustration (replace placeholder values)

json

{
  "code": "string",
  "message": "string"
}

413 Body over 4 MB or input over 2048 tokens; never truncated

X-Request-Id

Unique request ID; quote it when contacting support.

stringpattern: "^req_[0-9a-f]{32}$"

application/json

ErrorobjectadditionalProperties: false

code required

string

message required

string

Schema illustration (replace placeholder values)

json

{
  "code": "string",
  "message": "string"
}

415 Unsupported content type or content encoding

X-Request-Id

Unique request ID; quote it when contacting support.

stringpattern: "^req_[0-9a-f]{32}$"

application/json

ErrorobjectadditionalProperties: false

code required

string

message required

string

Schema illustration (replace placeholder values)

json

{
  "code": "string",
  "message": "string"
}

422 Request does not match the schema: unknown field, option or level count, or blank text

X-Request-Id

Unique request ID; quote it when contacting support.

stringpattern: "^req_[0-9a-f]{32}$"

application/json

ErrorobjectadditionalProperties: false

code required

string

message required

string

Schema illustration (replace placeholder values)

json

{
  "code": "string",
  "message": "string"
}

429 Rate limited; wait Retry-After seconds (retry-after-ms milliseconds). Only for requests that can succeed later

X-Request-Id

Unique request ID; quote it when contacting support.

stringpattern: "^req_[0-9a-f]{32}$"

X-RateLimit-Limit

Requests allowed in the current one-minute window by the tightest limit (key or account).

integerminimum: 1

X-RateLimit-Remaining

Requests left in the current window by the tightest limit.

integerminimum: 0

X-RateLimit-Reset

Seconds until the current window resets.

integerminimum: 0

Retry-After

{
  "code": "string",
  "message": "string"
}

Read Markdown ↗

Make a decision

POST /v1/decide

Choose one offered option

Request body (required)

application/json

Responses and error codes

X-Request-Id

X-RateLimit-Limit

X-RateLimit-Remaining

X-RateLimit-Reset

application/json

X-Request-Id

application/json

X-Request-Id

application/json

X-Request-Id

application/json

X-Request-Id

application/json

X-Request-Id

application/json

X-Request-Id

application/json

X-Request-Id

X-RateLimit-Limit

X-RateLimit-Remaining

X-RateLimit-Reset

Retry-After

retry-after-ms

application/json

X-Request-Id

application/json

X-Request-Id

application/json

X-Request-Id

application/json

X-Request-Id

application/json

POST `/v1/decide`