{ "openapi": "3.1.0", "info": { "title": "Bitbybit CAD Cloud API", "version": "1.0.0-rc.1", "description": "High-performance parametric CAD model generation, STEP conversion, and CAD operation execution via a Bitbybit cloud API.\n\nAll async endpoints return **HTTP 202** with a task ID. Poll the task until completion, then retrieve the result download URL.\n\n**Base URL:** `https://api.bitbybit.dev`\n\n**Authentication:** Pass your API key via the `x-api-key` header. Keys are scoped - each endpoint documents which scope is required.\n\n**TypeScript SDK:** Install `@bitbybit-dev/cad-cloud-api` for a type-safe Node.js client with built-in polling.", "contact": { "name": "Bitbybit", "url": "https://bitbybit.dev", "email": "info@bitbybit.dev" }, "license": { "name": "Proprietary", "url": "https://bitbybit.dev/terms-and-conditions" } }, "servers": [ { "url": "https://api.bitbybit.dev", "description": "Production" } ], "tags": [ { "name": "Health", "description": "Service health checks (no auth required)" }, { "name": "Models", "description": "Parametric CAD model generation. Requires the `models` scope." }, { "name": "Tasks", "description": "Async task management — status, results, cancellation, retry. Requires the `tasks` scope." }, { "name": "CAD", "description": "Direct CAD operations — execute, pipeline, compound. Requires the `cad` scope." }, { "name": "Convert", "description": "STEP → glTF file conversion. Requires the `convert` scope." }, { "name": "Files", "description": "File upload, confirmation, and management. Requires the `files` scope." } ], "paths": { "/health": { "get": { "tags": [ "Health" ], "summary": "Health check", "operationId": "healthCheck", "security": [], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "instance": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/v1/models": { "get": { "tags": [ "Models" ], "summary": "List available models", "operationId": "listModels", "responses": { "200": { "description": "List of registered parametric model names", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse_ModelList" }, "example": { "ok": true, "data": { "models": [ "dragon-cup", "phone-nest" ] } } } } } } } }, "/api/v1/models/{modelName}/params": { "get": { "tags": [ "Models" ], "summary": "Get model parameter definitions", "operationId": "getModelParams", "parameters": [ { "name": "modelName", "in": "path", "required": true, "schema": { "type": "string" }, "example": "dragon-cup" } ], "responses": { "200": { "description": "Parameter definitions with types, descriptions, and defaults", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse_ModelDefinition" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/models/definitions": { "post": { "tags": [ "Models" ], "summary": "Batch-fetch model definitions", "operationId": "batchModelDefinitions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "names" ], "properties": { "names": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "example": [ "dragon-cup", "phone-nest" ] } } } } } }, "responses": { "200": { "description": "Definitions keyed by model name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse_BatchDefinitions" } } } } } } }, "/api/v1/models/{modelName}": { "post": { "tags": [ "Models" ], "summary": "Generate a parametric model", "operationId": "generateModel", "description": "Submits a parametric model for generation. Returns **202 Accepted** with a task ID.\n\nPoll `GET /api/v1/tasks/{taskId}` until `status` is `completed`, then fetch the result via `GET /api/v1/tasks/{taskId}/result/{format}`.\n\nSee the model-specific examples below. All model parameters are optional — defaults produce a valid model.", "parameters": [ { "name": "modelName", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "dragon-cup": { "value": "dragon-cup" }, "phone-nest": { "value": "phone-nest" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelSubmission" }, "examples": { "dragon-cup": { "summary": "Dragon Cup — all parameters (defaults)", "value": { "params": { "height": 8, "radiusBottom": 4, "radiusTopOffset": 2, "radiusMidOffset": 2, "rotationTopAngle": 20, "rotationMidAngle": 20, "nrSkinCellsVertical": 5, "nrSkinCellsHorizontal": 10, "nrSkinCellDivisionsTop": 1, "nrSkinCellDivisionsBottom": 3, "skinCellOuterHeight": 0.4, "skinCellInnerHeight": 0.3, "skinCellBottomHeight": 0.4, "skinCellTopHeight": 0.4, "thickness": 0.6, "bottomThickness": 1, "precision": 0.01, "rotation": 0, "scale": 1, "origin": [ 0, 0, 0 ], "direction": [ 0, 1, 0 ] }, "outputs": { "formats": [ "gltf" ] } } }, "phone-nest": { "summary": "Phone Nest — all parameters (defaults)", "value": { "params": { "heightBottom": 5, "heightTop": 16, "widthBack": 25, "widthFront": 10, "length": 16, "backOffset": 6, "thickness": 0.4, "applyOrnaments": false, "filletRadius": 2, "phoneHeight": 16.8, "phoneWidth": 7.8, "phoneThickness": 0.7, "precision": 0.01, "rotation": 0, "scale": 1, "origin": [ 0, 0, 0 ], "direction": [ 0, 1, 0 ] }, "outputs": { "formats": [ "gltf" ] } } } } } } }, "responses": { "202": { "$ref": "#/components/responses/TaskCreated" }, "400": { "$ref": "#/components/responses/ValidationError" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/tasks": { "get": { "tags": [ "Tasks" ], "summary": "List tasks", "operationId": "listTasks", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/TaskStatus" } }, { "name": "kind", "in": "query", "schema": { "$ref": "#/components/schemas/TaskKind" } } ], "responses": { "200": { "description": "Paginated task list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse_TaskList" } } } } } } }, "/api/v1/tasks/{taskId}": { "get": { "tags": [ "Tasks" ], "summary": "Get task status", "operationId": "getTask", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse_TaskDetail" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Tasks" ], "summary": "Cancel a task", "operationId": "cancelTask", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "cancelled": { "type": "boolean" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/tasks/{taskId}/retry": { "post": { "tags": [ "Tasks" ], "summary": "Retry a failed or cancelled task", "operationId": "retryTask", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "$ref": "#/components/responses/TaskCreated" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/tasks/{taskId}/result": { "get": { "tags": [ "Tasks" ], "summary": "Get task result (default format)", "operationId": "getTaskResult", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pre-signed download URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse_TaskResultDownload" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/tasks/{taskId}/result/{format}": { "get": { "tags": [ "Tasks" ], "summary": "Get task result in a specific format", "operationId": "getTaskResultByFormat", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "glb", "step", "stpz", "metadata", "decomposed-mesh" ] } } ], "responses": { "200": { "description": "Pre-signed download URL for the requested format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse_TaskResultDownload" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/cad/execute": { "post": { "tags": [ "CAD" ], "summary": "Execute a single CAD operation", "operationId": "cadExecute", "description": "Runs one OCCT operation by its dotted path (e.g. `occt.shapes.solid.createSphere`). Returns **202 Accepted** with a task ID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CadExecuteRequest" }, "example": { "operation": "occt.shapes.solid.createSphere", "params": { "radius": 5, "center": [ 0, 0, 0 ] } } } } }, "responses": { "202": { "$ref": "#/components/responses/TaskCreated" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/cad/pipeline": { "post": { "tags": [ "CAD" ], "summary": "Execute a chained pipeline", "operationId": "cadPipeline", "description": "Runs multiple operations sequentially in a single worker. Use `$ref:N` in params to reference step N's result. Optionally pass `outputs` to convert the final OCCT shape result into downloadable formats (STEP, GLB, decomposed mesh).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CadPipelineRequest" }, "example": { "steps": [ { "operation": "occt.shapes.solid.createSphere", "params": { "radius": 5, "center": [ 0, 0, 0 ] } }, { "operation": "occt.shapes.solid.createCube", "params": { "size": 3, "center": [ 0, 3, 0 ] } }, { "operation": "occt.booleans.union", "params": { "shapes": [ "$ref:0", "$ref:1" ], "keepEdges": false } } ], "outputs": { "formats": [ "step", "gltf" ], "adjustYtoZ": true } } } } }, "responses": { "202": { "$ref": "#/components/responses/TaskCreated" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/convert/step-to-gltf": { "post": { "tags": [ "Convert" ], "summary": "Convert STEP to glTF (simple)", "operationId": "convertStepToGltf", "description": "Upload a STEP file first via the Files API, then convert it to glTF. Returns **202 Accepted** with a task ID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertSimpleRequest" }, "example": { "stepFileId": "file-uuid-here", "meshPrecision": 0.1 } } } }, "responses": { "202": { "$ref": "#/components/responses/TaskCreated" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/convert/step-to-gltf-advanced": { "post": { "tags": [ "Convert" ], "summary": "Convert STEP to glTF (advanced)", "operationId": "convertStepToGltfAdvanced", "description": "Full-control STEP → glTF conversion with mesh, export, and coordinate options. Returns **202 Accepted** with a task ID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertAdvancedRequest" }, "example": { "stepFileId": "file-uuid-here", "options": { "readColors": true, "readNames": true, "readMaterials": true, "readLayers": false, "readProps": false, "meshDeflection": 0.01, "meshAngle": 0.5, "meshParallel": true, "faceCountThreshold": -1, "mergeFaces": false, "splitIndices16": false, "parallelWrite": false, "embedTextures": true, "forceUVExport": false, "nodeNameFormat": "instanceOrProduct", "meshNameFormat": "instanceOrProduct", "transformFormat": "compact", "adjustZtoY": true, "scale": 1 } } } } }, "responses": { "202": { "$ref": "#/components/responses/TaskCreated" }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/v1/files/upload": { "post": { "tags": [ "Files" ], "summary": "Request a file upload URL", "operationId": "requestUpload", "description": "Returns a pre-signed URL. PUT your file bytes to that URL, then call `POST /api/v1/files/{fileId}/confirm`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadRequest" }, "example": { "filename": "model.stp", "contentType": "application/octet-stream", "bytes": 102400, "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } } } }, "responses": { "201": { "description": "Upload URL created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse_UploadResult" } } } } } } }, "/api/v1/files/{fileId}/confirm": { "post": { "tags": [ "Files" ], "summary": "Confirm file upload", "operationId": "confirmUpload", "description": "Call after PUTting file bytes to the pre-signed upload URL.", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "File confirmed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse_ConfirmResult" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/files/{fileId}": { "get": { "tags": [ "Files" ], "summary": "Get file details", "operationId": "getFile", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "File details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse_FileDetail" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Files" ], "summary": "Delete a file", "operationId": "deleteFile", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "File deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/files": { "get": { "tags": [ "Files" ], "summary": "List files", "operationId": "listFiles", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "confirmed", "expired" ] } } ], "responses": { "200": { "description": "Paginated file list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse_FileList" } } } } } } } }, "components": { "responses": { "TaskCreated": { "description": "Task accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse_TaskCreated" }, "example": { "ok": true, "data": { "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "queued", "statusUrl": "/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } }, "ValidationError": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "VALIDATION_ERROR", "message": "'outputs.formats' must be a non-empty array" } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "ok": false, "error": { "code": "NOT_FOUND", "message": "Task not found" } } } } } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "details": { "description": "Optional structured error context" }, "requestId": { "type": "string" } } } } }, "TaskStatus": { "type": "string", "enum": [ "waiting", "queued", "processing", "completed", "failed", "cancelled", "expired" ] }, "TaskKind": { "type": "string", "enum": [ "cad", "model", "convert-simple", "convert-advanced", "pipeline", "compound" ] }, "ResultPartMeta": { "type": "object", "properties": { "mime": { "type": "string" }, "bytes": { "type": "integer" } } }, "TaskDetail": { "type": "object", "required": [ "taskId", "kind", "label", "status", "createdAt", "expiresAt" ], "properties": { "taskId": { "type": "string", "format": "uuid" }, "kind": { "$ref": "#/components/schemas/TaskKind" }, "label": { "type": "string", "example": "Model: dragon-cup" }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "progress": { "type": "number", "minimum": 0, "maximum": 1, "nullable": true }, "error": { "type": "string", "nullable": true }, "resultParts": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ResultPartMeta" }, "nullable": true }, "metadata": { "type": "object", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "finishedAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time" } } }, "TaskCreatedResult": { "type": "object", "required": [ "taskId", "status", "statusUrl" ], "properties": { "taskId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued" ] }, "statusUrl": { "type": "string", "example": "/api/v1/tasks/{taskId}" } } }, "TaskResultDownload": { "type": "object", "required": [ "downloadUrl", "filename" ], "properties": { "downloadUrl": { "type": "string", "format": "uri" }, "filename": { "type": "string", "example": "result.glb" } } }, "OutputFormat": { "type": "string", "enum": [ "step", "stpz", "decomposed-mesh", "gltf" ] }, "OutputOptions": { "type": "object", "required": [ "formats" ], "properties": { "formats": { "type": "array", "items": { "$ref": "#/components/schemas/OutputFormat" }, "minItems": 1, "description": "Output formats to generate" }, "meshPrecision": { "type": "number", "minimum": 0.005, "maximum": 10, "description": "Mesh tessellation precision (lower = finer)" }, "gltfMeshPrecision": { "type": "number", "minimum": 0.005, "maximum": 10, "description": "glTF-specific mesh deflection" }, "adjustYtoZ": { "type": "boolean", "default": false, "description": "Swap Y↔Z axis for mesh/glTF output" } } }, "ModelSubmission": { "type": "object", "required": [ "outputs" ], "properties": { "params": { "type": "object", "description": "Model-specific parameters (all optional, defaults apply)" }, "outputs": { "$ref": "#/components/schemas/OutputOptions" } } }, "ModelParamDefinition": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "number", "integer", "boolean", "array" ] }, "description": { "type": "string" }, "default": {}, "items": { "type": "object" } } }, "ModelDefinition": { "type": "object", "properties": { "name": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "params": { "type": "array", "items": { "$ref": "#/components/schemas/ModelParamDefinition" } }, "defaults": { "type": "object" } } }, "CadExecuteRequest": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "type": "string", "description": "Dotted path to an OCCT operation", "example": "occt.shapes.solid.createSphere" }, "params": { "type": "object", "description": "Operation-specific parameters" } } }, "CadPipelineRequest": { "type": "object", "required": [ "steps" ], "properties": { "steps": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "type": "string" }, "params": { "type": "object", "description": "Use `$ref:N` to reference step N's result" } } } }, "outputs": { "$ref": "#/components/schemas/OutputOptions", "description": "Optional. When provided, the final pipeline result (if it is an OCCT shape) is converted to the requested formats and the task produces downloadable result parts (step, glb, decomposed-mesh, etc.). When omitted, the raw pipeline result is returned as JSON." } } }, "CadCompoundRequest": { "type": "object", "required": [ "parallel", "items" ], "properties": { "parallel": { "type": "boolean", "enum": [ true ] }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "type": "string" }, "params": { "type": "object" }, "inputFiles": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string" }, "role": { "type": "string" } } } }, "outputFormats": { "type": "array", "items": { "type": "string" }, "maxItems": 10 } } } } } }, "ConvertSimpleRequest": { "type": "object", "required": [ "stepFileId" ], "properties": { "stepFileId": { "type": "string", "format": "uuid", "description": "File ID from POST /api/v1/files/upload + confirm" }, "meshPrecision": { "type": "number", "minimum": 0.005, "maximum": 10, "description": "Mesh tessellation precision" } } }, "ConvertAdvancedRequest": { "type": "object", "required": [ "stepFileId" ], "properties": { "stepFileId": { "type": "string", "format": "uuid" }, "options": { "type": "object", "description": "Advanced conversion options — all optional", "properties": { "readColors": { "type": "boolean" }, "readNames": { "type": "boolean" }, "readMaterials": { "type": "boolean" }, "readLayers": { "type": "boolean" }, "readProps": { "type": "boolean" }, "meshDeflection": { "type": "number", "minimum": 0.005, "maximum": 10 }, "meshAngle": { "type": "number", "minimum": 0.01, "maximum": 3.14159 }, "meshParallel": { "type": "boolean" }, "faceCountThreshold": { "type": "integer", "minimum": -1, "maximum": 500000 }, "mergeFaces": { "type": "boolean" }, "splitIndices16": { "type": "boolean" }, "parallelWrite": { "type": "boolean" }, "embedTextures": { "type": "boolean" }, "forceUVExport": { "type": "boolean" }, "nodeNameFormat": { "type": "string", "enum": [ "empty", "product", "instance", "instanceOrProduct", "productOrInstance", "productAndInstance", "productAndInstanceAndOcaf" ] }, "meshNameFormat": { "type": "string", "enum": [ "empty", "product", "instance", "instanceOrProduct", "productOrInstance", "productAndInstance", "productAndInstanceAndOcaf" ] }, "transformFormat": { "type": "string", "enum": [ "compact", "mat4", "trs" ] }, "adjustZtoY": { "type": "boolean" }, "scale": { "type": "number", "minimum": 0.000001, "maximum": 1000 } } } } }, "UploadRequest": { "type": "object", "required": [ "filename", "contentType", "bytes" ], "properties": { "filename": { "type": "string", "maxLength": 255 }, "contentType": { "type": "string", "maxLength": 255 }, "bytes": { "type": "integer", "minimum": 1 }, "sha256": { "type": "string", "description": "Optional hash for deduplication" } } }, "UploadResult": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid" }, "uploadUrl": { "type": "string", "format": "uri", "description": "PUT file bytes here" }, "expiresIn": { "type": "integer" }, "maxBytes": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending" ] } } }, "ConfirmResult": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "confirmed" ] }, "bytes": { "type": "integer" }, "contentType": { "type": "string" } } }, "FileDetail": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "bytes": { "type": "integer", "nullable": true }, "sha256": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "confirmed", "expired" ] }, "createdAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true }, "downloadUrl": { "type": "string", "format": "uri" } } }, "SuccessResponse_TaskCreated": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TaskCreatedResult" } } }, "SuccessResponse_TaskDetail": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TaskDetail" } } }, "SuccessResponse_TaskList": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/TaskDetail" } }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" } } } } }, "SuccessResponse_TaskResultDownload": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TaskResultDownload" } } }, "SuccessResponse_ModelList": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "string" } } } } } }, "SuccessResponse_ModelDefinition": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ModelDefinition" } } }, "SuccessResponse_BatchDefinitions": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "definitions": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ModelDefinition" } } } } } }, "SuccessResponse_UploadResult": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/UploadResult" } } }, "SuccessResponse_ConfirmResult": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ConfirmResult" } } }, "SuccessResponse_FileDetail": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/FileDetail" } } }, "SuccessResponse_FileList": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/FileDetail" } }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" } } } } }, "DragonCupParams": { "type": "object", "description": "Dragon Cup parameters — all optional, sane defaults apply", "properties": { "height": { "type": "number", "description": "Total cup height (cm)", "default": 8 }, "radiusBottom": { "type": "number", "description": "Radius at the base (cm)", "default": 4 }, "radiusTopOffset": { "type": "number", "description": "How much the top radius differs from bottom", "default": 2 }, "radiusMidOffset": { "type": "number", "description": "Mid-section radius offset", "default": 2 }, "rotationTopAngle": { "type": "number", "description": "Top twist angle (degrees)", "default": 20 }, "rotationMidAngle": { "type": "number", "description": "Mid twist angle (degrees)", "default": 20 }, "nrSkinCellsVertical": { "type": "integer", "description": "Vertical skin cell count", "default": 5 }, "nrSkinCellsHorizontal": { "type": "integer", "description": "Horizontal skin cell count", "default": 10 }, "nrSkinCellDivisionsTop": { "type": "integer", "description": "Subdivisions at top of each cell", "default": 1 }, "nrSkinCellDivisionsBottom": { "type": "integer", "description": "Subdivisions at bottom of each cell", "default": 3 }, "skinCellOuterHeight": { "type": "number", "description": "Outer cell extrusion height", "default": 0.4 }, "skinCellInnerHeight": { "type": "number", "description": "Inner cell extrusion height", "default": 0.3 }, "skinCellBottomHeight": { "type": "number", "description": "Bottom cell height", "default": 0.4 }, "skinCellTopHeight": { "type": "number", "description": "Top cell height", "default": 0.4 }, "thickness": { "type": "number", "description": "Shell wall thickness", "default": 0.6 }, "bottomThickness": { "type": "number", "description": "Bottom plate thickness", "default": 1 }, "precision": { "type": "number", "description": "OCCT geometry precision (lower = finer)", "default": 0.01 }, "rotation": { "type": "number", "description": "Final rotation angle (degrees)", "default": 0 }, "scale": { "type": "number", "description": "Uniform scale factor", "default": 1 }, "origin": { "type": "array", "description": "[x, y, z] placement origin", "default": [ 0, 0, 0 ], "items": { "type": "number" } }, "direction": { "type": "array", "description": "[x, y, z] up direction", "default": [ 0, 1, 0 ], "items": { "type": "number" } } } }, "PhoneNestParams": { "type": "object", "description": "Phone Nest parameters — all optional, sane defaults apply", "properties": { "heightBottom": { "type": "number", "description": "Height of the bottom section (cm)", "default": 5 }, "heightTop": { "type": "number", "description": "Height of the top section (cm)", "default": 16 }, "widthBack": { "type": "number", "description": "Width at the back (cm)", "default": 25 }, "widthFront": { "type": "number", "description": "Width at the front (cm)", "default": 10 }, "length": { "type": "number", "description": "Depth / length (cm)", "default": 16 }, "backOffset": { "type": "number", "description": "Back curve offset (cm)", "default": 6 }, "thickness": { "type": "number", "description": "Shell wall thickness", "default": 0.4 }, "applyOrnaments": { "type": "boolean", "description": "Add decorative perforations to the surface", "default": false }, "filletRadius": { "type": "number", "description": "Fillet radius on loft edges", "default": 2 }, "phoneHeight": { "type": "number", "description": "Phone mock-up height (cm)", "default": 16.8 }, "phoneWidth": { "type": "number", "description": "Phone mock-up width (cm)", "default": 7.8 }, "phoneThickness": { "type": "number", "description": "Phone mock-up thickness (cm)", "default": 0.7 }, "precision": { "type": "number", "description": "OCCT geometry precision (lower = finer)", "default": 0.01 }, "rotation": { "type": "number", "description": "Final rotation angle (degrees)", "default": 0 }, "scale": { "type": "number", "description": "Uniform scale factor", "default": 1 }, "origin": { "type": "array", "description": "[x, y, z] placement origin", "default": [ 0, 0, 0 ], "items": { "type": "number" } }, "direction": { "type": "array", "description": "[x, y, z] up direction", "default": [ 0, 1, 0 ], "items": { "type": "number" } } } } } } }