bitbybit-dev CAD Operations API

openapi: 3.2.0
info:
  title: Bitbybit CAD Cloud CAD Operations API
  version: 1.6.0
  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: []
tags:
- name: CAD Operations
paths:
  /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'
      operationId: postApiV1CadExecute
      x-operation-id-source: derived
  /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'
      operationId: postApiV1CadPipeline
      x-operation-id-source: derived
  /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'
      operationId: postApiV1CadCompound
      x-operation-id-source: derived
components:
  schemas:
    CompoundExecuteBody:
      type: object
      properties:
        parallel:
          type: boolean
          const: true
          description: Must be true - signals that items should be processed concurrently
        items:
          minItems: 1
          maxItems: 100
          type: array
          items:
            $ref: '#/components/schemas/CompoundItem'
          description: List of independent CAD operations to execute in parallel. Each item becomes a sub-task.
      required:
      - parallel
      - items
      additionalProperties: false
      description: Execute multiple independent Bitbybit CAD operations in parallel. Each item runs as a separate sub-task and can be polled individually.
    TaskCreatedResult:
      type: object
      properties:
        taskId:
          type: string
          description: Unique task identifier - use this to poll for status and retrieve results
          format: uuid
        status:
          type: string
          const: queued
          description: Initial task status (always 'queued' upon creation)
        statusUrl:
          type: string
          description: Relative URL to poll for task status updates
          example: /api/v1/tasks/{taskId}
      required:
      - taskId
      - status
      - statusUrl
      additionalProperties: false
      description: Returned when a CAD task is accepted. Poll the statusUrl to track progress.
    TaskStatus:
      type: string
      enum:
      - waiting
      - queued
      - processing
      - completed
      - failed
      - cancelled
      - expired
      description: 'Task lifecycle state: waiting (pending dependencies), queued (in queue), processing (actively computing), completed (result available), failed (error occurred), cancelled (user-cancelled), expired (result TTL exceeded)'
    PipelineOutputFormat:
      type: string
      enum:
      - step
      - stpz
      - decomposed-mesh
      - gltf
      - json
      - csv
      - stl
      - 3mf
      - brep
      - brep-binary
      description: 'Pipeline output file format. Includes all standard formats plus: ''json'' (JSON data), ''csv'' (CSV text), ''stl'' (binary STL mesh - Manifold/JSCAD only), ''3mf'' (3MF mesh package - Manifold/JSCAD only), ''brep'' (OpenCascade BREP as text, which OCCT-based tools such as FreeCAD read) and ''brep-binary'' (OpenCascade binary BREP, the smallest and fastest exact form, which keeps the numbering of faces and edges; read back with occt.io.loadBrepBinary) - both OCCT only, without triangulation.'
    LengthUnit:
      type: string
      enum:
      - mm
      - cm
      - m
      - in
      description: 'A unit of length: ''mm'' (millimetres), ''cm'' (centimetres), ''m'' (metres) or ''in'' (inches).'
    InputFileItem:
      type: object
      properties:
        fileId:
          type: string
          minLength: 1
          description: ID of a previously uploaded file (from POST /files/upload)
        role:
          type: string
          minLength: 1
          description: Role identifier for the file (e.g. 'step-model', 'coordinates-csv')
      required:
      - fileId
      - role
      additionalProperties: false
      description: Reference to an uploaded file to be used as input
    MapStep:
      type: object
      properties:
        type:
          type: string
          const: map
          description: Declares this step as a map (iteration) step
        items:
          description: Source array to iterate over. Typically a '$ref:N' reference to a previous step that produced an array.
        steps:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/PipelineStep'
          description: Sub-steps to execute for each item. Use '$item' for the current element, '$index' for the iteration number.
        reduce:
          description: Optional sub-steps to combine map results. Use '$mapResult' to reference the collected array of iteration outputs.
          type: array
          items:
            $ref: '#/components/schemas/PipelineStep'
      required:
      - type
      - items
      - steps
      description: Iterate over an array, executing sub-steps for each element. Produces an array of results (or a reduced value).
    PipelineOutputOptions:
      type: object
      properties:
        formats:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/PipelineOutputFormat'
          description: Output formats to generate. Supports standard CAD formats (step, stpz, gltf, decomposed-mesh) plus pipeline-specific formats (json, csv, stl, 3mf, brep, brep-binary).
        meshPrecision:
          description: Tessellation precision for mesh-based outputs (decomposed-mesh and gltf). Lower values produce denser meshes.
          $ref: '#/components/schemas/MeshPrecision'
        gltfMeshPrecision:
          description: Override tessellation precision specifically for glTF output. When set, takes precedence over meshPrecision for glTF only.
          $ref: '#/components/schemas/MeshPrecision'
        adjustYtoZ:
          description: Convert from Y-up to Z-up coordinate system in the output. Useful for software that expects Z-up.
          type: boolean
        includePipelineInMetadata:
          description: Include the full pipeline definition in metadata.json. Defaults to true. Set to false to exclude it for smaller metadata.
          type: boolean
        unit:
          description: 'The unit the pipeline''s shapes are modelled in. Given, a STEP output is written at its true size in millimetres, so CAD tools open the shapes at the right size, and a glTF output is written in metres, the unit glTF viewers assume. Left out, the numbers are written as they are: STEP takes them as millimetres and glTF holds them unscaled. The other formats carry no unit and always hold the numbers as they are. A design build''s documents state their own unit, and a unit given here must be the same.'
          $ref: '#/components/schemas/LengthUnit'
      required:
      - formats
      additionalProperties: false
      description: Controls which output formats are generated for pipeline results. Supports additional formats (json, csv, stl, 3mf, brep, brep-binary) beyond standard model outputs.
    PipelineAnyStep:
      anyOf:
      - $ref: '#/components/schemas/MapStep'
      - $ref: '#/components/schemas/ChoiceStep'
      - $ref: '#/components/schemas/PipelineStep'
      description: A pipeline step - either a plain operation, a map (iteration), or a choice (conditional).
    MeshPrecision:
      type: number
      minimum: 0.0001
      maximum: 10
      description: 'Mesh tessellation precision (lower = finer). Range: [0.0001, 10]'
      example: 0.1
    ComparisonOperator:
      type: string
      enum:
      - eq
      - neq
      - gt
      - gte
      - lt
      - lte
      - exists
      description: 'Comparison operator: ''eq'' (equal), ''neq'' (not equal), ''gt'' (greater than), ''gte'' (greater or equal), ''lt'' (less than), ''lte'' (less or equal), ''exists'' (value is not null/undefined).'
    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:<format>:<codec>' to pick a read format and/or decompress - see PipelineStep.params).
          maxItems: 5
          type: array
          items:
            $ref: '#/components/schemas/InputFileItem'
        outputs:
          description: Output format options applied to the final pipeline result. Supports json, csv, stl, 3mf in addition to standard formats. If omitted, raw result data is stored.
          $ref: '#/components/schemas/PipelineOutputOptions'
      required:
      - steps
      additionalProperties: false
      description: Execute a chain of Bitbybit CAD operations sequentially. Supports $ref:N step references, $file:N file inputs, map iteration, and choice conditionals.
    ChoiceStep:
      type: object
      properties:
        type:
          type: string
          const: choice
          description: Declares this step as a choice (conditional) step
        value:
          description: Value to compare. Typically a '$ref:N' reference to a previous step result.
        operator:
          description: Comparison operator to apply between value and compareTo
          $ref: '#/components/schemas/ComparisonOperator'
        compareTo:
          description: Value to compare against. Not required for 'exists' operator.
        then:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/PipelineStep'
          description: Sub-steps to execute when condition is true
        else:
          description: Sub-steps to execute when condition is false. If omitted, produces null.
          type: array
          items:
            $ref: '#/components/schemas/PipelineStep'
      required:
      - type
      - value
      - operator
      - then
      description: Conditional execution - evaluate a condition and run the matching branch.
    CompoundTaskAcceptedResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/CompoundTaskCreatedResult'
      required:
      - ok
      - data
      additionalProperties: false
      description: HTTP 202 response when a compound (parallel) task is accepted
    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.
    CompoundItem:
      type: object
      properties:
        operation:
          type: string
          minLength: 1
          description: Fully-qualified CAD operation identifier. Supports OCCT, Manifold, JSCAD, and vector/math operations.
        params:
          description: Operation-specific parameters for this sub-task
        inputFiles:
          description: References to previously uploaded files to be used as inputs for this operation
          type: array
          items:
            $ref: '#/components/schemas/InputFileItem'
        outputFormats:
          description: Per-item output format overrides. If omitted, the task produces raw result data.
          maxItems: 10
          type: array
          items:
            type: string
            minLength: 1
      required:
      - operation
      additionalProperties: false
      description: A single operation within a compound (parallel) task. Each item runs independently.
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
      - ok
      - error
      additionalProperties: false
      description: Standard error envelope
    CompoundTaskCreatedResult:
      type: object
      properties:
        taskId:
          type: string
          description: Parent compound task ID for tracking overall progress
        kind:
          type: string
          const: compound
        subTaskCount:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
          description: Total number of sub-tasks created (one per item in the request)
        statusUrl:
          type: string
          description: Relative URL to poll the parent task status
          example: /api/v1/tasks/{taskId}
        subTasks:
          type: array
          items:
            $ref: '#/components/schemas/SubTaskSummary'
      required:
      - taskId
      - kind
      - subTaskCount
      - statusUrl
      - subTasks
      additionalProperties: false
      description: Returned when a compound (parallel) task is accepted. Contains initial status for all sub-tasks.
    ErrorDetail:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: VALIDATION_ERROR
        message:
          type: string
          description: Human-readable error message
        details:
          description: Optional structured error context
        requestId:
          description: Request ID for tracing
          type: string
      required:
      - code
      - message
      additionalProperties: false
      description: Structured error information with machine-readable code and optional debugging context
    PipelineStep:
      type: object
      properties:
        operation:
          type: string
          minLength: 1
          description: Fully-qualified CAD operation identifier (e.g. 'occt.shapes.solid.createSphere'). Supports OCCT, Manifold, JSCAD, and vector/math operations.
        params:
          description: Operation parameters. Use '$ref:N' (e.g. '$ref:0') to reference the output of a previous step by its zero-based index. Use '$file:N[:<format>][:<codec>]' to reference an input file's contents - <format> is one of text|buffer|uint8|json|base64 (default text), and the optional <codec> is one of raw|gunzip|auto (default raw) to decompress the file first; 'auto' gunzips only when gzip magic bytes are present, so '$file:0:text:auto' reads both plain and gzip-compressed uploads (e.g. .step and .stpz).
        output:
          description: When true, this step's result is included in a separate result.json output alongside any shape files.
          type: boolean
      required:
      - operation
      - params
      description: A single step in a sequential CAD pipeline. Steps can reference outputs of earlier steps via $ref or input files via $file.
    TaskAcceptedResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/TaskCreatedResult'
      required:
      - ok
      - data
      additionalProperties: false
      description: HTTP 202 response when a task is accepted for async processing
    SubTaskSummary:
      type: object
      properties:
        taskId:
          type: string
          description: Unique identifier for this sub-task (can be polled individually)
        index:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Zero-based position of this sub-task within the compound
        status:
          $ref: '#/components/schemas/TaskStatus'
        progress:
          anyOf:
          - type: number
          - type: 'null'
          description: Completion percentage (0–100) or null if not yet started
        computeMs:
          anyOf:
          - type: number
          - type: 'null'
          description: Actual compute time in milliseconds (null until completed)
        error:
          anyOf:
          - type: string
          - type: 'null'
          description: Error message if sub-task failed, null otherwise
        downloadFormats:
          type: array
          items:
            type: string
          description: Available output format keys (e.g. ['glb', 'stpz']) for downloading results
      required:
      - taskId
      - index
      - status
      - progress
      - computeMs
      - error
      - downloadFormats
      additionalProperties: false
      description: Status summary for one sub-task within a compound (parallel) task
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Scoped API key. Scopes: models, cad, convert, * (wildcard). A key without the required scope receives 403 INSUFFICIENT_SCOPE.'