{ "openapi": "3.1.0", "info": { "title": "FrontierSight Workbench API", "version": "0.38.0", "description": "Supported scene editing, canonical playback preparation, analysis/simulation handoff, segmentation and billing availability. This contract does not enumerate every legacy account endpoint. Single-image 3D visualization does not imply measured depth or physical calibration." }, "servers": [ { "url": "https://frontiersight-ai.vercel.app" } ], "paths": { "/api/scenes/resize": { "post": { "operationId": "resizeScene", "summary": "Scale all paths into a new floor, fit sampled smooth-curve envelopes and keep physical radii and speeds unchanged.", "description": "Pure computation: no saved record, account or billing state is modified. Save the returned scene separately through the authenticated scene-storage API. Anonymous per-client POST rate limits apply.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResizeRequest" } } } }, "responses": { "200": { "description": "Edited scene", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditResult" } } } }, "400": { "description": "Invalid scene, dimensions or position", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds ingestion limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/scenes/reposition": { "post": { "operationId": "repositionScene", "summary": "Move one object\u2019s first waypoint toward x/y, translating its complete path. Clamps movement to keep the path and footprint inside the floor.", "description": "Pure computation: no saved record, account or billing state is modified. Save the returned scene separately through the authenticated scene-storage API. Anonymous per-client POST rate limits apply.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositionRequest" } } } }, "responses": { "200": { "description": "Edited scene", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditResult" } } } }, "400": { "description": "Invalid scene, dimensions or position", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds ingestion limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/mcp": { "get": { "operationId": "getMcpCatalog", "summary": "Describe the deterministic MCP tool catalog", "responses": { "200": { "description": "Tool names, descriptions and transport information" } } }, "post": { "operationId": "callMcp", "summary": "MCP JSON-RPC transport including resize_scene and reposition_scene", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": [ "integer", "string" ] }, "method": { "type": "string" }, "params": { "type": "object" } } } } } }, "responses": { "200": { "description": "JSON-RPC response; tool failures have result.isError=true" }, "202": { "description": "Notification accepted without response body" }, "400": { "description": "Invalid JSON" }, "429": { "description": "Rate limit" } } } }, "/api/meta/segment": { "post": { "operationId": "segmentImage", "summary": "Segment a user-supplied JPEG or PNG with SAM; return real decoded masks when available", "description": "Model-backed operation; the deployment must have a Meta API key. The public demo uses its host key and applies a separate 30-request/minute model limit per client, in addition to the general POST limit. No match is a successful result with empty frames. A decode budget/failure is explicit (decoded=false); never treat a bounding box as a decoded silhouette. Image-derived extrusion depth remains an assumption, not calibrated geometry.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image_data_url" ], "properties": { "image_data_url": { "type": "string", "maxLength": 3500000, "pattern": "^data:image/(jpeg|png);base64," }, "concept": { "type": "string", "minLength": 1, "maxLength": 100, "default": "person", "description": "One short noun phrase; send separate requests for different concepts." } } } } } }, "responses": { "200": { "description": "Completed segmentation, including valid zero matches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentationResult" } } } }, "202": { "description": "BLOCKED_CREDENTIALS; no model run occurred" }, "400": { "description": "Invalid image or concept" }, "413": { "description": "Ingestion limit exceeded" }, "429": { "description": "Rate limit exceeded" }, "502": { "description": "MODEL_ERROR; no completed segmentation result" } } } }, "/api/scenes/prepare": { "post": { "operationId": "prepareScene", "summary": "Prepare a complete scene for Studio and Counterfactual playback", "description": "Preserves declared floor, object definitions, custom appearance, path modes and physical radii. Samples bounded 10 Hz tracks over at most 20 seconds, carrying a scene digest. Requires every object to be placed. No saved state or model call.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareRequest" } } } }, "responses": { "200": { "description": "Canonical USER_UPLOADED scenario including stage_metres, objects, scene_digest and tracks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedScene" } } } }, "400": { "description": "Invalid or unplaced scene" }, "413": { "description": "Ingestion limit" }, "429": { "description": "Rate limit" } } } }, "/api/counterfactual-custom": { "post": { "operationId": "simulateCustomScene", "summary": "Simulate a scene while preserving floor, definitions and physical footprints", "description": "Pass a complete scene plus agent_id and optional target_id. Existing tracks-only requests remain supported. A complete scene is resampled on the server; supplied client tracks are not trusted as a substitute. Monte-Carlo limits follow authenticated plan entitlements; MCP is capped at 200. Responses include the input floor, definitions and digest alongside simulation results.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SceneSimulationRequest" }, { "type": "object", "required": [ "tracks" ], "properties": { "tracks": { "type": "array" } } } ] } } } }, "responses": { "200": { "description": "Path-following comparison, declared scene context and provenance" }, "400": { "description": "Invalid scene, agent, target or parameters" }, "402": { "description": "Simulation budget exceeds the current plan" }, "429": { "description": "Rate limit" } } } }, "/api/analyze-custom": { "post": { "operationId": "analyzeCustomScene", "summary": "Analyze a complete edited scene without losing its floor or definitions", "description": "New clients pass scene. Legacy tracks requests remain supported. Returns run plus the canonical scenario with stage_metres, objects, digest and sampled tracks. Analysis may invoke a configured reasoning provider and consume model credits; this model-backed operation is not an MCP tool.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PrepareRequest" }, { "type": "object", "required": [ "tracks" ], "properties": { "tracks": { "type": "array" } } } ] } } } }, "responses": { "200": { "description": "Analysis run and canonical scenario" }, "400": { "description": "Invalid scene or tracks" }, "429": { "description": "Rate limit" } } } }, "/api/billing/config": { "get": { "operationId": "getBillingAvailability", "summary": "Public offer and checkout availability without secret values", "responses": { "200": { "description": "USD prices, supported periods and live/test/unavailable checkout mode. Availability does not claim a customer transaction was completed." } } } }, "/api/meta/scene": { "post": { "operationId": "generateScene", "summary": "Generate a bounded candidate batch and select one scene", "description": "1\u20138 parallel calls to the selected model. No automatic provider or quality-repair retries. Shared 28-second provider deadline; completed valid candidates are ranked by deterministic path-quality heuristics. Browser cancellation does not guarantee remote provider cancellation. A 503 indicates another batch still owns this process capacity. Existing offline templates are explicitly labelled. This model-generation endpoint is not exposed by the deterministic MCP server.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "minLength": 1, "maxLength": 4000 }, "model": { "type": "string", "enum": [ "muse-spark-1.3", "muse-spark-1.2", "muse-spark-1.1", "muse-spark-1.3-contributor", "muse-spark-1.2-contributor", "muse-wonder-1.0" ] }, "candidates": { "type": "integer", "minimum": 1, "maximum": 8, "default": 3 } } } } } }, "responses": { "200": { "description": "One validated scene and candidate metadata" }, "202": { "description": "Model credentials unavailable; no matching offline template" }, "400": { "description": "Invalid request" }, "502": { "description": "No valid candidate or provider failure" }, "503": { "description": "Generation capacity occupied" }, "504": { "description": "Deadline reached without a valid candidate" } } } }, "/api/v1/media/render-frame": { "post": { "operationId": "render_scene_frame", "summary": "Render a bounded PNG top-down simulation frame with metre-space poses, preserving the playback motion profiles. No model call; no observed-camera claim.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_render_scene_frame" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/media/render-preview": { "post": { "operationId": "render_video_preview", "summary": "Export a bounded animated GIF simulation preview, maximum 60 frames and 20 megapixels. This is not MP4 or photorealistic 3D video.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_render_video_preview" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/model-requests/get": { "post": { "operationId": "get_model_request", "summary": "Inspect your own durable model-request status/result by the original request key. Running or failed_or_unknown never automatically retries the provider.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_get_model_request" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/paths/plan": { "post": { "operationId": "plan_path", "summary": "Plan a bounded A* route around inflated static object footprints in metres. Moving actors are not reserved. Returns a new scene; never saves or actuates hardware.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_plan_path" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/paths/predict": { "post": { "operationId": "predict_path", "summary": "Fit the last 20 timestamped observations with constant velocity; return explicit future predictions and separate optional floor-constrained display points. Fit residuals are not calibrated uncertainty.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_predict_path" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/paths/describe": { "post": { "operationId": "describe_paths", "summary": "Request one bounded Muse path edit for existing exact object IDs. No automatic retries. Returns a new scene without saving it. Requires Researcher and an idempotency key.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_describe_paths" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/scenes/prepare": { "post": { "operationId": "prepare_scene", "summary": "Build the canonical timestamped tracks, object definitions and floor dimensions for Video Studio and Counterfactuals.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_prepare_scene" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/scenes/generate": { "post": { "operationId": "generate_scene", "summary": "Generate 1\u20138 candidates in one finite batch, select one scene, assign stable object IDs, and stop. Requires Researcher, durable storage and idempotency.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_generate_scene" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/objects/generate": { "post": { "operationId": "generate_object", "summary": "Generate one validated buildable object recipe. No automatic repair or image-generation request. Requires Researcher and idempotency.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_generate_object" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/objects/validate": { "post": { "operationId": "validate_object", "summary": "Validate a custom object recipe without saving it or invoking a model.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_validate_object" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/objects/use": { "post": { "operationId": "use_object", "summary": "Load an owned saved object recipe and place a uniquely named instance inside a scene. Returns a new unsaved scene.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_use_object" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/media/segment-frame": { "post": { "operationId": "segment_frame", "summary": "Segment an owned saved JPEG/PNG frame with Meta SAM. Requires Researcher and idempotency.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_segment_frame" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/media/segment-video": { "post": { "operationId": "segment_video", "summary": "Segment a saved Meta video file reference. Video bytes remain in the provider file service. Requires Researcher and idempotency.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_segment_video" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/scenes/list": { "post": { "operationId": "list_scenes", "summary": "List scenes within the verified active Clerk workspace. Private data; never a public catalog.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_list_scenes" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/scenes/get": { "post": { "operationId": "get_scenes", "summary": "Get scenes within the verified active Clerk workspace. Private data; never a public catalog.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_get_scenes" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/scenes/create": { "post": { "operationId": "create_scenes", "summary": "Create scenes within the verified active Clerk workspace. Mutations require Idempotency-Key; updates/deletes require expectedVersion. Organization deletion requires admin.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_create_scenes" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/scenes/update": { "post": { "operationId": "update_scenes", "summary": "Update scenes within the verified active Clerk workspace. Mutations require Idempotency-Key; updates/deletes require expectedVersion. Organization deletion requires admin.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_update_scenes" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/scenes/delete": { "post": { "operationId": "delete_scenes", "summary": "Delete scenes within the verified active Clerk workspace. Mutations require Idempotency-Key; updates/deletes require expectedVersion. Organization deletion requires admin.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_delete_scenes" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/objects/list": { "post": { "operationId": "list_objects", "summary": "List objects within the verified active Clerk workspace. Private data; never a public catalog.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_list_objects" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/objects/get": { "post": { "operationId": "get_objects", "summary": "Get objects within the verified active Clerk workspace. Private data; never a public catalog.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_get_objects" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/objects/create": { "post": { "operationId": "create_objects", "summary": "Create objects within the verified active Clerk workspace. Mutations require Idempotency-Key; updates/deletes require expectedVersion. Organization deletion requires admin.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_create_objects" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/objects/update": { "post": { "operationId": "update_objects", "summary": "Update objects within the verified active Clerk workspace. Mutations require Idempotency-Key; updates/deletes require expectedVersion. Organization deletion requires admin.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_update_objects" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/objects/delete": { "post": { "operationId": "delete_objects", "summary": "Delete objects within the verified active Clerk workspace. Mutations require Idempotency-Key; updates/deletes require expectedVersion. Organization deletion requires admin.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_delete_objects" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/media/list": { "post": { "operationId": "list_media", "summary": "List media within the verified active Clerk workspace. Private data; never a public catalog.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_list_media" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/media/get": { "post": { "operationId": "get_media", "summary": "Get media within the verified active Clerk workspace. Private data; never a public catalog.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_get_media" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/media/create": { "post": { "operationId": "create_media", "summary": "Create media within the verified active Clerk workspace. Mutations require Idempotency-Key; updates/deletes require expectedVersion. Organization deletion requires admin.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_create_media" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/media/update": { "post": { "operationId": "update_media", "summary": "Update media within the verified active Clerk workspace. Mutations require Idempotency-Key; updates/deletes require expectedVersion. Organization deletion requires admin.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_update_media" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/v1/media/delete": { "post": { "operationId": "delete_media", "summary": "Delete media within the verified active Clerk workspace. Mutations require Idempotency-Key; updates/deletes require expectedVersion. Organization deletion requires admin.", "tags": [ "Workbench" ], "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "X-Workspace-Organization", "schema": { "type": "string" }, "description": "Optional stale-workspace guard: active org ID, or personal." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_delete_media" } } } }, "responses": { "200": { "description": "Operation result; mutations return id, version and replay status. Renders return MIME type and data URL." }, "400": { "description": "Invalid request" }, "401": { "description": "Missing/expired session" }, "402": { "description": "Paid model capability required" }, "403": { "description": "Unauthorized workspace/origin" }, "404": { "description": "Record not in this workspace" }, "409": { "description": "Version conflict or prior model attempt" }, "429": { "description": "Quota exhausted" }, "503": { "description": "Storage or provider unavailable" } } } }, "/api/paths/plan": { "post": { "operationId": "public_plan_path", "summary": "Anonymous bounded deterministic plan; no storage or provider call.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_plan_path" } } } }, "responses": { "200": { "description": "New unsaved scene or separately labelled predictions" }, "400": { "description": "Invalid path input" } } } }, "/api/paths/predict": { "post": { "operationId": "public_predict_path", "summary": "Anonymous bounded deterministic predict; no storage or provider call.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbench_predict_path" } } } }, "responses": { "200": { "description": "New unsaved scene or separately labelled predictions" }, "400": { "description": "Invalid path input" } } } }, "/api/v1/account": { "get": { "operationId": "get_workspace_account", "summary": "Verified current user, active organization, plan and billing availability.", "security": [ { "ClerkSession": [] } ], "responses": { "200": { "description": "Verified workspace context" }, "401": { "description": "Session required" } } } }, "/api/v1/billing/checkout": { "post": { "operationId": "create_billing_checkout", "summary": "Create a hosted Stripe checkout session for the verified personal account.", "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string", "enum": [ "monthly", "annual" ] } } } } } }, "responses": { "200": { "description": "Server-created Stripe URL; no entitlement granted by redirect" }, "401": { "description": "Clerk sign-in required" }, "503": { "description": "Stripe not configured; no payment taken" } } } }, "/api/v1/billing/portal": { "post": { "operationId": "create_billing_portal", "summary": "Create a hosted Stripe portal session for the verified personal account.", "security": [ { "ClerkSession": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string", "enum": [ "monthly", "annual" ] } } } } } }, "responses": { "200": { "description": "Server-created Stripe URL; no entitlement granted by redirect" }, "401": { "description": "Clerk sign-in required" }, "503": { "description": "Stripe not configured; no payment taken" } } } }, "/api/v1/keys/create": { "post": { "operationId": "create_agent_key", "summary": "Clerk personal session only; create a scoped, revocable agent credential.", "security": [ { "ClerkSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "write", "model" ] }, "uniqueItems": true }, "days": { "type": "integer", "minimum": 1, "maximum": 90 } }, "required": [ "name", "scopes" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Key shown once for create; only prefix, scopes, expiry and revocation status for list." }, "401": { "description": "Session required" }, "403": { "description": "API keys and organization sessions cannot manage keys" }, "503": { "description": "Durable storage unavailable" } } } }, "/api/v1/keys/list": { "post": { "operationId": "list_agent_key", "summary": "Clerk personal session only; list a scoped, revocable agent credential.", "security": [ { "ClerkSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Key shown once for create; only prefix, scopes, expiry and revocation status for list." }, "401": { "description": "Session required" }, "403": { "description": "API keys and organization sessions cannot manage keys" }, "503": { "description": "Durable storage unavailable" } } } }, "/api/v1/keys/revoke": { "post": { "operationId": "revoke_agent_key", "summary": "Clerk personal session only; revoke a scoped, revocable agent credential.", "security": [ { "ClerkSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Key shown once for create; only prefix, scopes, expiry and revocation status for list." }, "401": { "description": "Session required" }, "403": { "description": "API keys and organization sessions cannot manage keys" }, "503": { "description": "Durable storage unavailable" } } } }, "/api/v1/provider-key/save": { "post": { "operationId": "save_workspace_provider_key", "summary": "Manage the encrypted Meta credential; raw values are never returned. Save/delete require a paid Clerk workspace administrator.", "security": [ { "ClerkSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 20, "maxLength": 512 } }, "required": [ "key" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "configured and last4 only" }, "403": { "description": "Clerk workspace administrator required" }, "503": { "description": "Credential encryption/storage unavailable" } } } }, "/api/v1/provider-key/status": { "post": { "operationId": "status_workspace_provider_key", "summary": "Manage the encrypted Meta credential; raw values are never returned. Save/delete require a paid Clerk workspace administrator.", "security": [ { "ClerkSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "configured and last4 only" }, "403": { "description": "Clerk workspace administrator required" }, "503": { "description": "Credential encryption/storage unavailable" } } } }, "/api/v1/provider-key/delete": { "post": { "operationId": "delete_workspace_provider_key", "summary": "Manage the encrypted Meta credential; raw values are never returned. Save/delete require a paid Clerk workspace administrator.", "security": [ { "ClerkSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "configured and last4 only" }, "403": { "description": "Clerk workspace administrator required" }, "503": { "description": "Credential encryption/storage unavailable" } } } } }, "components": { "schemas": { "EditorObject": { "type": "object", "required": [ "waypoints" ], "anyOf": [ { "required": [ "id" ] }, { "required": [ "object_id" ] } ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9_-]{1,100}$" }, "object_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "category": { "type": "string" }, "waypoints": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "minItems": 0, "maxItems": 24 }, "radius": { "type": "number", "minimum": 0, "default": 0.5 }, "speed": { "type": "number", "minimum": 0, "maximum": 8 }, "delay": { "type": "number", "minimum": 0, "maximum": 10 }, "curve": { "type": "string", "enum": [ "straight", "smooth" ] }, "mode": { "type": "string", "enum": [ "stop", "loop", "pingpong" ] } }, "additionalProperties": true, "description": "Unique id (or object_id). When both are present they must agree. Coordinates are metres. Appearance and other supplied fields are preserved; derived caches are discarded." }, "EditableScene": { "type": "object", "required": [ "stage_metres", "objects" ], "properties": { "name": { "type": "string" }, "stage_metres": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number", "minimum": 6, "maximum": 60 } }, "objects": { "type": "array", "items": { "$ref": "#/components/schemas/EditorObject" }, "minItems": 0, "maxItems": 24 } }, "additionalProperties": true }, "ResizeRequest": { "type": "object", "required": [ "scene", "width", "height" ], "properties": { "scene": { "$ref": "#/components/schemas/EditableScene" }, "width": { "type": "number", "minimum": 6, "maximum": 60 }, "height": { "type": "number", "minimum": 6, "maximum": 60 } } }, "RepositionRequest": { "type": "object", "required": [ "scene", "object_id", "x", "y" ], "properties": { "scene": { "$ref": "#/components/schemas/EditableScene" }, "object_id": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" } } }, "EditResult": { "type": "object", "required": [ "scene", "operation", "source", "persisted" ], "properties": { "scene": { "$ref": "#/components/schemas/EditableScene" }, "operation": { "type": "string", "enum": [ "resize", "reposition" ] }, "source": { "type": "string", "const": "DETERMINISTIC" }, "persisted": { "type": "boolean", "const": false }, "clamped": { "type": "boolean" }, "applied_translation": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "physical_sizes_preserved": { "type": "boolean" }, "speeds_preserved": { "type": "boolean" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "SegmentationBox": { "type": "object", "required": [ "x1", "y1", "x2", "y2", "frame_w", "frame_h" ], "properties": { "x1": { "type": "integer", "minimum": 0 }, "y1": { "type": "integer", "minimum": 0 }, "x2": { "type": "integer", "minimum": 0 }, "y2": { "type": "integer", "minimum": 0 }, "frame_w": { "type": "integer", "minimum": 0 }, "frame_h": { "type": "integer", "minimum": 0 } } }, "SegmentationMask": { "type": "object", "required": [ "decoded" ], "properties": { "decoded": { "type": "boolean" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "png_data_url": { "type": "string", "pattern": "^data:image/png;base64,", "description": "Actual decoded binary mask as a white/alpha PNG. Present only when decoding succeeded within budget." }, "note": { "type": "string" } }, "additionalProperties": true }, "SegmentationRecord": { "type": "object", "required": [ "object_id", "box" ], "properties": { "object_id": { "type": "integer", "minimum": 0 }, "box": { "$ref": "#/components/schemas/SegmentationBox" }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "mask": { "$ref": "#/components/schemas/SegmentationMask" } } }, "SegmentationResult": { "type": "object", "required": [ "frames", "objects", "diagnostics", "model", "concept" ], "properties": { "frames": { "type": "array", "items": { "type": "object", "properties": { "frame": { "type": "integer", "minimum": 0 }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentationRecord" } } } } }, "objects": { "type": "array", "items": { "type": "integer" } }, "diagnostics": { "type": "array", "items": { "type": "object" } }, "model": { "type": "string" }, "concept": { "type": "string" }, "latency_ms": { "type": "number" } } }, "PrepareRequest": { "type": "object", "required": [ "scene" ], "properties": { "scene": { "$ref": "#/components/schemas/EditableScene" } } }, "PreparedScene": { "type": "object", "required": [ "id", "kind", "stage_metres", "objects", "tracks", "scene_digest" ], "properties": { "id": { "type": "string" }, "kind": { "const": "USER_UPLOADED" }, "stage_metres": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number", "minimum": 6, "maximum": 60 } }, "objects": { "type": "array", "items": { "$ref": "#/components/schemas/EditorObject" }, "minItems": 0, "maxItems": 24 }, "tracks": { "type": "array", "items": { "type": "object", "required": [ "object_id", "category", "space", "radius", "points" ], "properties": { "object_id": { "type": "string" }, "category": { "type": "string" }, "space": { "const": "world" }, "radius": { "type": "number" }, "points": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 } } } } }, "scene_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "SceneSimulationRequest": { "type": "object", "required": [ "scene", "agent_id" ], "properties": { "scene": { "$ref": "#/components/schemas/EditableScene" }, "agent_id": { "type": "string" }, "target_id": { "type": [ "string", "null" ] }, "intervention_t": { "type": "number", "default": 1 }, "speed_reduction_pct": { "type": "number", "minimum": 0, "maximum": 100, "default": 40 }, "braking_decel": { "type": "number", "minimum": 0, "maximum": 6, "default": 2.5 }, "mc_runs": { "type": "integer", "minimum": 0, "default": 100 } } }, "Workbench_plan_path": { "type": "object", "properties": { "scene": { "$ref": "#/components/schemas/EditableScene" }, "object_id": { "type": "string" }, "goal": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "resolution_m": { "type": "number", "minimum": 0.25, "maximum": 2, "default": 0.5 }, "clearance_m": { "type": "number", "minimum": 0, "maximum": 2, "default": 0.1 }, "smooth": { "type": "boolean", "default": true } }, "required": [ "scene", "object_id", "goal" ], "additionalProperties": false }, "Workbench_predict_path": { "type": "object", "properties": { "points": { "type": "array", "minItems": 3, "maxItems": 5000, "items": { "type": "array", "items": { "type": "number" }, "minItems": 3, "maxItems": 3 } }, "horizon_s": { "type": "number", "minimum": 0.1, "maximum": 30, "default": 3 }, "step_s": { "type": "number", "minimum": 0.05, "maximum": 5, "default": 0.25 }, "space": { "type": "string", "enum": [ "world", "pixel" ] }, "stage_metres": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "radius": { "type": "number", "minimum": 0, "maximum": 10 } }, "required": [ "points" ], "additionalProperties": false }, "Workbench_describe_paths": { "type": "object", "properties": { "scene": { "$ref": "#/components/schemas/EditableScene" }, "description": { "type": "string", "minLength": 4, "maxLength": 2000 }, "model": { "type": "string" } }, "required": [ "scene", "description" ], "additionalProperties": false }, "Workbench_prepare_scene": { "type": "object", "properties": { "scene": { "$ref": "#/components/schemas/EditableScene" } }, "required": [ "scene" ], "additionalProperties": false }, "Workbench_generate_scene": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 4000 }, "model": { "type": "string" }, "candidates": { "type": "integer", "minimum": 1, "maximum": 8, "default": 3 } }, "required": [ "description" ], "additionalProperties": false }, "Workbench_generate_object": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 300 }, "model": { "type": "string" } }, "required": [ "description" ], "additionalProperties": false }, "Workbench_validate_object": { "type": "object", "properties": { "spec": { "type": "object" } }, "required": [ "spec" ], "additionalProperties": false }, "Workbench_use_object": { "type": "object", "properties": { "scene": { "$ref": "#/components/schemas/EditableScene" }, "object_record_id": { "type": "string", "format": "uuid" }, "object_id": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "scene", "object_record_id", "object_id", "x", "y" ], "additionalProperties": false }, "Workbench_render_scene_frame": { "type": "object", "properties": { "scene": { "$ref": "#/components/schemas/EditableScene" }, "timestamp_s": { "type": "number", "minimum": 0, "maximum": 20 }, "width": { "type": "integer", "minimum": 160, "maximum": 1024 }, "height": { "type": "integer", "minimum": 120, "maximum": 768 } }, "required": [ "scene" ], "additionalProperties": false }, "Workbench_render_video_preview": { "type": "object", "properties": { "scene": { "$ref": "#/components/schemas/EditableScene" }, "duration_s": { "type": "number", "minimum": 0.2, "maximum": 12 }, "fps": { "type": "integer", "minimum": 1, "maximum": 15 }, "width": { "type": "integer", "minimum": 160, "maximum": 1024 }, "height": { "type": "integer", "minimum": 120, "maximum": 768 } }, "required": [ "scene" ], "additionalProperties": false }, "Workbench_get_model_request": { "type": "object", "properties": { "request_key": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } }, "required": [ "request_key" ], "additionalProperties": false }, "Workbench_list_scenes": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "after": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false }, "Workbench_get_scenes": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ], "additionalProperties": false }, "Workbench_create_scenes": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "scene": { "$ref": "#/components/schemas/EditableScene" } }, "required": [ "name", "scene" ], "additionalProperties": false }, "Workbench_update_scenes": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "scene": { "$ref": "#/components/schemas/EditableScene" }, "id": { "type": "string", "format": "uuid" }, "expectedVersion": { "type": "integer", "minimum": 1 } }, "required": [ "name", "scene", "id", "expectedVersion" ], "additionalProperties": false }, "Workbench_delete_scenes": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "expectedVersion": { "type": "integer", "minimum": 1 } }, "required": [ "id", "expectedVersion" ], "additionalProperties": false }, "Workbench_list_objects": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "after": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false }, "Workbench_get_objects": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ], "additionalProperties": false }, "Workbench_create_objects": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "spec": { "type": "object" } }, "required": [ "name", "spec" ], "additionalProperties": false }, "Workbench_update_objects": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "spec": { "type": "object" }, "id": { "type": "string", "format": "uuid" }, "expectedVersion": { "type": "integer", "minimum": 1 } }, "required": [ "name", "spec", "id", "expectedVersion" ], "additionalProperties": false }, "Workbench_delete_objects": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "expectedVersion": { "type": "integer", "minimum": 1 } }, "required": [ "id", "expectedVersion" ], "additionalProperties": false }, "Workbench_list_media": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "after": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false }, "Workbench_get_media": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ], "additionalProperties": false }, "Workbench_create_media": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "kind": { "type": "string", "enum": [ "frame", "video" ] }, "data_url": { "type": "string", "maxLength": 180000 }, "timestamp_s": { "type": "number", "minimum": 0, "maximum": 86400 }, "source_video_id": { "type": "string", "format": "uuid" }, "provider_file_id": { "type": "string", "maxLength": 160 } }, "required": [ "name", "kind" ], "additionalProperties": false }, "Workbench_update_media": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "kind": { "type": "string", "enum": [ "frame", "video" ] }, "data_url": { "type": "string", "maxLength": 180000 }, "timestamp_s": { "type": "number", "minimum": 0, "maximum": 86400 }, "source_video_id": { "type": "string", "format": "uuid" }, "provider_file_id": { "type": "string", "maxLength": 160 }, "id": { "type": "string", "format": "uuid" }, "expectedVersion": { "type": "integer", "minimum": 1 } }, "required": [ "name", "kind", "id", "expectedVersion" ], "additionalProperties": false }, "Workbench_delete_media": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "expectedVersion": { "type": "integer", "minimum": 1 } }, "required": [ "id", "expectedVersion" ], "additionalProperties": false }, "Workbench_segment_frame": { "type": "object", "properties": { "media_id": { "type": "string", "format": "uuid" }, "concept": { "type": "string", "maxLength": 100 } }, "required": [ "media_id" ], "additionalProperties": false }, "Workbench_segment_video": { "type": "object", "properties": { "media_id": { "type": "string", "format": "uuid" }, "concept": { "type": "string", "maxLength": 100 } }, "required": [ "media_id" ], "additionalProperties": false } }, "securitySchemes": { "ClerkSession": { "type": "http", "scheme": "bearer", "bearerFormat": "Clerk short-lived session JWT", "description": "Clerk session JWT or revocable fsa_ personal agent key. Session-only billing and key administration reject agent keys." } } } }