{ "openapi": "3.1.0", "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", "info": { "title": "ORBIT public simulation API", "version": "public-simulation-v1", "description": "Fixed simulation endpoints only: no live model answers and no real charges. Requests and responses are strict: unlisted fields are rejected. String lengths are counted in UTF-16 code units." }, "servers": [ { "url": "/", "description": "Your ORBIT service origin (https)." } ], "security": [ { "orbitSimulationKey": [] } ], "paths": { "/api/public-simulation/v1/models": { "get": { "operationId": "listModels", "summary": "Models and sell prices available to this key", "security": [ { "orbitSimulationKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } }, "400": { "description": "Error: PUBLIC_SIMULATION_INVALID, SIMULATION_INVALID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_INVALID", "SIMULATION_INVALID" ] } } } } } ] } } } }, "401": { "description": "Error: PUBLIC_SIMULATION_UNAUTHENTICATED", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_UNAUTHENTICATED" ] } } } } } ] } } } }, "403": { "description": "Error: PUBLIC_SIMULATION_FORBIDDEN, SIMULATION_KEY_INVALID, SIMULATION_KEY_FORBIDDEN, SIMULATION_MODEL_NOT_ALLOWED", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_FORBIDDEN", "SIMULATION_KEY_INVALID", "SIMULATION_KEY_FORBIDDEN", "SIMULATION_MODEL_NOT_ALLOWED" ] } } } } } ] } } } }, "404": { "description": "Error: PUBLIC_SIMULATION_NOT_FOUND, SIMULATION_NOT_FOUND", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_NOT_FOUND", "SIMULATION_NOT_FOUND" ] } } } } } ] } } } }, "405": { "description": "Error: PUBLIC_SIMULATION_INVALID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_INVALID" ] } } } } } ] } } } }, "409": { "description": "Error: SIMULATION_INSUFFICIENT_BALANCE, SIMULATION_ACCOUNT_FROZEN, SIMULATION_KEY_BUDGET, SIMULATION_IDEMPOTENCY_CONFLICT, SIMULATION_CAPACITY", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "SIMULATION_INSUFFICIENT_BALANCE", "SIMULATION_ACCOUNT_FROZEN", "SIMULATION_KEY_BUDGET", "SIMULATION_IDEMPOTENCY_CONFLICT", "SIMULATION_CAPACITY" ] } } } } } ] } } } }, "413": { "description": "Error: PUBLIC_SIMULATION_INVALID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_INVALID" ] } } } } } ] } } } }, "429": { "description": "Error: PUBLIC_SIMULATION_RATE_LIMITED, SIMULATION_QUOTA", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_RATE_LIMITED", "SIMULATION_QUOTA" ] } } } } } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before sending a new request.", "schema": { "type": "integer", "minimum": 1, "maximum": 3600 } } } }, "502": { "description": "Error: PUBLIC_SIMULATION_UNAVAILABLE", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_UNAVAILABLE" ] } } } } } ] } } } }, "503": { "description": "Error: PUBLIC_SIMULATION_UNAVAILABLE", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_UNAVAILABLE" ] } } } } } ] } } } } } } }, "/api/public-simulation/v1/generate": { "post": { "operationId": "generate", "summary": "Submit one simulated call (requestId is the idempotency key)", "security": [ { "orbitSimulationKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ack" } } } }, "400": { "description": "Error: PUBLIC_SIMULATION_INVALID, SIMULATION_INVALID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_INVALID", "SIMULATION_INVALID" ] } } } } } ] } } } }, "401": { "description": "Error: PUBLIC_SIMULATION_UNAUTHENTICATED", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_UNAUTHENTICATED" ] } } } } } ] } } } }, "403": { "description": "Error: PUBLIC_SIMULATION_FORBIDDEN, SIMULATION_KEY_INVALID, SIMULATION_KEY_FORBIDDEN, SIMULATION_MODEL_NOT_ALLOWED", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_FORBIDDEN", "SIMULATION_KEY_INVALID", "SIMULATION_KEY_FORBIDDEN", "SIMULATION_MODEL_NOT_ALLOWED" ] } } } } } ] } } } }, "404": { "description": "Error: PUBLIC_SIMULATION_NOT_FOUND, SIMULATION_NOT_FOUND", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_NOT_FOUND", "SIMULATION_NOT_FOUND" ] } } } } } ] } } } }, "405": { "description": "Error: PUBLIC_SIMULATION_INVALID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_INVALID" ] } } } } } ] } } } }, "409": { "description": "Error: SIMULATION_INSUFFICIENT_BALANCE, SIMULATION_ACCOUNT_FROZEN, SIMULATION_KEY_BUDGET, SIMULATION_IDEMPOTENCY_CONFLICT, SIMULATION_CAPACITY", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "SIMULATION_INSUFFICIENT_BALANCE", "SIMULATION_ACCOUNT_FROZEN", "SIMULATION_KEY_BUDGET", "SIMULATION_IDEMPOTENCY_CONFLICT", "SIMULATION_CAPACITY" ] } } } } } ] } } } }, "413": { "description": "Error: PUBLIC_SIMULATION_INVALID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_INVALID" ] } } } } } ] } } } }, "415": { "description": "Error: PUBLIC_SIMULATION_INVALID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_INVALID" ] } } } } } ] } } } }, "429": { "description": "Error: PUBLIC_SIMULATION_RATE_LIMITED, SIMULATION_QUOTA", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_RATE_LIMITED", "SIMULATION_QUOTA" ] } } } } } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before sending a new request.", "schema": { "type": "integer", "minimum": 1, "maximum": 3600 } } } }, "502": { "description": "Error: PUBLIC_SIMULATION_UNAVAILABLE", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_UNAVAILABLE" ] } } } } } ] } } } }, "503": { "description": "Error: PUBLIC_SIMULATION_UNAVAILABLE", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_UNAVAILABLE" ] } } } } } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateRequest" } } } }, "x-orbit-idempotency": { "key": "requestId", "replay": "Same requestId and identical body returns the original record with replayed true.", "conflict": "Same requestId with a different body returns 409 SIMULATION_IDEMPOTENCY_CONFLICT." } } }, "/api/public-simulation/v1/request": { "get": { "operationId": "lookupRequest", "summary": "Read the stored record of a requestId (read-only, never executes)", "security": [ { "orbitSimulationKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lookup" } } } }, "400": { "description": "Error: PUBLIC_SIMULATION_INVALID, SIMULATION_INVALID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_INVALID", "SIMULATION_INVALID" ] } } } } } ] } } } }, "401": { "description": "Error: PUBLIC_SIMULATION_UNAUTHENTICATED", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_UNAUTHENTICATED" ] } } } } } ] } } } }, "403": { "description": "Error: PUBLIC_SIMULATION_FORBIDDEN, SIMULATION_KEY_INVALID, SIMULATION_KEY_FORBIDDEN, SIMULATION_MODEL_NOT_ALLOWED", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_FORBIDDEN", "SIMULATION_KEY_INVALID", "SIMULATION_KEY_FORBIDDEN", "SIMULATION_MODEL_NOT_ALLOWED" ] } } } } } ] } } } }, "404": { "description": "Error: PUBLIC_SIMULATION_NOT_FOUND, SIMULATION_NOT_FOUND", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_NOT_FOUND", "SIMULATION_NOT_FOUND" ] } } } } } ] } } } }, "405": { "description": "Error: PUBLIC_SIMULATION_INVALID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_INVALID" ] } } } } } ] } } } }, "409": { "description": "Error: SIMULATION_INSUFFICIENT_BALANCE, SIMULATION_ACCOUNT_FROZEN, SIMULATION_KEY_BUDGET, SIMULATION_IDEMPOTENCY_CONFLICT, SIMULATION_CAPACITY", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "SIMULATION_INSUFFICIENT_BALANCE", "SIMULATION_ACCOUNT_FROZEN", "SIMULATION_KEY_BUDGET", "SIMULATION_IDEMPOTENCY_CONFLICT", "SIMULATION_CAPACITY" ] } } } } } ] } } } }, "413": { "description": "Error: PUBLIC_SIMULATION_INVALID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_INVALID" ] } } } } } ] } } } }, "429": { "description": "Error: PUBLIC_SIMULATION_RATE_LIMITED, SIMULATION_QUOTA", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_RATE_LIMITED", "SIMULATION_QUOTA" ] } } } } } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before sending a new request.", "schema": { "type": "integer", "minimum": 1, "maximum": 3600 } } } }, "502": { "description": "Error: PUBLIC_SIMULATION_UNAVAILABLE", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_UNAVAILABLE" ] } } } } } ] } } } }, "503": { "description": "Error: PUBLIC_SIMULATION_UNAVAILABLE", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_UNAVAILABLE" ] } } } } } ] } } } } }, "parameters": [ { "name": "requestId", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "format": "uuid" } } ] } }, "/api/public-simulation/v1/stream": { "post": { "operationId": "stream", "summary": "Submit one simulated call as a stream; a replayed requestId returns the JSON receipt", "security": [ { "orbitSimulationKey": [] } ], "responses": { "200": { "description": "OK", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/StreamFrame" }, "x-orbit-framing": "Each frame is one \"data:\" line holding JSON, then a blank line. No event, id or retry fields. Order: start, delta*, fault?, result, end. The record is final only after result, end and a clean close." }, "application/json": { "schema": { "$ref": "#/components/schemas/Ack" }, "x-orbit-note": "Replay of an earlier stream with the same requestId (replayed is true)." } } }, "400": { "description": "Error: PUBLIC_SIMULATION_INVALID, SIMULATION_INVALID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_INVALID", "SIMULATION_INVALID" ] } } } } } ] } } } }, "401": { "description": "Error: PUBLIC_SIMULATION_UNAUTHENTICATED", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_UNAUTHENTICATED" ] } } } } } ] } } } }, "403": { "description": "Error: PUBLIC_SIMULATION_FORBIDDEN, SIMULATION_KEY_INVALID, SIMULATION_KEY_FORBIDDEN, SIMULATION_MODEL_NOT_ALLOWED", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_FORBIDDEN", "SIMULATION_KEY_INVALID", "SIMULATION_KEY_FORBIDDEN", "SIMULATION_MODEL_NOT_ALLOWED" ] } } } } } ] } } } }, "404": { "description": "Error: PUBLIC_SIMULATION_NOT_FOUND, SIMULATION_NOT_FOUND", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_NOT_FOUND", "SIMULATION_NOT_FOUND" ] } } } } } ] } } } }, "405": { "description": "Error: PUBLIC_SIMULATION_INVALID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_INVALID" ] } } } } } ] } } } }, "409": { "description": "Error: SIMULATION_INSUFFICIENT_BALANCE, SIMULATION_ACCOUNT_FROZEN, SIMULATION_KEY_BUDGET, SIMULATION_IDEMPOTENCY_CONFLICT, SIMULATION_CAPACITY", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "SIMULATION_INSUFFICIENT_BALANCE", "SIMULATION_ACCOUNT_FROZEN", "SIMULATION_KEY_BUDGET", "SIMULATION_IDEMPOTENCY_CONFLICT", "SIMULATION_CAPACITY" ] } } } } } ] } } } }, "413": { "description": "Error: PUBLIC_SIMULATION_INVALID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_INVALID" ] } } } } } ] } } } }, "415": { "description": "Error: PUBLIC_SIMULATION_INVALID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_INVALID" ] } } } } } ] } } } }, "429": { "description": "Error: PUBLIC_SIMULATION_RATE_LIMITED, SIMULATION_QUOTA", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_RATE_LIMITED", "SIMULATION_QUOTA" ] } } } } } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before sending a new request.", "schema": { "type": "integer", "minimum": 1, "maximum": 3600 } } } }, "502": { "description": "Error: PUBLIC_SIMULATION_UNAVAILABLE", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_UNAVAILABLE" ] } } } } } ] } } } }, "503": { "description": "Error: PUBLIC_SIMULATION_UNAVAILABLE", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "properties": { "error": { "properties": { "code": { "enum": [ "PUBLIC_SIMULATION_UNAVAILABLE" ] } } } } } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamRequest" } } } }, "x-orbit-idempotency": { "key": "requestId", "replay": "Same requestId and identical body returns the original record with replayed true.", "conflict": "Same requestId with a different body returns 409 SIMULATION_IDEMPOTENCY_CONFLICT." } } } }, "components": { "securitySchemes": { "orbitSimulationKey": { "type": "http", "scheme": "bearer", "bearerFormat": "orb_sim_ followed by 72 lowercase hex characters (80 characters)" } }, "schemas": { "GenerateRequest": { "type": "object", "properties": { "mode": { "type": "string", "const": "simulation" }, "requestId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "format": "uuid" }, "model": { "type": "string", "enum": [ "sim-general", "sim-reasoning" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Leading and trailing whitespace is removed before the length check; send 1 to 500 characters of visible text." }, "maxOutputTokens": { "type": "integer", "minimum": 1, "maximum": 256 }, "scenario": { "type": "string", "enum": [ "success", "upstream_error", "timeout_unknown", "missing_usage", "overusage" ] } }, "required": [ "mode", "requestId", "model", "message", "maxOutputTokens", "scenario" ], "additionalProperties": false }, "StreamRequest": { "type": "object", "properties": { "mode": { "type": "string", "const": "simulation" }, "requestId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "format": "uuid" }, "model": { "type": "string", "enum": [ "sim-general", "sim-reasoning" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Leading and trailing whitespace is removed before the length check; send 1 to 500 characters of visible text." }, "maxOutputTokens": { "type": "integer", "minimum": 1, "maximum": 256 }, "scenario": { "type": "string", "enum": [ "success", "upstream_error", "timeout_unknown", "missing_usage", "overusage", "stream_disconnect" ] } }, "required": [ "mode", "requestId", "model", "message", "maxOutputTokens", "scenario" ], "additionalProperties": false }, "ModelList": { "type": "object", "properties": { "mode": { "type": "string", "const": "simulation" }, "models": { "type": "array", "maxItems": 2, "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "sim-general", "sim-reasoning" ] }, "priceVersion": { "type": "string", "enum": [ "sim-general-v1", "sim-reasoning-v1" ] }, "inputMicroPerMillion": { "type": "string", "pattern": "^[0-9]+$", "description": "Non-negative integer in micro-units, as a decimal string." }, "cachedMicroPerMillion": { "type": "string", "pattern": "^[0-9]+$", "description": "Non-negative integer in micro-units, as a decimal string." }, "outputMicroPerMillion": { "type": "string", "pattern": "^[0-9]+$", "description": "Non-negative integer in micro-units, as a decimal string." } }, "required": [ "id", "priceVersion", "inputMicroPerMillion", "cachedMicroPerMillion", "outputMicroPerMillion" ], "additionalProperties": false } } }, "required": [ "mode", "models" ], "additionalProperties": false }, "Ack": { "type": "object", "properties": { "mode": { "type": "string", "const": "simulation" }, "replayed": { "type": "boolean" }, "record": { "$ref": "#/components/schemas/SimulationRecord" } }, "required": [ "mode", "replayed", "record" ], "additionalProperties": false }, "Lookup": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "simulation" }, "state": { "type": "string", "const": "not_found" } }, "required": [ "mode", "state" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "simulation" }, "state": { "type": "string", "const": "found" }, "record": { "$ref": "#/components/schemas/SimulationRecord" } }, "required": [ "mode", "state", "record" ], "additionalProperties": false } ] }, "SimulationRecord": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "format": "uuid" }, "requestId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "format": "uuid" }, "keyId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "format": "uuid" }, "usageId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "format": "uuid" }, "model": { "type": "string", "enum": [ "sim-general", "sim-reasoning" ] }, "priceVersion": { "type": "string", "enum": [ "sim-general-v1", "sim-reasoning-v1" ] }, "maxOutputTokens": { "type": "integer", "minimum": 1, "maximum": 256 }, "state": { "type": "string", "enum": [ "running", "settled", "released", "review" ] }, "reason": { "type": "string", "enum": [ "provider_pending", "metered", "confirmed_not_executed", "usage_unknown", "usage_exceeds_contract" ] }, "meter": { "oneOf": [ { "$ref": "#/components/schemas/Meter" }, { "type": "null" } ] }, "cost": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]{0,29})$", "description": "Non-negative integer in micro-units, as a decimal string." }, "reserved": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,29})$", "description": "Non-negative integer in micro-units, as a decimal string." }, "actual": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]{0,29})$", "description": "Non-negative integer in micro-units, as a decimal string." }, "usageState": { "type": "string", "enum": [ "held", "settled", "released" ] }, "createdAt": { "type": "string", "maxLength": 32, "pattern": "^((\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-((0[13578]|1[02])-(0[1-9]|[12]\\d|3[01])|(0[469]|11)-(0[1-9]|[12]\\d|30)|(02)-(0[1-9]|1\\d|2[0-8])))T([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d(\\.\\d+)?)?(Z)$", "format": "date-time" }, "updatedAt": { "type": "string", "maxLength": 32, "pattern": "^((\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-((0[13578]|1[02])-(0[1-9]|[12]\\d|3[01])|(0[469]|11)-(0[1-9]|[12]\\d|30)|(02)-(0[1-9]|1\\d|2[0-8])))T([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d(\\.\\d+)?)?(Z)$", "format": "date-time" }, "transport": { "type": "string", "enum": [ "json", "stream" ] }, "streamStatus": { "type": [ "string", "null" ], "enum": [ "finished", "client_cancelled", "upstream_interrupted", "usage_missing", "deadline_exceeded", "protocol_error", null ] } }, "required": [ "id", "requestId", "keyId", "usageId", "model", "priceVersion", "maxOutputTokens", "state", "reason", "meter", "cost", "reserved", "actual", "usageState", "createdAt", "updatedAt", "transport", "streamStatus" ], "additionalProperties": false, "x-orbit-refinement": "model and priceVersion agree; state, usageState, cost and actual follow the accounting rules (settled: cost = actual, meter present; released: cost = actual = \"0\"; running/review: usageState held, cost and actual null)." }, "Meter": { "type": "object", "properties": { "input": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "cached": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "output": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, "required": [ "input", "cached", "output" ], "additionalProperties": false, "x-orbit-refinement": "cached is not greater than input." }, "StreamFrame": { "oneOf": [ { "$ref": "#/components/schemas/StreamStartFrame" }, { "$ref": "#/components/schemas/StreamDeltaFrame" }, { "$ref": "#/components/schemas/StreamFaultFrame" }, { "$ref": "#/components/schemas/StreamResultFrame" }, { "$ref": "#/components/schemas/StreamEndFrame" } ], "discriminator": { "propertyName": "type", "mapping": { "start": "#/components/schemas/StreamStartFrame", "delta": "#/components/schemas/StreamDeltaFrame", "fault": "#/components/schemas/StreamFaultFrame", "result": "#/components/schemas/StreamResultFrame", "end": "#/components/schemas/StreamEndFrame" } } }, "StreamStartFrame": { "type": "object", "properties": { "type": { "type": "string", "const": "start" }, "mode": { "type": "string", "const": "simulation" }, "requestId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "format": "uuid" }, "generationId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "format": "uuid" }, "keyId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "format": "uuid" }, "model": { "type": "string", "enum": [ "sim-general", "sim-reasoning" ] }, "maxOutputTokens": { "type": "integer", "minimum": 1, "maximum": 256 } }, "required": [ "type", "mode", "requestId", "generationId", "keyId", "model", "maxOutputTokens" ], "additionalProperties": false }, "StreamDeltaFrame": { "type": "object", "properties": { "type": { "type": "string", "const": "delta" }, "mode": { "type": "string", "const": "simulation" }, "text": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "type", "mode", "text" ], "additionalProperties": false, "x-orbit-refinement": "text is at most 4096 bytes as UTF-8." }, "StreamFaultFrame": { "type": "object", "properties": { "type": { "type": "string", "const": "fault" }, "mode": { "type": "string", "const": "simulation" }, "code": { "type": "string", "enum": [ "STREAM_CANCELLED", "STREAM_INTERRUPTED", "STREAM_USAGE_MISSING", "STREAM_DEADLINE", "STREAM_PROTOCOL", "STREAM_UNAVAILABLE" ] } }, "required": [ "type", "mode", "code" ], "additionalProperties": false }, "StreamResultFrame": { "type": "object", "properties": { "type": { "type": "string", "const": "result" }, "mode": { "type": "string", "const": "simulation" }, "record": { "$ref": "#/components/schemas/SimulationRecord" } }, "required": [ "type", "mode", "record" ], "additionalProperties": false, "x-orbit-refinement": "record.transport is \"stream\", record.state is not \"running\" and record.streamStatus is not null." }, "StreamEndFrame": { "type": "object", "properties": { "type": { "type": "string", "const": "end" }, "mode": { "type": "string", "const": "simulation" }, "generationId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "format": "uuid" } }, "required": [ "type", "mode", "generationId" ], "additionalProperties": false }, "ErrorBody": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "execution" ], "properties": { "code": { "type": "string", "maxLength": 80, "enum": [ "PUBLIC_SIMULATION_FORBIDDEN", "PUBLIC_SIMULATION_INVALID", "PUBLIC_SIMULATION_NOT_FOUND", "PUBLIC_SIMULATION_RATE_LIMITED", "PUBLIC_SIMULATION_UNAUTHENTICATED", "PUBLIC_SIMULATION_UNAVAILABLE", "SIMULATION_ACCOUNT_FROZEN", "SIMULATION_CAPACITY", "SIMULATION_IDEMPOTENCY_CONFLICT", "SIMULATION_INSUFFICIENT_BALANCE", "SIMULATION_INVALID", "SIMULATION_KEY_BUDGET", "SIMULATION_KEY_FORBIDDEN", "SIMULATION_KEY_INVALID", "SIMULATION_MODEL_NOT_ALLOWED", "SIMULATION_NOT_FOUND", "SIMULATION_QUOTA" ] }, "execution": { "type": "string", "enum": [ "not_started", "unknown" ], "description": "not_started: confirmed not started, nothing reserved or charged. unknown: may have run; keep requestId and only GET /request." } } } } } } }, "x-orbit-masked-errors": [ { "code": "PUBLIC_SIMULATION_DISABLED", "internalStatus": 503, "arrivesAs": { "status": 502, "code": "PUBLIC_SIMULATION_UNAVAILABLE", "execution": "unknown" } }, { "code": "SIMULATION_INTEGRITY", "internalStatus": 503, "arrivesAs": { "status": 502, "code": "PUBLIC_SIMULATION_UNAVAILABLE", "execution": "unknown" } }, { "code": "SIMULATION_UNAVAILABLE", "internalStatus": 503, "arrivesAs": { "status": 502, "code": "PUBLIC_SIMULATION_UNAVAILABLE", "execution": "unknown" } } ], "x-orbit-stream-faults": [ "STREAM_CANCELLED", "STREAM_INTERRUPTED", "STREAM_USAGE_MISSING", "STREAM_DEADLINE", "STREAM_PROTOCOL", "STREAM_UNAVAILABLE" ], "x-orbit-limits": { "credentialPerWindow": 30, "globalPerWindow": 120, "windowSeconds": 60, "maxInFlight": 32, "entryTimeoutSeconds": 15, "maxRequestBytes": 8192, "maxResponseBytes": 16384, "streamWireBytes": 65536, "streamFrames": 128, "streamTextBytes": 4096, "reservationInputTokens": 512 }, "x-orbit-retry": { "automatic": "Only 429 with execution not_started (after Retry-After), and read-only GETs that failed in transit or got 502/503 PUBLIC_SIMULATION_UNAVAILABLE.", "never": "Never re-send a POST whose outcome is unknown (execution unknown, timeout, dropped connection, malformed response, cut stream). Check it with GET /request using the same requestId." } }