Skip to content
RightNow
Skip to article
Docs navigation: Decision model / API reference

API reference

Status

RightNow AIDecision modelAPI reference Updated

View as Markdown
On this page

Send a model, state and named questions to the decide endpoint to receive structured answers.

decide.ts
import { SystemZeroClient } from '@rightnowai/system-zero';

const client = new SystemZeroClient({
  apiKey: process.env.SYSTEM_ZERO_API_KEY,
  baseURL: "https://api.rightnowai.co/v1",
});
const reply = await client.decide({
  "model": "rightnow-decision",
  "state": "The blender I ordered arrived with a cracked jar.",
  "questions": {
    "damaged": {
      "type": "boolean",
      "instructions": "Did the item arrive damaged?"
    }
  }
});
console.log(JSON.stringify(reply, null, 2));
const models = await client.models.list();
console.log(models);

// Set SYSTEM_ZERO_API_KEY to your API key before running this example.
// Run this example on your server.
// SDK defaults: The default is 5 retries, also the maximum, with 150 seconds
// per attempt and a 60-second total retry budget. A single wait longer than 60
// seconds raises the last error.
// Use Retry-After-Ms, or Retry-After when milliseconds are absent. The wait is
// never shorter than a random backoff floor: a random fraction of 0.5 seconds
// doubled for each attempt, capped at 8 seconds.

Request fields

POST https://api.rightnowai.co/v1/system-zero/decide accepts a JSON body with a RightNow decision model API key in the Authorization: Bearer header.

model
rightnow-decision follows the alias. Use an attested pinned version to select a model (Models).
state
The text, JSON object or JSON array to evaluate.
questions
Named boolean, choice or score questions, each with its own instructions (Decisions).
session_id
Optional routing affinity hint. It does not create a persistent session.
prompt_cache_key
Optional routing hint used when session_id is absent.
attachments
Optional inline files in the formats listed in Inputs. The complete JSON request, including state, questions and base64 data, must fit the published caller body limit.
policy
Optional confidence threshold and cost cap for this request (Request policy).

Send Content-Type: application/json. Add an Idempotency-Key when you need replay protection (Idempotency).

  1. Before the decision

    RightNow checks your key, the body and your limits before any work starts.

    Key missing or unknown: 401 invalid_api_key.

    Body over 3,665,920 bytes: 413 payload_too_large.

    Over 600 requests a minute, by default: 429 rate_limit_exceeded.

    Over 16 calls in flight, by default: 429 concurrency_limit_exceeded.

    Same key and body as a stored answer: that answer can return with X-RightNow-Idempotent-Replay: true.

  2. The decision

    RightNow answers each question you named.

    Unavailable or starting: 503 system_zero_unavailable with Retry-After. Wait, then send the same request.

    No answer in time: 504 system_zero_timeout. Do not resend it unchanged.

  3. After the decision

    HTTP 200 returns answers under your question names, and usage.

    A question can be refused inside a 200. Read every entry.

    See Pricing for what an answered call costs.

One decide request, from key to answer.

Read the response

A successful request returns HTTP 200. Read each named entry in answers; it can hold an answer or a question refusal.

Read answers.damaged in your response. probability is the likelihood of true; decision is the selected boolean; confidence is its probability.

reply shape
Text
id: string
model: string
served_by: string
created: integer
context:
  route: string
  tokens: integer
answers:
  damaged:
    type: "boolean"
    probability: number
    confidence: number
    calibration_version: string
    decision: boolean
    alternatives:
      decision: boolean
      confidence: number
    calibrated: boolean
usage:
  input_tokens: integer
  cached_input_tokens: integer
  media_tokens: integer
  long_input_tokens: integer
  media_items: integer
  thought_tokens: integer
The shape of a reply. Each type stands in for a value.
id
Identifies the decision.
model
The answering model version.
served_by
The answering version, matching model.
created
When the decision was made, in Unix seconds.
context
route, the context route, and tokens, the context's size in tokens.
answers
Results grouped under the question names from the request.
usage
Token counts (input_tokens, cached_input_tokens, media_tokens, long_input_tokens and thought_tokens) and media_items, the number of media items.
policy
The request policy you sent, echoed as sent. Absent when you sent none.

Fresh answers include decision, confidence, alternatives, calibrated and calibration_version. confidence is the probability of the selected decision. Legacy idempotent replays retain their stored answer shape. See Decisions for the field rules and question refusals.

With a request policy, an answer below min_confidence has abstained: true and no decision. Never act on its other fields.

A successful reply can also include provenance, metadata about the execution that produced it. Read Provenance for its fields.

Event stream reply

POST /v1/system-zero/decide can return the complete decision over Server-Sent Events. Send Accept: text/event-stream with exactly one media range. The match ignores case and allows parameters such as charset=utf-8. A list, */* or any q parameter keeps the JSON reply. A stream member in the body returns HTTP 400 invalid_request.

This is the same answer at the same time and price as JSON. There are no partial answers. The model returns decisions with confidences, not generated text. Prices, receipts, request limits, rate limits and concurrency limits are unchanged. One stream counts as one request. There is no streaming or per-event fee.

EventCarries
decisionThe complete JSON reply, byte for byte, on one data: line.
doneHTTP status, request id, replay flag, latency, server timing and rate limit. Always last.

Only a completed HTTP 200 reply becomes an event stream. Every refusal keeps its HTTP status, JSON error envelope and headers. The WebSocket stream is separate and unchanged. Read Streaming.

The reply has Content-Type: text/event-stream; charset=utf-8 and Cache-Control: no-store. Accept a data line of up to 4,000,000 bytes. Ignore unknown event names and comment lines. There are exactly two events, with no progress events or keepalive comments.

Use fetch or another HTTP client that supports POST with a body and an Authorization header. Browser EventSource cannot send this request. There is no event id, retry field or resume. If the connection breaks, resend the same body with the same Idempotency-Key within 24 hours. A saved answer returns the same decision at no cost, with replayed: true in done.

Values are illustrative, not measured. Reply fields are shortened for display.

Manual HTTP
Shell
curl -N https://api.rightnowai.co/v1/system-zero/decide \
  -H "Authorization: Bearer $SYSTEM_ZERO_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -H 'Idempotency-Key: ticket-8841-triage-1' \
  --data-binary @- <<'JSON'
{
  "model": "rightnow-decision-3.0.0",
  "state": "The charger arrived cracked. I want my money back.",
  "questions": {
    "wants_refund": {
      "type": "boolean",
      "instructions": "Is the customer asking for a refund?"
    }
  }
}
JSON

event: decision
data: {"answers":{"wants_refund":{"decision":true,"confidence":0.98}}}

event: done
data: {"http_status":200,"replayed":false,"latency_ms":149}

Response headers

The key window is checked first. A key refusal skips the workspace check. Otherwise, the reset uses the window with fewer requests remaining; ties select the key. Console-created keys have equal limits for both windows.

X-Request-Id
Keep this request identifier when contacting support.
X-RateLimit-Limit
The lower key or workspace limit after both checks. A key refusal returns its own limit. Also includes X-RateLimit-Remaining.
X-RateLimit-Reset
The Unix second when the window with fewer requests remaining resets; ties select the key. A key refusal returns its own reset.
X-RightNow-Idempotent-Replay
true for a replay; unavailable when the settled answer cannot be read.
X-Latency-Ms
Response timing. Server-Timing describes gateway stages; neither is a latency guarantee.
Cache-Control
no-store. Call the API from a server over HTTPS.

On a rate refusal, Retry-After uses the refusing window's reset. The workspace's limit per minute is shared by all its keys.

Validation

Use the decide schema. Unsupported fields such as messages, temperature and stream return invalid_request.

Inline input: text, JSON state (robot state), images, voice, PDF, video (preview). Only listed formats are supported. Read Inputs for input formats and availability and Sessions for the routing hints.

The 64k and 128k bands are served through Danger zone with SZ-Danger-Zone: long_context_64k or long_context_128k. Read Danger zone for access steps and limits.

For a refusal, inspect error.code and error.retryable. Follow the response's retry advice in Errors.

Credit balance

GET /v1/credits reads the balance for a workspace using prepaid credits. Use your API key.

Read limit
60 per minute
Reply fields
object, balance_cents, available_cents, currency, as_of, promotional_held_cents
object
credits
balance_cents
The balance in whole cents.
available_cents
The balance after subtracting held funds, in whole cents.
currency
usd
as_of
The time of the reading as an ISO timestamp.
promotional_held_cents
Optional. Promotional credit reserved by in-flight claims, in whole cents.