Provenance

RightNow AI RightNow System Zero Provenance Updated 2026-11-07

On this page

Read provenance
Fields
Request IDs and replays
Reply size
Playground and data

A successful RightNow System Zero decision reply can include provenance, metadata about the execution that produced the reply.

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": "system-zero",
  "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.

Read provenance

These Python and TypeScript programs send one decision over HTTP with no Idempotency-Key and print the X-Request-Id header as the current request. When the reply includes provenance, they print provenance.request_id as the first request, then the keyed replay state.

provenance.py

Python

import os
import requests

response = requests.post(
    "https://api.rightnowai.co/v1/system-zero/decide",
    headers={"Authorization": f"Bearer {os.environ['SYSTEM_ZERO_API_KEY']}"},
    json={
        "model": "system-zero",
        "state": "The blender I ordered arrived with a cracked jar.",
        "questions": {
            "damaged": {
                "type": "boolean",
                "instructions": "Did the item arrive damaged?"
            }
        }
    },
    timeout=130,
)
print("Current request", response.headers.get("X-Request-Id"))
reply = response.json()
provenance = reply.get("provenance") if response.ok else None
if provenance is None:
    print(reply)
else:
    print("First request", provenance["request_id"])
    print("Keyed replay", provenance["keyed_replay"])
    print(provenance)

provenance.ts

TypeScript

const url = "https://api.rightnowai.co/v1/system-zero/decide";
const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SYSTEM_ZERO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "system-zero",
    "state": "The blender I ordered arrived with a cracked jar.",
    "questions": {
      "damaged": {
        "type": "boolean",
        "instructions": "Did the item arrive damaged?"
      }
    }
  }),
});
console.log("Current request", response.headers.get("X-Request-Id"));
const reply = await response.json();
const provenance = response.ok ? reply.provenance : undefined;
if (provenance === undefined) {
  console.log(JSON.stringify(reply, null, 2));
} else {
  console.log("First request", provenance.request_id);
  console.log("Keyed replay", provenance.keyed_replay);
  console.log(JSON.stringify(provenance, null, 2));
}

The field is optional. A stored reply written before provenance keeps its original body and has none. Read provenance only when it is present, and never fill a missing field.

Fields

A provenance object has exactly these fields.

decision_id: The decision ID, equal to the reply's id.
request_id: The ID of the request that produced the decision.
created: The decision's creation time in Unix seconds, equal to the reply's created.
model: The model string you requested, including an alias when you used one.
resolved_release: The concrete release, equal to the reply's model.
render_id: The serving render identifier.
numeric_fingerprint: The serving fingerprint, a string of 64 lowercase hexadecimal characters.
calibration_version: The exact calibration version of each answered question, by question name. A question refusal has no entry.
route: direct or long, the context route of the reply.
served_by: The reply's served_by value.
attachment_classes: The sorted, unique attachment kinds in the request: audio, document, image or video. Empty for a request without attachments.
keyed_replay: false on a fresh reply; true when the API returns a stored provenance reply for the same Idempotency-Key.

A calibration version alone does not establish calibration. Read each answer's calibrated flag. Fingerprints and serving identifiers are strings, not quality scores or signatures.

Attachment classes contain no names, source URLs or content. A listed class still follows its existing input availability; this metadata grants no additional input support.

Request IDs and replays

The HTTP X-Request-Id header identifies the current request. It can differ from provenance.request_id, the first request that produced the decision.

A stream decision carries the same object at reply.provenance. The frame's request_id identifies the current request.

When the API returns a stored reply with keyed_replay set to true, it preserves the original decision ID, request ID, creation time and other provenance facts. Reusing the same key after a dropped connection does not guarantee the original reply.

Reply size

Provenance counts toward the reply size bound, which is checked before the request is admitted, dispatched or billed. A request near that bound can return HTTP 413 questions_too_large. Shorten question names or choice labels, or send fewer questions, before you send a changed request.

Playground and data

In Playground, open Details after a run, then Provenance. Request shows the current request ID; First request shows the request that produced the decision. Older stored replies can omit provenance. Playground then shows provenance as not recorded. The stored body remains byte for byte unchanged; no missing field is inferred. Response JSON and its copied text keep the returned provenance values.

Provenance stays with the existing keyed reply and follows its retention and eviction rules. There is no separate provenance store. Decision IDs, request IDs and question names can link to your own records. Read Idempotency and the data handling terms.

Execution evidence is not returned.