---
title: "CAD - execute a chained pipeline"
method: POST
path: "/api/v1/cad/pipeline"
tags: ["CAD Operations"]
---

# CAD - execute a chained pipeline

`POST /api/v1/cad/pipeline`

Runs multiple operations sequentially. Use '$ref:N' in params to reference step N's result.

## Request body

- PipelineBody — Execute a chain of Bitbybit CAD operations sequentially. Supports $ref:N step references, $file:N file inputs, map iteration, and choice conditionals.
  - `steps` PipelineAnyStep[], required — Ordered list of CAD operations executed sequentially. Later steps can reference earlier results using '$ref:N' syntax. Supports map and choice control-flow steps.
    - union — A pipeline step - either a plain operation, a map (iteration), or a choice (conditional).
      - MapStep — Iterate over an array, executing sub-steps for each element. Produces an array of results (or a reduced value).
        - `type` 'map', required — Declares this step as a map (iteration) step
        - `items` unknown, required
        - `steps` PipelineStep[], required — Sub-steps to execute for each item. Use '$item' for the current element, '$index' for the iteration number.
          - `operation` string, required — Fully-qualified CAD operation identifier (e.g. 'occt.shapes.solid.createSphere'). Supports OCCT, Manifold, JSCAD, and vector/math operations.
          - `params` unknown, required
          - `output` boolean — When true, this step's result is included in a separate result.json output alongside any shape files.
        - `reduce` PipelineStep[] — Optional sub-steps to combine map results. Use '$mapResult' to reference the collected array of iteration outputs.
          - `operation` string, required — Fully-qualified CAD operation identifier (e.g. 'occt.shapes.solid.createSphere'). Supports OCCT, Manifold, JSCAD, and vector/math operations.
          - `params` unknown, required
          - `output` boolean — When true, this step's result is included in a separate result.json output alongside any shape files.
      - ChoiceStep — Conditional execution - evaluate a condition and run the matching branch.
        - `type` 'choice', required — Declares this step as a choice (conditional) step
        - `value` unknown, required
        - `operator` 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'exists', required — 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).
        - `compareTo` unknown
        - `then` PipelineStep[], required — Sub-steps to execute when condition is true
          - `operation` string, required — Fully-qualified CAD operation identifier (e.g. 'occt.shapes.solid.createSphere'). Supports OCCT, Manifold, JSCAD, and vector/math operations.
          - `params` unknown, required
          - `output` boolean — When true, this step's result is included in a separate result.json output alongside any shape files.
        - `else` PipelineStep[] — Sub-steps to execute when condition is false. If omitted, produces null.
          - `operation` string, required — Fully-qualified CAD operation identifier (e.g. 'occt.shapes.solid.createSphere'). Supports OCCT, Manifold, JSCAD, and vector/math operations.
          - `params` unknown, required
          - `output` boolean — When true, this step's result is included in a separate result.json output alongside any shape files.
      - PipelineStep — A single step in a sequential CAD pipeline. Steps can reference outputs of earlier steps via $ref or input files via $file.
        - `operation` string, required — Fully-qualified CAD operation identifier (e.g. 'occt.shapes.solid.createSphere'). Supports OCCT, Manifold, JSCAD, and vector/math operations.
        - `params` unknown, required
        - `output` boolean — When true, this step's result is included in a separate result.json output alongside any shape files.
  - `inputFiles` InputFileItem[] — 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).
    - `fileId` string, required — ID of a previously uploaded file (from POST /files/upload)
    - `role` string, required — Role identifier for the file (e.g. 'step-model', 'coordinates-csv')
  - `outputs` PipelineOutputOptions — Controls which output formats are generated for pipeline results. Supports additional formats (json, csv, stl, 3mf) beyond standard model outputs.
    - `formats` PipelineOutputFormat[], required — Output formats to generate. Supports standard CAD formats (step, stpz, gltf, decomposed-mesh) plus pipeline-specific formats (json, csv, stl, 3mf).
    - `meshPrecision` number — Mesh tessellation precision (lower = finer). Range: [0.0001, 10]
    - `gltfMeshPrecision` number — Mesh tessellation precision (lower = finer). Range: [0.0001, 10]
    - `adjustYtoZ` boolean — Convert from Y-up to Z-up coordinate system in the output. Useful for software that expects Z-up.
    - `includePipelineInMetadata` boolean — Include the full pipeline definition in metadata.json. Defaults to true. Set to false to exclude it for smaller metadata.

## Response `202`

Task accepted

- TaskAcceptedResponse — HTTP 202 response when a task is accepted for async processing
  - `ok` true, required
  - `data` TaskCreatedResult, required — Returned when a CAD task is accepted. Poll the statusUrl to track progress.
    - `taskId` string, uuid, required — Unique task identifier - use this to poll for status and retrieve results
    - `status` 'queued', required — Initial task status (always 'queued' upon creation)
    - `statusUrl` string, required — Relative URL to poll for task status updates

## Other responses

- `400` — Validation error
- `500` — Server error

## Changes

- **2026-05-04** `43c3bc84d7c1` — 2 breaking, 2 warning, 10 info
  - the `steps/items/` request property type/format changed from `object`/`` to ``/``
  - removed the success response with the status `200`
  - removed the request property `steps/items/operation`
  - removed the request property `steps/items/params`
  - …10 more
- **2026-04-30** `bef883f8a334` — 4 breaking, 8 info
  - the request property `steps/items/params` became required
  - the `steps/items/operation` request property's minLength was increased from `0` to `1`
  - the `steps/items/params` request property type/format changed from `object`/`` to ``/``
  - removed the success response with the status `202`
  - …8 more
- **2026-04-17** `5eb4ed0f33c7` — 14 breaking, 5 warning, 6 info
  - added the new required request property `steps/items/operation`
  - removed `#/components/schemas/MapStep, #/components/schemas/ChoiceStep, #/components/schemas/PipelineStep` from the `steps/items/` request property `anyOf` list
  - removed the enum value `3mf` of the request property `outputs/formats/items/`
  - removed the enum value `csv` of the request property `outputs/formats/items/`
  - …21 more

[Change history](https://skmtc.dev/bitbybit-dev/apis/bitbybit-cad-cloud-api/changes/api/v1/cad/pipeline/post.md)

---

[API](https://skmtc.dev/bitbybit-dev/apis/bitbybit-cad-cloud-api.md) · [All operations](https://skmtc.dev/bitbybit-dev/apis/bitbybit-cad-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bitbybit-dev/bitbybit-cad-cloud-api/revisions/1135d4473bc2/schema)