{ "openapi": "3.1.0", "info": { "title": "Gizmo API", "version": "1.0.0", "description": "Programmatic API for AI-powered 3D simulation authoring.\n\nGenerate physics-ready 3D scenes and articulated assets from natural language prompts. Export to USD / USDZ (Isaac Sim), MJCF (MuJoCo), and SDF (Gazebo). GLB is only available via the editor UI." }, "paths": { "/v1/scenes": { "get": { "tags": [ "Scenes" ], "summary": "List scenes", "description": "Retrieve all scenes belonging to the authenticated user, ordered by creation date (newest first).", "operationId": "list_scenes_v1_scenes_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "List of scene summaries", "content": { "application/json": { "schema": {}, "example": { "ok": true, "scenes": [ { "id": "jh72k3m4n5p6q7r8", "name": "Robot Kitchen", "pipeline_status": "completed", "pipeline_prompt": "A modern kitchen", "created_at": 1717800000000, "updated_at": 1717800060000 } ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } }, "post": { "tags": [ "Scenes" ], "summary": "Generate a scene", "description": "Start async scene generation from a text prompt. Returns immediately with a `job_id`. Optional `reference_image_urls` (e.g. a room photo) ground the structure build in your image.\n\nPoll progress via `GET /v1/jobs/{job_id}` or stream real-time events via `GET /v1/jobs/{job_id}/events`.\n\nThe AI agent will:\n1. Plan reusable assets from your prompt\n2. Generate each asset (geometry, joints, materials, physics)\n3. Create a floorplan and place assets with constraint solving\n4. Run physics validation\n\nTypical generation time: 2-5 minutes depending on scene complexity.", "operationId": "generate_scene_v1_scenes_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateSceneBody" } } } }, "responses": { "202": { "description": "Job created", "content": { "application/json": { "schema": {}, "example": { "ok": true, "scene_id": "jh72k3m4n5p6q7r8", "job_id": "job_a1b2c3d4", "status": "queued", "estimated_seconds": 1200, "estimate_note": "Scene generation typically takes 10-25 minutes (structure + assets + placement)." } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/v1/scenes/{scene_id}": { "get": { "tags": [ "Scenes" ], "summary": "Get scene detail", "description": "Retrieve a single scene by ID, optionally including the full scene graph (3D geometry, joints, materials) from S3.", "operationId": "get_scene_v1_scenes__scene_id__get", "parameters": [ { "name": "scene_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Scene Id" } }, { "name": "include_graph", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include the full scene graph JSON from S3", "default": false, "title": "Include Graph" }, "description": "Include the full scene graph JSON from S3" }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Scene not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } }, "patch": { "tags": [ "Scenes" ], "summary": "Update scene metadata", "description": "Update a scene's name or description. Does not trigger regeneration.", "operationId": "update_scene_v1_scenes__scene_id__patch", "parameters": [ { "name": "scene_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Scene Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSceneBody" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Scene not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } }, "delete": { "tags": [ "Scenes" ], "summary": "Delete scene", "description": "Permanently delete a scene and its associated data.", "operationId": "delete_scene_v1_scenes__scene_id__delete", "parameters": [ { "name": "scene_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Scene Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Scene not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/v1/scenes/{scene_id}/status": { "get": { "tags": [ "Scenes" ], "summary": "Scene pipeline status", "description": "Get detailed pipeline execution status for a scene — stages completed, errors, timing.", "operationId": "scene_status_v1_scenes__scene_id__status_get", "parameters": [ { "name": "scene_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Scene Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Scene not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/v1/scenes/{scene_id}/export": { "post": { "summary": "Export scene to MJCF/USD/SDF", "description": "Fetch the scene graph from S3 and run the export via the Node.js bundle.\n\nThe export runs in-process (subprocess) — no external service dependency.\nReturns the ZIP archive directly (``application/zip``).", "operationId": "export_scene_v1_scenes__scene_id__export_post", "parameters": [ { "name": "scene_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Scene Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportSceneBody" } } } }, "responses": { "200": { "description": "ZIP archive of the exported scene", "content": { "application/json": { "schema": {} }, "application/zip": {} } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Scene not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Export processing error" } } } }, "/v1/assets": { "get": { "tags": [ "Assets" ], "summary": "List assets", "description": "Retrieve all assets belonging to the authenticated user. Optionally filter by scene.", "operationId": "list_assets_v1_assets_get", "parameters": [ { "name": "scene_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by scene ID", "title": "Scene Id" }, "description": "Filter by scene ID" }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } }, "post": { "tags": [ "Assets" ], "summary": "Generate an asset", "description": "Generate a single 3D asset from a text prompt. The asset includes geometry, joints, materials, physics properties, and affordances.\n\nThe build method is chosen automatically per request: structured or jointed objects (furniture, appliances, racks) build as prim-based articulated assets (~15-20 min); organic objects (food, plants, fabric) build as mesh scans (~2-4 min). Optional `reference_image_urls` ground the geometry/texture in your photos.\n\nReturns a `job_id` — poll or stream for progress.", "operationId": "generate_asset_v1_assets_post", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateAssetBody" } } } }, "responses": { "202": { "description": "Job created", "content": { "application/json": { "schema": {}, "example": { "ok": true, "scene_id": "jh72k3m4n5p6q7r8", "job_id": "job_x9y8z7w6", "status": "queued" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/v1/assets/{asset_id}": { "get": { "tags": [ "Assets" ], "summary": "Get asset detail", "description": "Retrieve a single asset by ID. Use `include_record=true` to get the full geometry, joints, and materials data.", "operationId": "get_asset_v1_assets__asset_id__get", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Asset Id" } }, { "name": "include_record", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include the full asset record JSON from S3", "default": false, "title": "Include Record" }, "description": "Include the full asset record JSON from S3" }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Asset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } }, "delete": { "tags": [ "Assets" ], "summary": "Delete asset", "description": "Permanently delete an asset.", "operationId": "delete_asset_v1_assets__asset_id__delete", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Asset Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Asset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/v1/assets/{asset_id}/export": { "post": { "tags": [ "Assets" ], "summary": "Export a single asset to MJCF/USD/SDF", "description": "Fetch one asset's full record from storage, build a single-asset document (geometry + joints + materials preserved), and run the export. Returns a ZIP archive (`application/zip`). GLB is not offered here — it requires a live render; use the editor for GLB.", "operationId": "export_asset_v1_assets__asset_id__export_post", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Asset Id" } }, { "name": "format", "in": "query", "required": true, "schema": { "enum": [ "mjcf", "usd", "usdz", "sdf" ], "type": "string", "description": "Export format: mjcf, usd, usdz, or sdf", "title": "Format" }, "description": "Export format: mjcf, usd, usdz, or sdf" }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "ZIP archive of the exported asset", "content": { "application/json": { "schema": {} }, "application/zip": {} } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Asset not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Export processing error" } } } }, "/v1/scenes/{scene_id}/edit": { "post": { "tags": [ "Scenes" ], "summary": "Edit a scene", "description": "Apply a natural language edit to an existing scene. The AI agent interprets your instruction and modifies the scene graph accordingly.\n\nReturns a `job_id` — poll or stream for progress.", "operationId": "edit_scene_v1_scenes__scene_id__edit_post", "parameters": [ { "name": "scene_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Scene Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditSceneBody" } } } }, "responses": { "202": { "description": "Edit job created", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Scene not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/v1/jobs/{job_id}": { "get": { "tags": [ "Jobs" ], "summary": "Get job status", "description": "Poll the current status of a generation job. Returns the job's status, timing, and optionally the full result payload once complete.\n\n**Status values:** `queued` → `running` → `succeeded` | `failed` | `cancelled`", "operationId": "get_job_v1_jobs__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "include_result", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include the full result payload", "default": false, "title": "Include Result" }, "description": "Include the full result payload" }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": {}, "example": { "ok": true, "job": { "id": "job_a1b2c3d4", "status": "running", "mode": "scene", "scene_id": "jh72k3m4n5p6q7r8", "created_at": 1717800000, "started_at": 1717800001 } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/v1/jobs/{job_id}/events": { "get": { "tags": [ "Jobs" ], "summary": "Job event stream (SSE)", "description": "Real-time Server-Sent Events stream of generation progress. Events include pipeline stage transitions, asset completion notifications, and error reports.\n\nThe stream closes automatically when the job reaches a terminal state (`succeeded`, `failed`, `cancelled`).\n\n**Event types:** `stage_start`, `stage_complete`, `asset_ready`, `error`, `ping`, `done`\n\nUse the `after` parameter to resume from a specific sequence number (e.g., after a reconnection).", "operationId": "job_events_v1_jobs__job_id__events_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "After" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "SSE event stream", "content": { "application/json": { "schema": {} }, "text/event-stream": {} } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/v1/jobs/{job_id}/cancel": { "post": { "tags": [ "Jobs" ], "summary": "Cancel a job", "description": "Request cancellation of a running job. If the job has already completed, this is a no-op.", "operationId": "cancel_job_endpoint_v1_jobs__job_id__cancel_post", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/v1/catalog": { "get": { "tags": [ "Catalog" ], "summary": "Browse premade catalog", "description": "Search and browse the premade asset library. Supports full-text search across names and tags, category filtering, and pagination.", "operationId": "catalog_list_v1_catalog_get", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search term", "title": "Search" }, "description": "Search term" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by category", "title": "Category" }, "description": "Filter by category" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "Paginated catalog results", "content": { "application/json": { "schema": {}, "example": { "ok": true, "items": [ { "slug": "modern-office-chair", "name": "Modern Office Chair", "category": "furniture", "tags": [ "chair", "office" ], "mesh_count": 12, "extent_m": 0.85 } ], "total": 3071, "offset": 0, "limit": 50 } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/v1/catalog/categories": { "get": { "tags": [ "Catalog" ], "summary": "Catalog categories", "description": "Get all available categories in the premade catalog.", "operationId": "catalog_categories_v1_catalog_categories_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/v1/catalog/{slug}": { "get": { "tags": [ "Catalog" ], "summary": "Catalog item detail", "description": "Get full details for a premade catalog item including download paths for GLB and USDZ files.", "operationId": "catalog_detail_v1_catalog__slug__get", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } }, { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Item not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/v1/whoami": { "get": { "tags": [ "Account" ], "summary": "Current user info", "description": "Returns identity information for the authenticated API key — useful for verifying your key works and checking scopes.", "operationId": "whoami_v1_whoami_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "User identity", "content": { "application/json": { "schema": {}, "example": { "ok": true, "user": { "kind": "api_key", "storage_user_id": "user_abc123", "convex_user_id": "jh72k3m4n5p6q7r8", "email": "dev@example.com", "name": "Jane Developer", "scopes": [ "generate:asset", "generate:scene", "read:scenes" ] } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/v1/usage": { "get": { "tags": [ "Account" ], "summary": "API key usage stats", "description": "Get usage statistics for all your API keys — request counts, last used timestamps, and rate limit configuration.", "operationId": "usage_v1_usage_get", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "name": "x-gizmo-service-token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Service-Token" } }, { "name": "x-gizmo-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-User-Id" } }, { "name": "x-gizmo-convex-user-id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Gizmo-Convex-User-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } } }, "components": { "schemas": { "AgentRunRequest": { "properties": { "message": { "type": "string", "minLength": 1, "title": "Message" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "scene_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scene Id" }, "asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Asset Id" }, "editor_mode": { "type": "boolean", "title": "Editor Mode", "default": false }, "scene_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Scene Context" }, "study_index": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Study Index" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "max_turns": { "type": "integer", "maximum": 80, "minimum": 1, "title": "Max Turns", "default": 20 }, "sandbox": { "type": "boolean", "title": "Sandbox", "default": false } }, "type": "object", "required": [ "message" ], "title": "AgentRunRequest" }, "ApiErrorDetail": { "properties": { "code": { "type": "string", "title": "Code", "description": "Machine-readable error code", "examples": [ "scene_not_found" ] }, "message": { "type": "string", "title": "Message", "description": "Human-readable description", "examples": [ "Scene sc_abc123 not found" ] }, "status": { "type": "integer", "title": "Status", "description": "HTTP status code", "examples": [ 404 ] } }, "type": "object", "required": [ "code", "message", "status" ], "title": "ApiErrorDetail" }, "ApiErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ApiErrorDetail" } }, "type": "object", "required": [ "error" ], "title": "ApiErrorResponse" }, "ApplySceneOperationsRequest": { "properties": { "operations": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Operations" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "scene_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scene Id" }, "scene": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Scene" }, "persist": { "type": "boolean", "title": "Persist", "default": false }, "allow_destructive": { "type": "boolean", "title": "Allow Destructive", "default": false } }, "type": "object", "title": "ApplySceneOperationsRequest" }, "AuthorJobClaimRequest": { "properties": { "worker_id": { "type": "string", "minLength": 1, "title": "Worker Id" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "lease_seconds": { "type": "integer", "maximum": 7200, "minimum": 30, "title": "Lease Seconds", "default": 600 } }, "type": "object", "required": [ "worker_id" ], "title": "AuthorJobClaimRequest" }, "AuthorJobCreateRequest": { "properties": { "prompt": { "type": "string", "minLength": 1, "title": "Prompt" }, "mode": { "type": "string", "enum": [ "auto", "scene", "asset", "asset_batch", "edit", "asset_and_place", "structure", "add_structure", "backdrop", "placement", "terrain", "response" ], "title": "Mode", "default": "auto" }, "place": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Place" }, "asset_briefs": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Asset Briefs" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "scene_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scene Id" }, "asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Asset Id" }, "instance_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instance Id" }, "scene": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Scene" }, "current_scene": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Current Scene" }, "scene_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Scene Context" }, "floorplan": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Floorplan" }, "persist": { "type": "boolean", "title": "Persist", "default": false }, "allow_destructive": { "type": "boolean", "title": "Allow Destructive", "default": false }, "reference_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reference Notes" }, "asset_pipeline": { "type": "string", "enum": [ "auto", "gizmo", "cad" ], "title": "Asset Pipeline", "default": "auto" }, "placement_tier": { "anyOf": [ { "type": "string", "enum": [ "floor", "surface", "wall", "ceiling" ] }, { "type": "null" } ], "title": "Placement Tier" }, "fidelity_tier": { "anyOf": [ { "type": "string", "enum": [ "articulated", "static", "background" ] }, { "type": "null" } ], "title": "Fidelity Tier" }, "target_max_dim": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Target Max Dim" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "instance_count": { "type": "integer", "maximum": 20, "minimum": 1, "title": "Instance Count", "default": 1 }, "plan_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan Id" }, "plan_entry_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan Entry Name" }, "client_trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Trace Id" }, "user_message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Message Id" }, "assistant_message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assistant Message Id" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "use_premade_library": { "type": "boolean", "title": "Use Premade Library", "default": true }, "pinned_premade_slugs": { "items": { "type": "string" }, "type": "array", "title": "Pinned Premade Slugs" }, "procedural_structure": { "type": "boolean", "title": "Procedural Structure", "default": true }, "parent_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Event Id" }, "reference_image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reference Image" }, "reference_image_urls": { "items": { "type": "string" }, "type": "array", "title": "Reference Image Urls" }, "scene_reference_image_urls": { "items": { "type": "string" }, "type": "array", "title": "Scene Reference Image Urls" }, "execution": { "type": "string", "enum": [ "direct", "sandbox_agent" ], "title": "Execution", "default": "direct" }, "dispatch": { "anyOf": [ { "type": "string", "enum": [ "inline", "external", "modal" ] }, { "type": "null" } ], "title": "Dispatch" }, "max_turns": { "type": "integer", "maximum": 120, "minimum": 1, "title": "Max Turns", "default": 40 }, "max_attempts": { "type": "integer", "maximum": 10, "minimum": 1, "title": "Max Attempts", "default": 3 } }, "type": "object", "required": [ "prompt" ], "title": "AuthorJobCreateRequest" }, "AuthorJobHeartbeatRequest": { "properties": { "worker_id": { "type": "string", "minLength": 1, "title": "Worker Id" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "lease_seconds": { "type": "integer", "maximum": 7200, "minimum": 30, "title": "Lease Seconds", "default": 600 } }, "type": "object", "required": [ "worker_id" ], "title": "AuthorJobHeartbeatRequest" }, "AuthorRunRequest": { "properties": { "prompt": { "type": "string", "minLength": 1, "title": "Prompt" }, "mode": { "type": "string", "enum": [ "auto", "scene", "asset", "asset_batch", "edit", "asset_and_place", "structure", "add_structure", "backdrop", "placement", "terrain", "response" ], "title": "Mode", "default": "auto" }, "place": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Place" }, "asset_briefs": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Asset Briefs" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "scene_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scene Id" }, "asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Asset Id" }, "instance_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instance Id" }, "scene": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Scene" }, "current_scene": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Current Scene" }, "scene_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Scene Context" }, "floorplan": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Floorplan" }, "persist": { "type": "boolean", "title": "Persist", "default": false }, "allow_destructive": { "type": "boolean", "title": "Allow Destructive", "default": false }, "reference_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reference Notes" }, "asset_pipeline": { "type": "string", "enum": [ "auto", "gizmo", "cad" ], "title": "Asset Pipeline", "default": "auto" }, "placement_tier": { "anyOf": [ { "type": "string", "enum": [ "floor", "surface", "wall", "ceiling" ] }, { "type": "null" } ], "title": "Placement Tier" }, "fidelity_tier": { "anyOf": [ { "type": "string", "enum": [ "articulated", "static", "background" ] }, { "type": "null" } ], "title": "Fidelity Tier" }, "target_max_dim": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Target Max Dim" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "instance_count": { "type": "integer", "maximum": 20, "minimum": 1, "title": "Instance Count", "default": 1 }, "plan_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan Id" }, "plan_entry_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan Entry Name" }, "client_trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Trace Id" }, "user_message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Message Id" }, "assistant_message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assistant Message Id" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "use_premade_library": { "type": "boolean", "title": "Use Premade Library", "default": true }, "pinned_premade_slugs": { "items": { "type": "string" }, "type": "array", "title": "Pinned Premade Slugs" }, "procedural_structure": { "type": "boolean", "title": "Procedural Structure", "default": true }, "parent_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Event Id" }, "reference_image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reference Image" }, "reference_image_urls": { "items": { "type": "string" }, "type": "array", "title": "Reference Image Urls" }, "scene_reference_image_urls": { "items": { "type": "string" }, "type": "array", "title": "Scene Reference Image Urls" } }, "type": "object", "required": [ "prompt" ], "title": "AuthorRunRequest" }, "EditSceneBody": { "properties": { "prompt": { "type": "string", "minLength": 1, "title": "Prompt", "description": "Edit instruction", "examples": [ "Add a conveyor belt along the north wall" ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "Override the default LLM model" } }, "type": "object", "required": [ "prompt" ], "title": "EditSceneBody", "description": "Request body for scene editing." }, "EditSceneRequest": { "properties": { "prompt": { "type": "string", "minLength": 1, "title": "Prompt" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "scene_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scene Id" }, "scene": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Scene" }, "scene_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Scene Context" }, "persist": { "type": "boolean", "title": "Persist", "default": false }, "allow_destructive": { "type": "boolean", "title": "Allow Destructive", "default": false }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" } }, "type": "object", "required": [ "prompt" ], "title": "EditSceneRequest" }, "ExportSceneBody": { "properties": { "format": { "type": "string", "enum": [ "mjcf", "usd", "usdz", "sdf" ], "title": "Format", "description": "Export format: mjcf, usd, usdz, or sdf" }, "robot_profile": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Robot Profile", "description": "Robot to embed (e.g. 'franka_panda')" } }, "type": "object", "required": [ "format" ], "title": "ExportSceneBody" }, "GenerateAssetBody": { "properties": { "prompt": { "type": "string", "minLength": 1, "title": "Prompt", "description": "Natural language description of the asset", "examples": [ "A 6-DOF robotic arm with gripper end-effector" ] }, "scene_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scene Id", "description": "Target scene ID. If omitted, a default scene is created." }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "Override the default LLM model" }, "asset_pipeline": { "type": "string", "enum": [ "auto", "gizmo", "cad" ], "title": "Asset Pipeline", "description": "Geometry pipeline", "default": "auto" }, "reference_image_urls": { "items": { "type": "string" }, "type": "array", "maxItems": 3, "title": "Reference Image Urls", "description": "Up to 3 http(s) image URLs grounding the asset's geometry/texture" }, "persist": { "type": "boolean", "title": "Persist", "description": "Whether to persist to S3", "default": true } }, "type": "object", "required": [ "prompt" ], "title": "GenerateAssetBody", "description": "Request body for asset generation." }, "GenerateAssetRequest": { "properties": { "prompt": { "type": "string", "minLength": 1, "title": "Prompt" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "scene_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scene Id" }, "asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Asset Id" }, "persist": { "type": "boolean", "title": "Persist", "default": false }, "reference_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reference Notes" }, "asset_pipeline": { "type": "string", "enum": [ "auto", "gizmo", "cad" ], "title": "Asset Pipeline", "default": "auto" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "use_premade_library": { "type": "boolean", "title": "Use Premade Library", "default": true } }, "type": "object", "required": [ "prompt" ], "title": "GenerateAssetRequest" }, "GenerateSceneBody": { "properties": { "prompt": { "type": "string", "minLength": 1, "title": "Prompt", "description": "Natural language description of the scene to generate", "examples": [ "A modern robotics lab with two workbenches and a mobile manipulator" ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "Override the default LLM model" }, "asset_pipeline": { "type": "string", "enum": [ "auto", "gizmo", "cad" ], "title": "Asset Pipeline", "description": "Asset geometry pipeline: 'auto' (recommended), 'gizmo' (parametric), or 'cad' (B-Rep)", "default": "auto" }, "reference_image_urls": { "items": { "type": "string" }, "type": "array", "maxItems": 3, "title": "Reference Image Urls", "description": "Up to 3 http(s) image URLs grounding the generation (room photo, product shot). A reference automatically selects the photo-grounded structure build." }, "persist": { "type": "boolean", "title": "Persist", "description": "Whether to save the scene to your library", "default": true } }, "type": "object", "required": [ "prompt" ], "title": "GenerateSceneBody", "description": "Request body for scene generation." }, "GenerateSceneRequest": { "properties": { "prompt": { "type": "string", "minLength": 1, "title": "Prompt" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "scene_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scene Id" }, "current_scene": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Current Scene" }, "persist": { "type": "boolean", "title": "Persist", "default": false }, "reference_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reference Notes" }, "asset_pipeline": { "type": "string", "enum": [ "auto", "gizmo", "cad" ], "title": "Asset Pipeline", "default": "auto" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "procedural_structure": { "type": "boolean", "title": "Procedural Structure", "default": true } }, "type": "object", "required": [ "prompt" ], "title": "GenerateSceneRequest" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "PlanDispatchRequest": { "properties": { "client_trace_id": { "type": "string", "minLength": 1, "title": "Client Trace Id" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" } }, "type": "object", "required": [ "client_trace_id" ], "title": "PlanDispatchRequest", "description": "POST /agent/plan/dispatch — durably execute an approved generation plan.\n\nBelt-and-suspenders for the in-process approval waiter (plan_gate.py):\nthe PlanCard calls this right after its Convex approve mutation so\napproval does not depend on the waiter task surviving. Idempotent —\ndispatch is claimed atomically via generationPlans:claimDispatch, so a\nplan can only ever fan out once no matter how many callers race." }, "SolveScenePlacementRequest": { "properties": { "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "scene_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scene Id" }, "scene": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Scene" }, "floorplan": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Floorplan" }, "asset_records": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Asset Records" }, "persist": { "type": "boolean", "title": "Persist", "default": false } }, "type": "object", "title": "SolveScenePlacementRequest" }, "SupervisorChatRequest": { "properties": { "message": { "type": "string", "minLength": 1, "title": "Message" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "scene_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scene Id" }, "asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Asset Id" }, "scene": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Scene" }, "current_scene": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Current Scene" }, "scene_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Scene Context" }, "floorplan": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Floorplan" }, "active_job_ids": { "items": { "type": "string" }, "type": "array", "title": "Active Job Ids" }, "chat_history": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Chat History" }, "persist": { "type": "boolean", "title": "Persist", "default": true }, "execution": { "type": "string", "enum": [ "direct", "sandbox_agent" ], "title": "Execution", "default": "direct" }, "dispatch": { "anyOf": [ { "type": "string", "enum": [ "inline", "external", "modal" ] }, { "type": "null" } ], "title": "Dispatch" }, "max_turns": { "type": "integer", "maximum": 80, "minimum": 1, "title": "Max Turns", "default": 24 }, "author_max_turns": { "type": "integer", "maximum": 120, "minimum": 1, "title": "Author Max Turns", "default": 80 }, "client_trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Trace Id" }, "user_message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Message Id" }, "assistant_message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assistant Message Id" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "author_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author Model" }, "use_premade_library": { "type": "boolean", "title": "Use Premade Library", "default": true }, "pinned_premade_slugs": { "items": { "type": "string" }, "type": "array", "title": "Pinned Premade Slugs" }, "procedural_structure": { "type": "boolean", "title": "Procedural Structure", "default": true }, "reference_image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reference Image" }, "reference_image_urls": { "items": { "type": "string" }, "type": "array", "title": "Reference Image Urls" }, "available_library_assets": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Available Library Assets" } }, "type": "object", "required": [ "message" ], "title": "SupervisorChatRequest" }, "UpdateSceneBody": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "New scene name", "examples": [ "Kitchen v2" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "New scene description" } }, "type": "object", "title": "UpdateSceneBody", "description": "Request body for updating scene metadata." }, "ValidateUsdRequest": { "properties": { "usda": { "type": "string", "minLength": 1, "title": "Usda", "description": "Raw USDA file content" }, "strict": { "type": "boolean", "title": "Strict", "description": "Treat ComplianceChecker errors as hard failures", "default": false } }, "type": "object", "required": [ "usda" ], "title": "ValidateUsdRequest", "description": "POST /validate-usd — validate raw USDA text via OpenUSD." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VerifySceneRequest": { "properties": { "scene": { "additionalProperties": true, "type": "object", "title": "Scene" }, "fix_floating": { "type": "boolean", "title": "Fix Floating", "default": false }, "calibrate_physics": { "type": "boolean", "title": "Calibrate Physics", "default": true } }, "type": "object", "required": [ "scene" ], "title": "VerifySceneRequest" } } }, "tags": [ { "name": "Scenes", "description": "Create, retrieve, update, and delete 3D simulation scenes. Generation is async — `POST /v1/scenes` returns a `job_id` for polling." }, { "name": "Assets", "description": "Manage individual 3D assets (articulated objects, furniture, equipment). Each asset belongs to a scene and contains geometry, joints, materials, and physics data." }, { "name": "Jobs", "description": "Monitor and control async generation jobs. Poll with `GET /v1/jobs/{id}`, stream real-time progress via `GET /v1/jobs/{id}/events` (SSE), or cancel with `POST /v1/jobs/{id}/cancel`." }, { "name": "Catalog", "description": "Browse the premade asset library — thousands of physics-ready 3D objects organized by category. Download GLB/USDZ directly." }, { "name": "Account", "description": "View your identity and API usage statistics." } ], "servers": [ { "url": "https://api.gizmo.antimlabs.com", "description": "Production" } ] }