{
"openapi": "3.1.0",
"info": {
"title": "Bitbybit CAD Cloud API",
"version": "1.3.1",
"description": "High-performance parametric CAD model generation API. Supports multi-format output (STEP, GLTF, decomposed mesh), pipeline execution, file-based conversion, and async job processing.",
"contact": {
"name": "Bitbybit",
"url": "https://bitbybit.dev"
},
"termsOfService": "https://bitbybit.dev/terms-and-conditions",
"license": {
"name": "Proprietary",
"url": "https://bitbybit.dev/terms-and-conditions"
}
},
"servers": [
{
"url": "https://api.bitbybit.dev",
"description": "Production"
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"paths": {
"/health": {
"get": {
"tags": [
"Health"
],
"summary": "Health - status check",
"description": "Returns the operational status of the Bitbybit CAD Cloud API, including service health and readiness. Requires no authentication, so it is suitable for uptime monitoring, load balancer probes and deployment smoke tests.",
"security": [],
"responses": {
"200": {
"description": "Health status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HealthResponse"
}
}
}
}
}
}
},
"/api/v1/cad/execute": {
"post": {
"tags": [
"CAD Operations"
],
"summary": "CAD - execute a single operation",
"description": "Runs a single CAD operation by its fully-qualified identifier.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteBody"
}
}
}
},
"responses": {
"202": {
"description": "Task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/cad/pipeline": {
"post": {
"tags": [
"CAD Operations"
],
"summary": "CAD - execute a chained pipeline",
"description": "Runs multiple operations sequentially. Use '$ref:N' in params to reference step N's result.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PipelineBody"
}
}
}
},
"responses": {
"202": {
"description": "Task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/cad/compound": {
"post": {
"tags": [
"CAD Operations"
],
"summary": "CAD - execute compound (parallel) operations",
"description": "Runs several independent CAD operations in parallel as one compound task. Each sub-operation is executed on its own and produces its own downloadable result, so use this when the operations do not depend on each other - for a sequence where each step consumes the previous one's output, use the chained pipeline endpoint instead. Returns 202 with a compound task id; poll it and download the per-sub-task manifest when it completes.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompoundExecuteBody"
}
}
}
},
"responses": {
"202": {
"description": "Compound task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompoundTaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/models": {
"get": {
"tags": [
"Models"
],
"summary": "Models - list available models",
"description": "Lists every parametric model available for generation, by name. Use the returned names with the definitions and generation endpoints to discover each model's parameter schema and defaults before submitting a job.",
"responses": {
"200": {
"description": "Model name list",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ModelListResponse"
}
}
}
}
}
}
},
"/api/v1/models/definitions": {
"post": {
"tags": [
"Models"
],
"summary": "Models - batch-fetch definitions",
"description": "Returns parameter schemas and defaults for the requested model names.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefinitionsBody"
}
}
}
},
"responses": {
"200": {
"description": "Model definitions",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ModelBatchDefinitionsResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/models/{modelName}": {
"post": {
"tags": [
"Models"
],
"summary": "Models - execute a parametric model",
"description": "Generic endpoint - works for any registered model. See model-specific endpoints for fully typed parameters. Always returns 202 with a task ID for polling.",
"parameters": [
{
"name": "modelName",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Model slug (e.g. dragon-cup, phone-nest)"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ModelSubmissionBody"
}
}
}
},
"responses": {
"202": {
"description": "Task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/models/{modelName}/batch": {
"post": {
"tags": [
"Models"
],
"summary": "Models - generate a batch",
"description": "Creates a compound task with one sub-task per item. Each item can have different parameters but shares the same output config.",
"parameters": [
{
"name": "modelName",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Model slug (e.g. dragon-cup, phone-nest)"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchModelSubmissionBody"
}
}
}
},
"responses": {
"202": {
"description": "Compound task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompoundTaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/models/{modelName}/params": {
"get": {
"tags": [
"Models"
],
"summary": "Models - get parameter definitions",
"description": "Returns parameter schema, types, defaults, and limits for the specified model.",
"parameters": [
{
"name": "modelName",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Model slug (e.g. dragon-cup, phone-nest)"
}
],
"responses": {
"200": {
"description": "Model definition",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ModelDefinitionResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/models/dragon-cup": {
"post": {
"tags": [
"Models - Dragon Cup"
],
"summary": "Models - build a Dragon Cup",
"description": "Parametric dragon-scale textured cup with twisted lofted body, voronoi-like skin cells, and configurable shell thickness. All parameters are optional - defaults produce a ready-to-print model.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"example": {
"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": [
"step",
"gltf"
]
}
},
"schema": {
"$ref": "#/components/schemas/DragonCupBody"
}
}
}
},
"responses": {
"202": {
"description": "Task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/models/phone-nest": {
"post": {
"tags": [
"Models - Phone Nest"
],
"summary": "Models - build a Phone Nest",
"description": "Parametric 3D-printable desktop phone holder/stand with a lofted cradle surface, optional ornamental perforations, and a phone mock-up shape. All parameters are optional - defaults produce a ready-to-print model.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"example": {
"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": [
"step",
"gltf"
]
}
},
"schema": {
"$ref": "#/components/schemas/PhoneNestBody"
}
}
}
},
"responses": {
"202": {
"description": "Task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/convert/step-to-gltf": {
"post": {
"tags": [
"Convert"
],
"summary": "Convert - STEP to glTF (.glb)",
"description": "Simple STEP → glTF conversion using a previously uploaded file. Requires the 'convert' API key scope. Returns 202 with a task ID.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StepToGltfBody"
}
}
}
},
"responses": {
"202": {
"description": "Task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Insufficient scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/convert/step-to-gltf-advanced": {
"post": {
"tags": [
"Convert"
],
"summary": "Convert - STEP to glTF (.glb), advanced options",
"description": "Full-control STEP → glTF conversion with fine-grained mesh, export, and coordinate options. Requires the 'convert' API key scope. Returns 202 with a task ID.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StepToGltfAdvancedBody"
}
}
}
},
"responses": {
"202": {
"description": "Task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Insufficient scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/convert/step-to-gltf-with-draco": {
"post": {
"tags": [
"Convert"
],
"summary": "Convert - STEP to Draco-compressed glTF (.glb)",
"description": "STEP → glTF conversion with Draco geometry compression using a previously uploaded file. Requires the 'convert' API key scope. Returns 202 with a task ID.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StepToGltfWithDracoBody"
}
}
}
},
"responses": {
"202": {
"description": "Task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Insufficient scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/convert/step-to-gltf-advanced-with-draco": {
"post": {
"tags": [
"Convert"
],
"summary": "Convert - STEP to Draco-compressed glTF (.glb), advanced options",
"description": "Full-control STEP → glTF conversion with Draco geometry compression. Combines fine-grained mesh, export, and coordinate options with Draco quantization controls. Requires the 'convert' API key scope. Returns 202 with a task ID.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StepToGltfAdvancedWithDracoBody"
}
}
}
},
"responses": {
"202": {
"description": "Task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Insufficient scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/cad/pro/unfold/face-to-flat": {
"post": {
"tags": [
"Sheet Metal"
],
"summary": "Sheet metal - unfold a face to flat geometry",
"description": "Proprietary sheet-metal unfold: flattens a single developable face (by index) of an uploaded STEP shape. Requires the 'cad' API key scope. Returns 202 with a task ID; the flattened geometry is delivered as the task's output files.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnfoldFaceToFlatBody"
}
}
}
},
"responses": {
"202": {
"description": "Task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Insufficient scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/cad/pro/unfold/face-report": {
"post": {
"tags": [
"Sheet Metal"
],
"summary": "Sheet metal - unfold a face, metrics report",
"description": "Proprietary sheet-metal analysis: computes the unfold metrics report (developability, area, ...) for a single face of an uploaded STEP shape. Requires the 'cad' API key scope. Returns 202 with a task ID; the JSON report is delivered in the task metadata.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnfoldFaceReportBody"
}
}
}
},
"responses": {
"202": {
"description": "Task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Insufficient scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/cad/pro/unfold/solid-to-flat": {
"post": {
"tags": [
"Sheet Metal"
],
"summary": "Sheet metal - unfold all solids to flat geometry",
"description": "Proprietary sheet-metal unfold: loads every solid in an uploaded STEP file and flattens each to a flat pattern. Requires the 'cad' API key scope. Returns 202 with a task ID; all flats are combined into one compound output per format.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnfoldSolidToFlatBody"
}
}
}
},
"responses": {
"202": {
"description": "Task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Insufficient scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/cad/pro/unfold/solid-report": {
"post": {
"tags": [
"Sheet Metal"
],
"summary": "Sheet metal - unfold all solids, metrics report",
"description": "Proprietary sheet-metal analysis: computes per-solid unfold metrics for every solid in an uploaded STEP file. Requires the 'cad' API key scope. Returns 202 with a task ID; the JSON report array is delivered in the task metadata.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnfoldSolidReportBody"
}
}
}
},
"responses": {
"202": {
"description": "Task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Insufficient scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/cad/pro/unfold/solid": {
"post": {
"tags": [
"Sheet Metal"
],
"summary": "Sheet metal - unfold all solids, geometry + report",
"description": "Proprietary sheet-metal unfold, full workflow: flattens every solid in an uploaded STEP file AND returns per-solid metrics in one call. Requires the 'cad' API key scope. Returns 202 with a task ID; flats are combined into one compound output per format and the per-solid report array is delivered in the task metadata.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnfoldSolidBody"
}
}
}
},
"responses": {
"202": {
"description": "Task accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Insufficient scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/files/upload": {
"post": {
"tags": [
"Files"
],
"summary": "Files - request an upload URL",
"description": "Returns a pre-signed URL for uploading a file via PUT.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileUploadBody"
}
}
}
},
"responses": {
"201": {
"description": "Upload URL and file ID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadResponse"
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/files": {
"get": {
"tags": [
"Files"
],
"summary": "Files - list uploaded files",
"description": "Returns a paginated list of the files uploaded under your API key, newest first, with each file's id, original name, size, upload status and expiry. Use it to find the file id to pass to a conversion endpoint, and to check that an upload through a pre-signed URL actually completed before you reference it.",
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"description": "1-based page number. Defaults to the first page.",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "How many files to return per page.",
"schema": {
"type": "integer",
"default": 20
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "Return only files in this upload state: pending (a pre-signed URL was issued but the upload has not been confirmed), confirmed (the blob is stored and usable), or expired.",
"schema": {
"type": "string",
"enum": [
"pending",
"confirmed",
"expired"
]
}
}
],
"responses": {
"200": {
"description": "File list",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileListResponse"
}
}
}
}
}
}
},
"/api/v1/files/{fileId}": {
"get": {
"tags": [
"Files"
],
"summary": "Files - get file details",
"description": "Returns metadata and download URL for a single file.",
"parameters": [
{
"name": "fileId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "File ID"
}
],
"responses": {
"200": {
"description": "File details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileDetailResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": [
"Files"
],
"summary": "Files - delete a file",
"description": "Permanently deletes an uploaded file and the stored blob behind it. This cannot be undone, and any task result that still points at the blob stops resolving. Files also expire on their own, so call this only when you need the storage released sooner than that.",
"parameters": [
{
"name": "fileId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "File ID"
}
],
"responses": {
"200": {
"description": "File deleted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteFileResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/files/{fileId}/confirm": {
"post": {
"tags": [
"Files"
],
"summary": "Files - confirm upload",
"description": "Confirms that the file was successfully uploaded to the pre-signed URL.",
"parameters": [
{
"name": "fileId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "File ID"
}
],
"responses": {
"200": {
"description": "File confirmed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConfirmResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/tasks": {
"get": {
"tags": [
"Tasks"
],
"summary": "Tasks - list tasks",
"description": "Returns a paginated list of your tasks, newest first, each with its id, kind, status, creation time and result link when finished. Filter by status to poll only what is still running, or by kind to separate model generation, STEP conversion, pipelines and compound runs. This is the endpoint to build a job dashboard on rather than polling every task id individually.",
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"description": "1-based page number. Defaults to the first page.",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "How many tasks to return per page.",
"schema": {
"type": "integer",
"default": 20
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "Return only tasks in this state. waiting and queued are not started yet, processing is running, completed has a downloadable result, failed carries an error, cancelled was stopped by you, and expired means the result has been cleaned up.",
"schema": {
"type": "string",
"enum": [
"waiting",
"queued",
"processing",
"completed",
"failed",
"cancelled",
"expired"
]
}
},
{
"name": "kind",
"in": "query",
"required": false,
"description": "Return only tasks of this kind: cad for a single operation, model for a registered parametric model, convert-simple and convert-advanced for STEP conversions, pipeline for a chained run, compound for a parallel run.",
"schema": {
"type": "string",
"enum": [
"cad",
"model",
"convert-simple",
"convert-advanced",
"pipeline",
"compound"
]
}
}
],
"responses": {
"200": {
"description": "Task list",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskListResponse"
}
}
}
}
}
}
},
"/api/v1/tasks/{taskId}": {
"get": {
"tags": [
"Tasks"
],
"summary": "Tasks - get task status",
"description": "Returns the current status and metadata of a task.",
"parameters": [
{
"name": "taskId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Task ID"
}
],
"responses": {
"200": {
"description": "Task status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskDetailResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
},
"delete": {
"tags": [
"Tasks"
],
"summary": "Tasks - cancel a task",
"description": "Cancels a waiting or queued task. Has no effect on completed/failed tasks.",
"parameters": [
{
"name": "taskId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Task ID"
}
],
"responses": {
"200": {
"description": "Task cancelled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CancelTaskResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/tasks/{taskId}/result": {
"get": {
"tags": [
"Tasks"
],
"summary": "Tasks - get result (default format)",
"description": "Returns a download URL for the task's primary result. For compound tasks, returns a manifest with per-sub-task download links.",
"parameters": [
{
"name": "taskId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Task ID"
}
],
"responses": {
"200": {
"description": "Result download link (standard) or compound manifest",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskOrCompoundResultResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Task is not yet completed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/tasks/{taskId}/result/{format}": {
"get": {
"tags": [
"Tasks"
],
"summary": "Tasks - get result in a specific format",
"description": "Returns a download URL for the requested output format (e.g. glb, step, stpz).",
"parameters": [
{
"name": "taskId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Task ID"
},
{
"name": "format",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Result format (e.g. glb, step, stpz, metadata, decomposed-mesh)"
}
],
"responses": {
"200": {
"description": "Result download link",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskResultResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Task is not yet completed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/tasks/{taskId}/results": {
"get": {
"tags": [
"Tasks"
],
"summary": "Tasks - get all results",
"description": "Returns download URLs for every available result format in a single call. Use this instead of making multiple requests to /result/{format}.",
"parameters": [
{
"name": "taskId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Task ID"
}
],
"responses": {
"200": {
"description": "Download links for all available formats",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskResultsResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Task is not yet completed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/api/v1/tasks/{taskId}/retry": {
"post": {
"tags": [
"Tasks"
],
"summary": "Tasks - retry a failed or cancelled task",
"description": "Re-queues a failed or cancelled task with the same parameters.",
"parameters": [
{
"name": "taskId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Task ID"
}
],
"responses": {
"202": {
"description": "Task re-queued",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskAcceptedResponse"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"409": {
"description": "Task is not in a retryable state",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ExecuteBody": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"minLength": 1,
"description": "Fully-qualified CAD operation identifier (e.g. 'occt.shapes.solid.createBox', 'manifold.primitives.cube', 'jscad.booleans.union'). Supports OCCT, Manifold, JSCAD, and vector/math operations."
},
"params": {
"description": "Operation-specific parameters - varies by operation. See model definitions for available parameters."
}
},
"required": [
"operation"
],
"additionalProperties": false,
"description": "Execute a single Bitbybit CAD operation. The operation runs asynchronously and returns a task ID for polling."
},
"PipelineBody": {
"type": "object",
"properties": {
"steps": {
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"$ref": "#/components/schemas/PipelineAnyStep"
},
"description": "Ordered list of CAD operations executed sequentially. Later steps can reference earlier results using '$ref:N' syntax. Supports map and choice control-flow steps."
},
"inputFiles": {
"description": "References to previously uploaded files. Use '$file:N' in step params to inject file contents (optionally '$file:N: