{ "openapi": "3.1.0", "info": { "title": "RightNow System Zero API", "version": "1", "description": "Decisions over a state, with each selected outcome's estimated probability, every alternative and evidence-backed calibration status. Every answer and refusal carries X-Request-Id." }, "servers": [ { "url": "https://api.rightnowai.co/v1" } ], "security": [ { "apiKey": [] } ], "paths": { "/system-zero/stream": { "get": { "operationId": "openStream", "summary": "Open an incremental decision stream.", "description": "Use an authenticated HTTP/1.1 WebSocket handshake with subprotocol system-zero.stream.v1. Each dispatched update is an ordinary decide charged at the active rate card; accepted updates may coalesce. See docs/system-zero/stream-v1.md and docs/system-zero/stream-v1.schema.json for messages, limits and reconnect rules.", "security": [ { "apiKey": [] } ], "responses": { "101": { "description": "WebSocket handshake accepted; the first application message is hello." }, "426": { "description": "An ordinary GET requires a WebSocket handshake.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "Retry-After-Ms": { "$ref": "#/components/headers/Retry-After-Ms" }, "x-should-retry": { "$ref": "#/components/headers/x-should-retry" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "rate_limit_exceeded or stream_limit_exceeded; honor Retry-After-Ms.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "Retry-After-Ms": { "$ref": "#/components/headers/Retry-After-Ms" }, "x-should-retry": { "$ref": "#/components/headers/x-should-retry" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "service_unavailable; retry after the advertised delay.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "Retry-After-Ms": { "$ref": "#/components/headers/Retry-After-Ms" }, "x-should-retry": { "$ref": "#/components/headers/x-should-retry" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/system-zero/decide": { "post": { "operationId": "decide", "summary": "Answer questions about a state.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Sends the request at most once: the same key and body replays the stored answer for 24 hours.", "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[\\x20-\\x7E]+$" } }, { "name": "X-Client-Request-Id", "in": "header", "required": false, "description": "Your own id for the request, echoed back.", "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[\\x20-\\x7E]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideRequest" } } } }, "responses": { "200": { "description": "Fresh successful answers use structured confidence v1. A stored reply from before the change may use the deprecated legacy branch for its 24 hours of retention, only with X-RightNow-Idempotent-Replay: true. Replay preserves answer shape and calibration flags; calibration identifiers use opaque public names or unpublished. A reply never mixes legacy and v1 successful answers; refusals are unchanged.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RightNow-Idempotent-Replay": { "$ref": "#/components/headers/X-RightNow-Idempotent-Replay" }, "X-Latency-Ms": { "$ref": "#/components/headers/X-Latency-Ms" }, "Server-Timing": { "$ref": "#/components/headers/Server-Timing" } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DecideReply" }, { "$ref": "#/components/schemas/LegacyReplayReply" } ] }, "examples": { "boolean": { "summary": "A high-confidence false decision, with calibration unattested.", "value": { "id": "szd_00000000000000000000000000000001", "model": "system-zero-1.0.0", "served_by": "system-zero-1.0.0", "created": 1792144800, "context": { "route": "direct", "tokens": 100 }, "answers": { "escalate": { "type": "boolean", "probability": 0.06, "decision": false, "confidence": 0.94, "alternatives": [ { "decision": true, "confidence": 0.06 } ], "calibrated": false, "calibration_version": "unpublished" } }, "usage": { "input_tokens": 100, "cached_input_tokens": 0, "media_tokens": 0, "long_input_tokens": 0, "media_items": 0, "thought_tokens": 0 } } }, "choice": { "summary": "A choice and all remaining outcomes, with calibration unattested.", "value": { "id": "szd_00000000000000000000000000000002", "model": "system-zero-1.0.0", "served_by": "system-zero-1.0.0", "created": 1792144800, "context": { "route": "direct", "tokens": 100 }, "answers": { "action": { "type": "choice", "choice": "escalate", "probabilities": { "escalate": 0.94, "wait": 0.05, "close": 0.01 }, "decision": "escalate", "confidence": 0.94, "alternatives": [ { "decision": "wait", "confidence": 0.05 }, { "decision": "close", "confidence": 0.01 } ], "calibrated": false, "calibration_version": "unpublished" } }, "usage": { "input_tokens": 100, "cached_input_tokens": 0, "media_tokens": 0, "long_input_tokens": 0, "media_items": 0, "thought_tokens": 0 } } }, "score": { "summary": "A selected level distinct from the expected score, with calibration unattested.", "value": { "id": "szd_00000000000000000000000000000003", "model": "system-zero-1.0.0", "served_by": "system-zero-1.0.0", "created": 1792144800, "context": { "route": "direct", "tokens": 100 }, "answers": { "urgency": { "type": "score", "score": 1.1, "legend": { "0": "low", "1": "medium", "2": "high" }, "probabilities": { "0": 0.1, "1": 0.7, "2": 0.2 }, "decision": "1", "confidence": 0.7, "alternatives": [ { "decision": "2", "confidence": 0.2 }, { "decision": "0", "confidence": 0.1 } ], "calibrated": false, "calibration_version": "unpublished" } }, "usage": { "input_tokens": 100, "cached_input_tokens": 0, "media_tokens": 0, "long_input_tokens": 0, "media_items": 0, "thought_tokens": 0 } } } } } } }, "4XX": { "description": "A refusal of the request, the key or its limits: error.code names it.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "Retry-After-Ms": { "$ref": "#/components/headers/Retry-After-Ms" }, "x-should-retry": { "$ref": "#/components/headers/x-should-retry" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "The platform could not answer: retry when error.retryable is true.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "Retry-After-Ms": { "$ref": "#/components/headers/Retry-After-Ms" }, "x-should-retry": { "$ref": "#/components/headers/x-should-retry" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/models": { "get": { "operationId": "listModels", "summary": "The names an account can send in the model field.", "responses": { "200": { "description": "The alias, then each version served.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } }, "4XX": { "description": "A refusal of the key or its limits.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "Retry-After-Ms": { "$ref": "#/components/headers/Retry-After-Ms" }, "x-should-retry": { "$ref": "#/components/headers/x-should-retry" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "5XX": { "description": "The platform could not answer.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "Retry-After-Ms": { "$ref": "#/components/headers/Retry-After-Ms" }, "x-should-retry": { "$ref": "#/components/headers/x-should-retry" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "A RightNow API key, rnsk_..., as Authorization: Bearer ." } }, "headers": { "X-Request-Id": { "description": "The gateway's id for this request; quote it to support.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "The key's requests a minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the key's minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "The unix second the key's window reopens.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before sending again.", "schema": { "type": "integer" } }, "Retry-After-Ms": { "description": "The same wait in milliseconds; read it first.", "schema": { "type": "integer" } }, "x-should-retry": { "description": "Whether the same request can be answered later: true or false, as error.retryable.", "schema": { "enum": [ "true", "false" ] } }, "X-RightNow-Idempotent-Replay": { "description": "true on a stored answer replayed for the same Idempotency-Key.", "schema": { "enum": [ "true", "unavailable" ] } }, "X-Latency-Ms": { "description": "The gateway's time for this answer, in milliseconds.", "schema": { "type": "integer" } }, "Server-Timing": { "description": "The gateway's stages and their durations, on answers to a proven key.", "schema": { "type": "string" } } }, "schemas": { "DecideRequest": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "$ref": "#/components/schemas/StructuredJson" }, "attachments": { "anyOf": [ { "type": "array", "maxItems": 16, "items": { "allOf": [ { "$ref": "#/components/schemas/Attachment" }, { "properties": { "type": { "enum": [ "image", "audio", "document" ] } } } ] } }, { "type": "array", "minItems": 1, "maxItems": 1, "items": { "allOf": [ { "$ref": "#/components/schemas/Attachment" }, { "properties": { "type": { "const": "video" }, "data": { "pattern": "^data:video/mp4;base64," } } } ] } }, { "type": "null" } ], "description": "One silent H.264 MP4 video, without any other attachment. Video upload references are not supported." }, "questions": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$" }, "minProperties": 1, "maxProperties": 1024, "additionalProperties": { "$ref": "#/components/schemas/Question" } }, "session_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "prompt_cache_key": { "type": "string", "minLength": 1, "maxLength": 256 }, "route": { "type": "string", "enum": [ "standard" ] }, "mode": { "type": "string", "enum": [ "standard" ] } }, "required": [ "model", "state", "questions" ], "additionalProperties": false, "description": "Send one silent H.264 MP4 video as an inline base64 data URL. Maximum duration: 10 seconds. Maximum dimensions: 1920 x 1080. Maximum decoded file size: 2,621,440 bytes (2.5 MiB). The complete JSON request must fit 3,665,920 bytes, including base64 and questions. Frames are sampled at 2 per second from time zero, up to 20 frames. Rotated videos, soundtracks, separate attachments and video upload references are not supported.", "allOf": [ { "if": { "required": [ "attachments" ], "properties": { "attachments": { "type": "array", "contains": { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "video" } } } } } }, "then": { "properties": { "attachments": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "name", "type", "data" ], "properties": { "type": { "const": "video" }, "data": { "type": "string", "pattern": "^data:video/mp4;base64," } }, "not": { "required": [ "upload" ] } } } } } } ] }, "Question": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "instructions": { "$ref": "#/components/schemas/StructuredJson" }, "criteria": { "type": "object", "properties": { "true": { "type": "string" }, "false": { "type": "string" } }, "additionalProperties": false } }, "required": [ "type", "instructions" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "choice" }, "instructions": { "$ref": "#/components/schemas/StructuredJson" }, "criteria": { "type": "object", "description": "Each option's key, and its description or null.", "propertyNames": { "type": "string", "minLength": 1 }, "minProperties": 1, "maxProperties": 255, "additionalProperties": { "type": [ "string", "null" ] } } }, "required": [ "type", "instructions", "criteria" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "score" }, "instructions": { "$ref": "#/components/schemas/StructuredJson" }, "criteria": { "minItems": 2, "maxItems": 10, "type": "array", "items": { "type": "string" } } }, "required": [ "type", "instructions", "criteria" ], "additionalProperties": false } ] }, "Attachment": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,63}$" }, "type": { "type": "string", "enum": [ "image", "audio", "document", "video" ] }, "data": { "type": "string", "description": "Served MIME types: image/png, image/jpeg, audio/wav. Aggregate decoded bytes at most 2,621,440. Documents use application/pdf, at most 500 pages. Encrypted PDFs and document references are not supported. Video uses video/mp4, up to 10 seconds and 1920 x 1080. Soundtracks and rotation are refused." } }, "required": [ "name", "type", "data" ], "additionalProperties": false, "description": "Inline media as a canonical base64 data URL: static PNG or JPEG images and 16,000 Hz PCM or float WAV audio. PDF is supported through ordinary inline attachments. Only PDF is supported; other document formats are unavailable. One silent H.264 MP4 video may be sent as the only attachment." }, "StructuredJson": { "description": "Text, or a JSON object or array; every number finite (an integer past 2^53 - 1 reaches the node digit for digit).", "anyOf": [ { "type": "string" }, { "type": "object" }, { "type": "array" } ] }, "DecideReply": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^szd_[a-f0-9]{32}$" }, "model": { "type": "string" }, "served_by": { "type": "string" }, "created": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "context": { "type": "object", "properties": { "route": { "type": "string", "enum": [ "direct" ] }, "tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "route", "tokens" ], "additionalProperties": false }, "answers": { "type": "object", "description": "One entry per question asked, by its name.", "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/Answer" }, { "$ref": "#/components/schemas/QuestionRefusal" } ] } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cached_input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "media_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "long_input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "media_items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "thought_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "input_tokens", "cached_input_tokens", "media_tokens", "long_input_tokens", "media_items", "thought_tokens" ], "additionalProperties": false } }, "required": [ "id", "model", "served_by", "created", "context", "answers", "usage" ], "additionalProperties": false, "description": "Structured confidence v1. Every successful answer requires decision, confidence, alternatives and calibrated; partial metadata and mixed legacy successes are invalid." }, "Answer": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "probability": { "type": "number", "minimum": 0, "maximum": 1, "description": "P(true), even when decision is false. Probabilities use integer millionths; confidence and alternatives preserve the same distribution." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "The model's estimated probability that the selected decision is correct, equal to that outcome's released probability. Not a margin; measured reliability depends on the calibration chart's evaluated scope." }, "calibration_version": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Opaque public calibration identifier, or unpublished when no public identifier is assigned. The same registered calibration keeps the same identifier. An identifier does not prove calibration." }, "preview": { "type": "boolean", "const": true, "description": "Compatibility marker for an answer without attested calibration; preserved on stored replies." }, "decision": { "type": "boolean", "description": "The selected boolean outcome: true when P(true) is at least 0.5, otherwise false. A tie selects true." }, "alternatives": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "decision": { "type": "boolean", "description": "Another allowed outcome, with the same decision type as this answer." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "This outcome's released probability, not the probability that it is the runner-up." } }, "required": [ "decision", "confidence" ], "additionalProperties": false }, "description": "Every other allowed outcome exactly once, including zero-probability outcomes. Sorted by descending integer-millionth probability; choice ties use ascending UTF-8 key bytes and score ties use ascending numeric index. No probability mass is omitted." }, "calibrated": { "type": "boolean", "description": "True only for an exact evidence-backed gateway release attestation matching the concrete model, calibration version, answer type, context route, serving identity, input attachment-type set and outcome count. Answers without attested calibration, including fallback and identity calibration, are false; true does not guarantee future accuracy." } }, "required": [ "type", "probability", "confidence", "calibration_version", "decision", "alternatives", "calibrated" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "choice" }, "choice": { "type": "string" }, "probabilities": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "The complete released distribution in integer millionths, totaling exactly 1000000 units. Confidence equals probabilities[decision]; JSON floating-point sums may use absolute tolerance 0.000001." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "The model's estimated probability that the selected decision is correct, equal to that outcome's released probability. Not a margin; measured reliability depends on the calibration chart's evaluated scope." }, "calibration_version": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Opaque public calibration identifier, or unpublished when no public identifier is assigned. The same registered calibration keeps the same identifier. An identifier does not prove calibration." }, "preview": { "type": "boolean", "const": true, "description": "Compatibility marker for an answer without attested calibration; preserved on stored replies." }, "decision": { "type": "string", "description": "The validated node choice, including its selection among tied maxima; exactly equal to choice." }, "alternatives": { "maxItems": 254, "type": "array", "items": { "type": "object", "properties": { "decision": { "type": "string", "description": "Another allowed outcome, with the same decision type as this answer." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "This outcome's released probability, not the probability that it is the runner-up." } }, "required": [ "decision", "confidence" ], "additionalProperties": false }, "description": "Every other allowed outcome exactly once, including zero-probability outcomes. Sorted by descending integer-millionth probability; choice ties use ascending UTF-8 key bytes and score ties use ascending numeric index. No probability mass is omitted." }, "calibrated": { "type": "boolean", "description": "True only for an exact evidence-backed gateway release attestation matching the concrete model, calibration version, answer type, context route, serving identity, input attachment-type set and outcome count. Answers without attested calibration, including fallback and identity calibration, are false; true does not guarantee future accuracy." } }, "required": [ "type", "choice", "probabilities", "confidence", "calibration_version", "decision", "alternatives", "calibrated" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "score" }, "score": { "type": "number", "description": "Expected level index, rounded to six decimals; it can be fractional. Decision confidence describes exact-level correctness, not distance from this expected score." }, "legend": { "type": "object", "additionalProperties": { "type": "string" } }, "probabilities": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "The complete released distribution in integer millionths, totaling exactly 1000000 units. Confidence equals probabilities[decision]; JSON floating-point sums may use absolute tolerance 0.000001." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "The model's estimated probability that the selected decision is correct, equal to that outcome's released probability. Not a margin; measured reliability depends on the calibration chart's evaluated scope." }, "calibration_version": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Opaque public calibration identifier, or unpublished when no public identifier is assigned. The same registered calibration keeps the same identifier. An identifier does not prove calibration." }, "preview": { "type": "boolean", "const": true, "description": "Compatibility marker for an answer without attested calibration; preserved on stored replies." }, "decision": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "The most likely zero-based decimal level key in legend and probabilities; ties select the lowest numeric index. This is not the expected score or label text." }, "alternatives": { "maxItems": 9, "type": "array", "items": { "type": "object", "properties": { "decision": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "Another allowed outcome, with the same decision type as this answer." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "This outcome's released probability, not the probability that it is the runner-up." } }, "required": [ "decision", "confidence" ], "additionalProperties": false }, "description": "Every other allowed outcome exactly once, including zero-probability outcomes. Sorted by descending integer-millionth probability; choice ties use ascending UTF-8 key bytes and score ties use ascending numeric index. No probability mass is omitted." }, "calibrated": { "type": "boolean", "description": "True only for an exact evidence-backed gateway release attestation matching the concrete model, calibration version, answer type, context route, serving identity, input attachment-type set and outcome count. Answers without attested calibration, including fallback and identity calibration, are false; true does not guarantee future accuracy." } }, "required": [ "type", "score", "legend", "probabilities", "confidence", "calibration_version", "decision", "alternatives", "calibrated" ], "additionalProperties": false } ] }, "LegacyReplayReply": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^szd_[a-f0-9]{32}$" }, "model": { "type": "string" }, "served_by": { "type": "string" }, "created": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "context": { "type": "object", "properties": { "route": { "type": "string", "enum": [ "direct" ] }, "tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "route", "tokens" ], "additionalProperties": false }, "answers": { "type": "object", "description": "All successful answers use the legacy replay shape; no v1 successes may be mixed in.", "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/LegacyAnswer" }, { "$ref": "#/components/schemas/QuestionRefusal" } ] } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cached_input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "media_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "long_input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "media_items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "thought_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "input_tokens", "cached_input_tokens", "media_tokens", "long_input_tokens", "media_items", "thought_tokens" ], "additionalProperties": false } }, "required": [ "id", "model", "served_by", "created", "context", "answers", "usage" ], "additionalProperties": false, "deprecated": true, "description": "Stored pre-v1 reply, with public calibration identifiers, available only on an idempotent replay within its 24-hour retention. Its confidence is a legacy margin and must not be used as decision probability." }, "LegacyAnswer": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "probability": { "type": "number", "minimum": 0, "maximum": 1 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Legacy margin, not the probability of a selected decision. Do not use this value for automation thresholds." }, "calibration_version": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Opaque public calibration identifier, or unpublished when no public identifier is assigned. The same registered calibration keeps the same identifier. An identifier does not prove calibration." }, "preview": { "type": "boolean", "const": true, "description": "Compatibility marker for an answer without attested calibration; preserved on stored replies." } }, "required": [ "type", "probability", "confidence", "calibration_version" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "choice" }, "choice": { "type": "string" }, "probabilities": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 } }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Legacy margin, not the probability of a selected decision. Do not use this value for automation thresholds." }, "calibration_version": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Opaque public calibration identifier, or unpublished when no public identifier is assigned. The same registered calibration keeps the same identifier. An identifier does not prove calibration." }, "preview": { "type": "boolean", "const": true, "description": "Compatibility marker for an answer without attested calibration; preserved on stored replies." } }, "required": [ "type", "choice", "probabilities", "confidence", "calibration_version" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "score" }, "score": { "type": "number" }, "legend": { "type": "object", "additionalProperties": { "type": "string" } }, "probabilities": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 } }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Legacy margin, not the probability of a selected decision. Do not use this value for automation thresholds." }, "calibration_version": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Opaque public calibration identifier, or unpublished when no public identifier is assigned. The same registered calibration keeps the same identifier. An identifier does not prove calibration." }, "preview": { "type": "boolean", "const": true, "description": "Compatibility marker for an answer without attested calibration; preserved on stored replies." } }, "required": [ "type", "score", "legend", "probabilities", "confidence", "calibration_version" ], "additionalProperties": false } ], "deprecated": true }, "QuestionRefusal": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "injection_suspected", "question_not_grounded" ] }, "retryable": { "type": "boolean", "const": false } }, "required": [ "code", "retryable" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "ModelList": { "type": "object", "additionalProperties": false, "required": [ "object", "data" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } }, "Model": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "alias_for", "released_at", "calibration_versions", "limits", "held_routes" ], "properties": { "id": { "type": "string" }, "object": { "const": "model" }, "alias_for": { "type": [ "string", "null" ], "description": "The version the alias system-zero resolves to; null for a version." }, "released_at": { "type": [ "string", "null" ], "format": "date" }, "calibration_versions": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Opaque public calibration identifiers for discovery; null when none are attested. Unregistered calibrations appear as unpublished. A listed identifier is not a per-answer calibrated flag: answer type, route and input coverage must also match." }, "limits": { "type": "object", "additionalProperties": false, "required": [ "state_tokens", "rendered_tokens", "questions", "question_tokens", "question_bytes", "choice_options", "score_levels", "attachments", "body_bytes", "inline_attachment_bytes" ], "properties": { "state_tokens": { "type": "integer", "description": "The longest state one request answers, counted in state tokens. A longer state is refused with 404 long_context_not_available while long_context is held." }, "rendered_tokens": { "type": "integer", "description": "The longest rendered context one request answers, counted in rendered tokens: the state with each question rendered beside it. A longer one is refused with 404 long_context_not_available while long_context is held. Body bytes and the HTTP answer bound still apply independently." }, "questions": { "type": "integer", "description": "The most questions one request may ask." }, "question_tokens": { "type": "integer" }, "question_bytes": { "type": "integer" }, "choice_options": { "type": "object", "properties": { "text": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": [ "min", "max" ], "additionalProperties": false }, "media": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": [ "min", "max" ], "additionalProperties": false } }, "required": [ "text", "media" ], "additionalProperties": false }, "score_levels": { "type": "object", "properties": { "text": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": [ "min", "max" ], "additionalProperties": false }, "media": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": [ "min", "max" ], "additionalProperties": false } }, "required": [ "text", "media" ], "additionalProperties": false }, "attachments": { "type": "integer" }, "images": { "type": "integer" }, "audio": { "type": "integer" }, "body_bytes": { "type": "integer" }, "inline_attachment_bytes": { "type": "integer" } } }, "held_routes": { "type": "array", "items": { "type": "string" } } } }, "ErrorEnvelope": { "type": "object", "additionalProperties": false, "required": [ "error", "request_id" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "message", "type", "param", "code", "retryable" ], "properties": { "message": { "type": "string" }, "type": { "enum": [ "invalid_request_error", "authentication_error", "permission_error", "not_found_error", "rate_limit_error", "overloaded_error", "api_error", "server_error" ] }, "param": { "type": [ "string", "null" ], "description": "The request field the refusal names, in fixed labels: a name a caller chose reads *." }, "code": { "type": [ "string", "null" ] }, "retryable": { "type": "boolean", "description": "Whether the same request, sent again unchanged, can be answered, after Retry-After when the answer names one." }, "details": { "type": "object", "description": "The refusal's machine-readable extras: its cause on a 429, a reset, a limit. A stateless text request refused with 404 long_context_not_available names the served bound in max_state_tokens and max_rendered_tokens." } } }, "request_id": { "type": "string" } } } } } }