{ "openapi": "3.1.0", "info": { "title": "Blueprint Robot-Team Agent API", "version": "2026-05-21", "summary": "Headless catalog, site-world, dry-run commerce, hosted-session, explorer-render, and export contract for robot-team agents.", "description": "Blueprint exposes capture-backed site-world catalog, dry-run quote/order/entitlement proof, and hosted-session endpoints for robot-team agents. Public demo calls may run without privileged credentials only when a demo site world is enabled. Protected robot-team flows use the existing Firebase bearer path and require robot_team/admin outer auth plus session ownership or a matching provisioned entitlement." }, "servers": [ { "url": "https://tryblueprint.io", "description": "Production public origin. Protected flows require a scoped robot-team/admin bearer token." }, { "url": "http://localhost:5000", "description": "Local development server. Public demo flow can run without auth when demo site worlds are enabled." } ], "tags": [ { "name": "Discovery", "description": "Public site and API discovery for agents." }, { "name": "Catalog", "description": "Public site-world catalog and detail endpoints." }, { "name": "Agent commerce", "description": "Dry-run quote, order, receipt, and entitlement proof. Does not call live Stripe." }, { "name": "Hosted sessions", "description": "Session lifecycle, rollout, render, and export endpoints." } ], "paths": { "/api/site-content": { "get": { "tags": [ "Discovery" ], "operationId": "discoverBlueprint", "summary": "Discover public Blueprint pages, llms files, and machine-readable resources.", "security": [ {} ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteContentResponse" } } } } } } }, "/api/site-worlds": { "get": { "tags": [ "Catalog" ], "operationId": "listSiteWorlds", "summary": "List public site-world catalog entries.", "security": [ {} ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteWorldListResponse" } } } } } } }, "/api/site-worlds/search": { "get": { "tags": [ "Catalog" ], "operationId": "searchSiteWorlds", "summary": "Search public site-world catalog entries by natural language query, alias, and structured filters.", "description": "Public read-only catalog discovery for robot-team agents. Queries such as whole foods, store, supermarket, retail aisle, or warehouse tote return truthful close matches with scores, reasons, matched aliases, matched fields, parsed filters, warnings, and embedding-use metadata. Brand aliases do not imply exact partner or package availability.", "security": [ {} ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "examples": { "wholeFoods": { "value": "whole foods" }, "store": { "value": "store" }, "warehouseTote": { "value": "warehouse tote" } } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "industry", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "siteType", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "taskLane", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "objectTags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated required object tags, for example tote,pallet." }, { "name": "robot", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "availability", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "readiness", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "relevance", "name", "city", "category", "readiness", "availability" ], "default": "relevance" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteWorldSearchResponse" } } } } }, "x-blueprint-truth-boundary": "This endpoint is public catalog discovery only. It does not grant hosted-session access, buyer entitlement, private artifact access, or exact brand/site availability." } }, "/api/site-worlds/{siteWorldId}": { "get": { "tags": [ "Catalog" ], "operationId": "getSiteWorld", "summary": "Get one public site-world detail record.", "security": [ {} ], "parameters": [ { "$ref": "#/components/parameters/SiteWorldId" } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteWorld" } } } }, "404": { "description": "Requested site world or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/site-worlds/sessions/launch-readiness": { "get": { "tags": [ "Hosted sessions" ], "operationId": "getLaunchReadiness", "summary": "Inspect launch readiness for a site world before creating a hosted session.", "security": [ {}, { "BlueprintBearer": [] } ], "parameters": [ { "name": "siteWorldId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchReadiness" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated account is not allowed to launch protected hosted sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Requested site world or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Launch or runtime operation is blocked by current readiness, access, or session state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchBlockedResponse" } } } } }, "x-blueprint-public-demo": true } }, "/api/agent-access/commerce/quote": { "get": { "tags": [ "Agent commerce" ], "operationId": "quoteAgentCommerce", "summary": "Quote a site-world package or hosted-session rental for agent planning.", "security": [ {} ], "parameters": [ { "name": "siteWorldId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "product", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "site_world_package", "hosted_session_rental" ], "default": "hosted_session_rental" } }, { "name": "sessionHours", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCommerceQuoteResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-blueprint-dry-run-only": true, "x-blueprint-truth-boundary": "Quotes are planning artifacts. They do not create live Stripe sessions, charge cards, grant live package access, or prove rights clearance." } }, "/api/agent-access/commerce/dry-run-checkout": { "post": { "tags": [ "Agent commerce" ], "operationId": "createAgentDryRunCheckout", "summary": "Create a dry-run order and provisioned entitlement without live Stripe.", "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDryRunCheckoutRequest" } } } }, "responses": { "201": { "description": "Dry-run order created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDryRunOrderResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-blueprint-dry-run-only": true, "x-blueprint-truth-boundary": "This route reuses buyerOrders and marketplaceEntitlements response shapes for local/test proof only. It never calls live Stripe or opens live package access." } }, "/api/agent-access/commerce/orders/{orderId}": { "get": { "tags": [ "Agent commerce" ], "operationId": "getAgentDryRunOrder", "summary": "Read a dry-run order and receipt.", "security": [ {} ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDryRunOrderResponse" } } } }, "404": { "description": "Requested site world or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-blueprint-dry-run-only": true } }, "/api/agent-access/commerce/entitlements/{entitlementId}": { "get": { "tags": [ "Agent commerce" ], "operationId": "getAgentDryRunEntitlement", "summary": "Read a dry-run marketplace entitlement.", "security": [ {} ], "parameters": [ { "name": "entitlementId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEntitlementResponse" } } } }, "404": { "description": "Requested site world or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-blueprint-dry-run-only": true } }, "/api/agent-access/commerce/entitlement-readiness": { "get": { "tags": [ "Agent commerce" ], "operationId": "getAgentEntitlementReadiness", "summary": "Check whether a provisioned entitlement would unlock protected hosted-session launch.", "security": [ {} ], "parameters": [ { "name": "siteWorldId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "entitlementId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "buyerUserId", "in": "query", "required": false, "schema": { "type": "string", "default": "agent-dry-run-buyer" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEntitlementReadiness" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-blueprint-dry-run-only": true, "x-blueprint-truth-boundary": "Entitlement readiness proves commerce linkage only. Runtime launch, rights, provider execution, and package fulfillment still require their owning systems." } }, "/api/site-worlds/sessions": { "post": { "tags": [ "Hosted sessions" ], "operationId": "createHostedSession", "summary": "Create a hosted session for a public demo site world or protected robot-team account.", "security": [ {}, { "BlueprintBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHostedSessionRequest" } } } }, "responses": { "200": { "description": "Reusable presentation-demo session returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHostedSessionResponse" } } } }, "201": { "description": "Session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHostedSessionResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated account is not allowed to launch protected hosted sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Requested site world or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Launch or runtime operation is blocked by current readiness, access, or session state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchBlockedResponse" } } } } }, "x-blueprint-public-demo": true, "x-blueprint-truth-boundary": "Public unauthenticated creation applies only to demo-eligible site worlds. Protected site worlds continue through Firebase robot_team/admin checks plus provisioned entitlement or existing session ownership." } }, "/api/site-worlds/sessions/{sessionId}": { "get": { "tags": [ "Hosted sessions" ], "operationId": "getHostedSession", "summary": "Read a hosted session record.", "security": [ {}, { "BlueprintBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostedSession" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated account is not allowed to launch protected hosted sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Requested site world or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Launch or runtime operation is blocked by current readiness, access, or session state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchBlockedResponse" } } } } }, "x-blueprint-public-demo": true } }, "/api/site-worlds/sessions/{sessionId}/reset": { "post": { "tags": [ "Hosted sessions" ], "operationId": "resetHostedSession", "summary": "Reset scenario, start state, task, and seed for a hosted rollout.", "security": [ { "BlueprintBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetHostedSessionRequest" } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostedSessionOperationResponse" } } } }, "202": { "description": "Accepted for async runtime mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingOperationResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated account is not allowed to launch protected hosted sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Requested site world or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Launch or runtime operation is blocked by current readiness, access, or session state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchBlockedResponse" } } } } }, "x-blueprint-public-demo": true, "x-blueprint-truth-boundary": "Unauthenticated use applies only when the session belongs to a public-demo site world. Protected site worlds require bearer auth and preserve Firebase entitlement checks." } }, "/api/site-worlds/sessions/{sessionId}/step": { "post": { "tags": [ "Hosted sessions" ], "operationId": "stepHostedSession", "summary": "Advance one rollout step with an action or autopolicy request.", "security": [ { "BlueprintBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepHostedSessionRequest" } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostedSessionOperationResponse" } } } }, "202": { "description": "Accepted for async runtime mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingOperationResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated account is not allowed to launch protected hosted sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Requested site world or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Launch or runtime operation is blocked by current readiness, access, or session state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchBlockedResponse" } } } } }, "x-blueprint-public-demo": true, "x-blueprint-truth-boundary": "Unauthenticated use applies only when the session belongs to a public-demo site world. Protected site worlds require bearer auth and preserve Firebase entitlement checks." } }, "/api/site-worlds/sessions/{sessionId}/run-batch": { "post": { "tags": [ "Hosted sessions" ], "operationId": "runBatchHostedSession", "summary": "Run a headless batch rollout and return summary/artifact references.", "security": [ { "BlueprintBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunBatchRequest" } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostedSessionOperationResponse" } } } }, "202": { "description": "Accepted for async runtime mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingOperationResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated account is not allowed to launch protected hosted sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Requested site world or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Launch or runtime operation is blocked by current readiness, access, or session state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchBlockedResponse" } } } } }, "x-blueprint-public-demo": true, "x-blueprint-truth-boundary": "Unauthenticated use applies only when the session belongs to a public-demo site world. Protected site worlds require bearer auth and preserve Firebase entitlement checks." } }, "/api/site-worlds/sessions/{sessionId}/control": { "post": { "tags": [ "Hosted sessions" ], "operationId": "controlHostedSession", "summary": "Send runtime control intent for camera, policy, or playback state.", "security": [ { "BlueprintBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControlRequest" } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostedSessionOperationResponse" } } } }, "202": { "description": "Accepted for async runtime mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingOperationResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated account is not allowed to launch protected hosted sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Requested site world or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Launch or runtime operation is blocked by current readiness, access, or session state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchBlockedResponse" } } } } }, "x-blueprint-public-demo": true, "x-blueprint-truth-boundary": "Unauthenticated use applies only when the session belongs to a public-demo site world. Protected site worlds require bearer auth and preserve Firebase entitlement checks." } }, "/api/site-worlds/sessions/{sessionId}/render": { "get": { "tags": [ "Hosted sessions" ], "operationId": "renderHostedSessionFrame", "summary": "Render a robot-observation frame for the selected camera.", "security": [ {}, { "BlueprintBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionId" }, { "name": "cameraId", "in": "query", "required": false, "schema": { "type": "string", "default": "head_rgb" } } ], "responses": { "200": { "description": "Rendered frame or fallback artifact frame.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated account is not allowed to launch protected hosted sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Requested site world or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Launch or runtime operation is blocked by current readiness, access, or session state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchBlockedResponse" } } } } }, "x-blueprint-public-demo": true } }, "/api/site-worlds/sessions/{sessionId}/explorer-render": { "post": { "tags": [ "Hosted sessions" ], "operationId": "renderHostedSessionExplorer", "summary": "Render an explorer frame from a requested camera pose.", "security": [ { "BlueprintBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExplorerRenderRequest" } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostedSessionOperationResponse" } } } }, "202": { "description": "Accepted for async runtime mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingOperationResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated account is not allowed to launch protected hosted sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Requested site world or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Launch or runtime operation is blocked by current readiness, access, or session state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchBlockedResponse" } } } } }, "x-blueprint-public-demo": true, "x-blueprint-truth-boundary": "Unauthenticated use applies only when the session belongs to a public-demo site world. Protected site worlds require bearer auth and preserve Firebase entitlement checks." } }, "/api/site-worlds/sessions/{sessionId}/explorer-frame": { "get": { "tags": [ "Hosted sessions" ], "operationId": "getHostedSessionExplorerFrame", "summary": "Fetch the latest explorer-rendered PNG frame.", "security": [ {}, { "BlueprintBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionId" }, { "name": "cameraId", "in": "query", "required": false, "schema": { "type": "string", "default": "head_rgb" } } ], "responses": { "200": { "description": "Explorer-rendered PNG frame.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated account is not allowed to launch protected hosted sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Requested site world or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Launch or runtime operation is blocked by current readiness, access, or session state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchBlockedResponse" } } } } }, "x-blueprint-public-demo": true } }, "/api/site-worlds/sessions/{sessionId}/export": { "post": { "tags": [ "Hosted sessions" ], "operationId": "exportHostedSession", "summary": "Export session dataset artifacts and manifest references.", "security": [ { "BlueprintBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostedSessionOperationResponse" } } } }, "202": { "description": "Accepted for async runtime mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingOperationResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Authenticated account is not allowed to launch protected hosted sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Requested site world or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Launch or runtime operation is blocked by current readiness, access, or session state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchBlockedResponse" } } } } }, "x-blueprint-public-demo": true, "x-blueprint-truth-boundary": "Unauthenticated use applies only when the session belongs to a public-demo site world. Protected site worlds require bearer auth and preserve Firebase entitlement checks." } } }, "components": { "securitySchemes": { "BlueprintBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "Firebase ID token or future scoped robot-team machine token", "description": "Protected flows currently use Firebase Admin token verification. The bearer must resolve to an admin user or a user profile with buyerType robot_team." } }, "parameters": { "SiteWorldId": { "name": "siteWorldId", "in": "path", "required": true, "schema": { "type": "string" } }, "SessionId": { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } }, "schemas": { "TruthLabel": { "type": "string", "enum": [ "capture_grounded", "provider_derived", "generated", "sample_demo", "public_demo_eligible", "request_gated", "protected_robot_team", "dry_run_order" ] }, "AgentCommerceProduct": { "type": "string", "enum": [ "site_world_package", "hosted_session_rental" ] }, "StatusLabel": { "type": "string", "enum": [ "ready", "launchable", "blocked", "running", "completed", "failed", "request_gated", "not_configured" ] }, "SiteContentResponse": { "type": "object", "required": [ "summary", "definitions", "pages", "machineReadableFiles" ], "properties": { "summary": { "type": "string" }, "definitions": { "type": "array", "items": { "type": "object" } }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/PublicPage" } }, "queryThemes": { "type": "array", "items": { "type": "string" } }, "privateOrNoindex": { "type": "array", "items": { "type": "string" } }, "machineReadableFiles": { "type": "object", "additionalProperties": { "type": "string" } } } }, "PublicPage": { "type": "object", "required": [ "path", "title", "description" ], "properties": { "path": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" } } }, "SiteWorldListResponse": { "type": "object", "required": [ "items", "count" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteWorld" } }, "count": { "type": "integer" } } }, "SiteWorldSearchResponse": { "type": "object", "required": [ "query", "results", "parsed", "appliedFilters", "warnings", "meta" ], "properties": { "query": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SiteWorldSearchResult" } }, "parsed": { "$ref": "#/components/schemas/SiteWorldSearchParsed" }, "appliedFilters": { "$ref": "#/components/schemas/SiteWorldSearchFilters" }, "warnings": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/SiteWorldSearchMeta" } } }, "SiteWorldSearchResult": { "type": "object", "required": [ "siteWorld", "score", "reasons", "matchedAliases", "matchedFields" ], "properties": { "siteWorld": { "$ref": "#/components/schemas/SiteWorld" }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } }, "matchedAliases": { "type": "array", "items": { "type": "string" } }, "matchedFields": { "type": "array", "items": { "type": "string" } } } }, "SiteWorldSearchParsed": { "type": "object", "required": [ "q", "tokens", "aliases", "filters" ], "properties": { "q": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "string" } }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/SiteWorldSearchAlias" } }, "filters": { "$ref": "#/components/schemas/SiteWorldSearchFilters" } } }, "SiteWorldSearchAlias": { "type": "object", "required": [ "alias", "mapsTo", "categories", "industries", "siteTypes", "objectTags", "terms" ], "properties": { "alias": { "type": "string" }, "mapsTo": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "industries": { "type": "array", "items": { "type": "string" } }, "siteTypes": { "type": "array", "items": { "type": "string" } }, "objectTags": { "type": "array", "items": { "type": "string" } }, "terms": { "type": "array", "items": { "type": "string" } }, "truthNote": { "type": "string" } } }, "SiteWorldSearchFilters": { "type": "object", "additionalProperties": false, "properties": { "category": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "siteType": { "type": [ "string", "null" ] }, "taskLane": { "type": [ "string", "null" ] }, "objectTags": { "type": "array", "items": { "type": "string" } }, "robot": { "type": [ "string", "null" ] }, "availability": { "type": [ "string", "null" ] }, "readiness": { "type": [ "string", "null" ] }, "sort": { "type": "string", "enum": [ "relevance", "name", "city", "category", "readiness", "availability" ] } } }, "SiteWorldSearchMeta": { "type": "object", "required": [ "backend", "embeddingModel", "usedEmbeddings", "totalCandidates", "returned" ], "properties": { "backend": { "type": "string", "enum": [ "firestore-live", "static-fallback" ] }, "embeddingModel": { "type": "string" }, "usedEmbeddings": { "type": "boolean" }, "totalCandidates": { "type": "integer" }, "returned": { "type": "integer" } } }, "SiteWorld": { "type": "object", "required": [ "id", "siteName" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "siteName": { "type": "string" }, "siteAddress": { "type": "string" }, "commercialStatus": { "type": "string" }, "truthLabels": { "type": "array", "items": { "$ref": "#/components/schemas/TruthLabel" } }, "robotProfiles": { "type": "array", "items": { "$ref": "#/components/schemas/RobotProfile" } }, "taskCatalog": { "type": "array", "items": { "$ref": "#/components/schemas/TaskCatalogEntry" } }, "scenarioCatalog": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioCatalogEntry" } }, "startStateCatalog": { "type": "array", "items": { "$ref": "#/components/schemas/StartStateCatalogEntry" } } } }, "RobotProfile": { "type": "object", "required": [ "displayName", "embodimentType", "observationCameras", "actionSpace", "actionSpaceSummary" ], "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "embodimentType": { "type": "string", "enum": [ "humanoid", "mobile_manipulator", "fixed_arm", "mobile_base", "cart", "other" ] }, "observationCameras": { "type": "array", "items": { "$ref": "#/components/schemas/RobotObservationCamera" } }, "actionSpace": { "$ref": "#/components/schemas/RobotActionSpace" }, "actionSpaceSummary": { "type": "string" }, "gripperSemantics": { "type": [ "string", "null" ] }, "baseSemantics": { "type": [ "string", "null" ] }, "urdfRef": { "type": [ "string", "null" ] }, "usdRef": { "type": [ "string", "null" ] }, "allowedPolicyAdapters": { "type": "array", "items": { "type": "string" } }, "defaultPolicyAdapter": { "type": [ "string", "null" ] } } }, "RobotObservationCamera": { "type": "object", "required": [ "id", "role", "required", "defaultEnabled" ], "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "required": { "type": "boolean" }, "defaultEnabled": { "type": "boolean" }, "available": { "type": "boolean" }, "framePath": { "type": [ "string", "null" ] } } }, "RobotActionSpace": { "type": "object", "required": [ "name", "dim", "labels" ], "properties": { "name": { "type": "string" }, "dim": { "type": "integer" }, "labels": { "type": "array", "items": { "type": "string" } } } }, "TaskCatalogEntry": { "type": "object", "required": [ "id", "taskText" ], "properties": { "id": { "type": "string" }, "taskId": { "type": [ "string", "null" ] }, "taskText": { "type": "string" }, "taskCategory": { "type": [ "string", "null" ] } } }, "ScenarioCatalogEntry": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": [ "string", "null" ] } } }, "StartStateCatalogEntry": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "taskId": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "CreateHostedSessionRequest": { "type": "object", "required": [ "siteWorldId", "robotProfileId", "taskId", "scenarioId", "startStateId" ], "properties": { "siteWorldId": { "type": "string", "examples": [ "siteworld-f5fd54898cfb" ] }, "sessionMode": { "type": "string", "enum": [ "runtime_only", "presentation_demo" ], "default": "runtime_only" }, "runtimeUi": { "type": [ "string", "null" ], "enum": [ "neoverse_gradio", null ] }, "autoStartDemo": { "type": "boolean" }, "robotProfileId": { "type": "string" }, "robotProfileOverride": { "type": "object", "additionalProperties": true }, "policy": { "type": "object", "additionalProperties": true }, "taskId": { "type": "string" }, "scenarioId": { "type": "string" }, "startStateId": { "type": "string" }, "requestedBackend": { "type": [ "string", "null" ] }, "runtimeSessionConfig": { "$ref": "#/components/schemas/HostedRuntimeSessionConfig" }, "requestedOutputs": { "type": "array", "items": { "type": "string" } }, "exportModes": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "entitlementId": { "type": "string" }, "orderId": { "type": "string" }, "commerceMode": { "type": "string", "enum": [ "dry_run" ] } } }, "AgentCommerceQuote": { "type": "object", "required": [ "quoteId", "mode", "product", "siteWorldId", "sku", "quantity", "unitAmountCents", "totalAmountCents", "currency" ], "properties": { "quoteId": { "type": "string" }, "mode": { "type": "string", "enum": [ "dry_run" ] }, "product": { "$ref": "#/components/schemas/AgentCommerceProduct" }, "siteWorldId": { "type": "string" }, "sku": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "quantityLabel": { "type": "string" }, "unitAmountCents": { "type": "integer" }, "totalAmountCents": { "type": "integer" }, "currency": { "type": "string", "enum": [ "usd" ] }, "entitlementType": { "type": "string", "enum": [ "package_access", "hosted_session" ] }, "truthLabels": { "type": "array", "items": { "$ref": "#/components/schemas/TruthLabel" } } } }, "AgentCommerceQuoteResponse": { "type": "object", "required": [ "quote", "truth" ], "properties": { "quote": { "$ref": "#/components/schemas/AgentCommerceQuote" }, "siteWorld": { "type": [ "object", "null" ], "additionalProperties": true }, "truth": { "type": "string" } } }, "AgentDryRunCheckoutRequest": { "type": "object", "required": [ "siteWorldId", "mode" ], "properties": { "mode": { "type": "string", "enum": [ "dry_run" ] }, "siteWorldId": { "type": "string" }, "product": { "$ref": "#/components/schemas/AgentCommerceProduct" }, "sessionHours": { "type": "integer", "minimum": 1, "default": 1 }, "buyer": { "type": "object", "properties": { "uid": { "type": "string" }, "email": { "type": "string" } } } } }, "AgentDryRunOrder": { "type": "object", "required": [ "id", "dry_run", "status", "payment_status", "fulfillment_status", "item", "pricing", "entitlement_id" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "dry_run": { "type": "boolean" }, "status": { "type": "string", "enum": [ "fulfilled" ] }, "payment_status": { "type": "string", "enum": [ "dry_run_paid" ] }, "fulfillment_status": { "type": "string", "enum": [ "provisioned" ] }, "item": { "type": "object", "additionalProperties": true }, "pricing": { "type": "object", "additionalProperties": true }, "stripe": { "type": "object", "additionalProperties": true }, "entitlement_id": { "type": "string" } } }, "AgentMarketplaceEntitlement": { "type": "object", "required": [ "id", "order_id", "sku", "access_state" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "order_id": { "type": "string" }, "sku": { "type": "string" }, "item_type": { "$ref": "#/components/schemas/AgentCommerceProduct" }, "delivery_mode": { "type": "string" }, "access_state": { "type": "string", "enum": [ "provisioned", "manual_review_required", "revoked" ] }, "dry_run": { "type": "boolean" } } }, "AgentDryRunOrderResponse": { "type": "object", "properties": { "quote": { "$ref": "#/components/schemas/AgentCommerceQuote" }, "order": { "$ref": "#/components/schemas/AgentDryRunOrder" }, "receipt": { "type": "object", "additionalProperties": true }, "entitlement": { "$ref": "#/components/schemas/AgentMarketplaceEntitlement" }, "truth": { "type": "string" } } }, "AgentEntitlementResponse": { "type": "object", "required": [ "entitlement" ], "properties": { "entitlement": { "$ref": "#/components/schemas/AgentMarketplaceEntitlement" } } }, "AgentEntitlementReadiness": { "type": "object", "required": [ "mode", "siteWorldId", "entitled", "launchable", "blockers" ], "properties": { "mode": { "type": "string", "enum": [ "dry_run" ] }, "siteWorldId": { "type": "string" }, "entitlement": { "type": [ "object", "null" ], "additionalProperties": true }, "entitled": { "type": "boolean" }, "launchable": { "type": "boolean" }, "blockers": { "type": "array", "items": { "type": "string" } }, "truth": { "type": "string" } } }, "HostedRuntimeSessionConfig": { "type": "object", "properties": { "canonical_package_uri": { "type": [ "string", "null" ] }, "canonical_package_version": { "type": [ "string", "null" ] }, "prompt": { "type": [ "string", "null" ] }, "trajectory": { "type": [ "string", "null" ] }, "presentation_model": { "type": [ "string", "null" ] }, "debug_mode": { "type": "boolean" }, "unsafe_allow_blocked_site_world": { "type": "boolean", "description": "Internal/local escape hatch only. Do not use for public or protected production flows." } } }, "ResetHostedSessionRequest": { "type": "object", "properties": { "taskId": { "type": "string" }, "scenarioId": { "type": "string" }, "startStateId": { "type": "string" }, "seed": { "type": "integer" } } }, "StepHostedSessionRequest": { "type": "object", "properties": { "episodeId": { "type": "string" }, "action": { "type": "array", "items": { "type": "number" } }, "autoPolicy": { "type": "boolean", "default": true } } }, "RunBatchRequest": { "type": "object", "properties": { "numEpisodes": { "type": "integer", "minimum": 1, "default": 1 }, "taskId": { "type": "string" }, "scenarioId": { "type": "string" }, "startStateId": { "type": "string" }, "seed": { "type": "integer" }, "maxSteps": { "type": "integer", "minimum": 1 } } }, "ControlRequest": { "type": "object", "additionalProperties": true, "properties": { "mode": { "type": "string" }, "cameraId": { "type": "string" }, "playback": { "type": "string" } } }, "ExplorerRenderRequest": { "type": "object", "properties": { "cameraId": { "type": "string", "default": "head_rgb" }, "pose": { "$ref": "#/components/schemas/ExplorerPose" }, "viewportWidth": { "type": "integer" }, "viewportHeight": { "type": "integer" }, "refineMode": { "type": [ "string", "null" ] } } }, "ExportRequest": { "type": "object", "properties": { "format": { "type": "string", "default": "manifest" } } }, "ExplorerPose": { "type": "object", "required": [ "x", "y", "z", "yaw", "pitch" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "z": { "type": "number" }, "yaw": { "type": "number" }, "pitch": { "type": "number" } } }, "LaunchReadiness": { "type": "object", "required": [ "entitled", "status", "launchable", "blockers" ], "properties": { "entitled": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/StatusLabel" }, "launchable": { "type": "boolean" }, "blockers": { "type": "array", "items": { "type": "string" } }, "blocker_details": { "type": "array", "items": { "$ref": "#/components/schemas/LaunchBlockerDetail" } }, "presentation_demo": { "type": "object", "additionalProperties": true }, "runtime_only": { "type": "object", "additionalProperties": true } } }, "LaunchBlockerDetail": { "type": "object", "required": [ "code", "message", "source" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "string", "enum": [ "access", "qualification", "runtime", "presentation_demo" ] } } }, "CreateHostedSessionResponse": { "type": "object", "required": [ "sessionId", "status", "site", "workspaceUrl" ], "properties": { "sessionId": { "type": "string" }, "status": { "type": "string" }, "site": { "type": "object", "additionalProperties": true }, "runtimeBackend": { "type": "string" }, "launchable": { "type": "boolean" }, "uiReady": { "type": "boolean" }, "uiMode": { "type": "string" }, "workspaceUrl": { "type": "string" } } }, "HostedSession": { "type": "object", "required": [ "sessionId", "sessionMode", "status", "site" ], "additionalProperties": true, "properties": { "sessionId": { "type": "string" }, "sessionMode": { "type": "string", "enum": [ "runtime_only", "presentation_demo" ] }, "status": { "type": "string", "enum": [ "creating", "ready", "running", "stopped", "failed" ] }, "site": { "type": "object", "additionalProperties": true }, "robotProfile": { "$ref": "#/components/schemas/RobotProfile" }, "taskSelection": { "type": "object", "additionalProperties": true }, "runtimeConfig": { "type": "object", "additionalProperties": true }, "latestEpisode": { "type": "object", "additionalProperties": true }, "batchSummary": { "type": "object", "additionalProperties": true }, "explorerState": { "type": "object", "additionalProperties": true }, "artifactUris": { "type": "object", "additionalProperties": { "type": "string" } }, "datasetArtifacts": { "type": "object", "additionalProperties": true } } }, "HostedSessionOperationResponse": { "type": "object", "additionalProperties": true, "properties": { "episode": { "type": "object", "additionalProperties": true }, "summary": { "type": "object", "additionalProperties": true }, "artifact_uris": { "type": "object", "additionalProperties": { "type": "string" } }, "dataset_artifacts": { "type": "object", "additionalProperties": true }, "explorerState": { "type": "object", "additionalProperties": true } } }, "PendingOperationResponse": { "type": "object", "required": [ "accepted", "pendingOperation" ], "properties": { "accepted": { "type": "boolean" }, "pendingOperation": { "type": "object", "additionalProperties": true }, "episode": { "type": [ "object", "null" ], "additionalProperties": true } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "diagnostic": { "type": "object", "additionalProperties": true } } }, "LaunchBlockedResponse": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "blockers": { "type": "array", "items": { "type": "string" } }, "blocker_details": { "type": "array", "items": { "$ref": "#/components/schemas/LaunchBlockerDetail" } }, "diagnostic": { "type": "object", "additionalProperties": true } } } } }, "x-blueprint-truth-labels": [ "capture_grounded", "provider_derived", "generated", "sample_demo", "public_demo_eligible", "request_gated", "protected_robot_team", "dry_run_order" ] }