Provenance

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.

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": "rightnow-decision",
    "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.

An identifier with no public id reads unpublished.

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.

A decision record lookup returns the stored reply with keyed_replay false: a lookup is not a replay.

Reply size

A reply too large to carry provenance omits it. Provenance never refuses a 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.