bitbybit-dev Sheet Metal API

openapi: 3.2.0
info:
  title: Bitbybit CAD Cloud Sheet Metal 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: Sheet Metal
paths:
  /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'
      operationId: postApiV1CadProUnfoldFaceToFlat
      x-operation-id-source: derived
  /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'
      operationId: postApiV1CadProUnfoldFaceReport
      x-operation-id-source: derived
  /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'
      operationId: postApiV1CadProUnfoldSolidToFlat
      x-operation-id-source: derived
  /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'
      operationId: postApiV1CadProUnfoldSolidReport
      x-operation-id-source: derived
  /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'
      operationId: postApiV1CadProUnfoldSolid
      x-operation-id-source: derived
components:
  schemas:
    OutputFormat:
      type: string
      enum:
      - step
      - stpz
      - decomposed-mesh
      - gltf
      description: 'Output file format: ''step'' (raw STEP), ''stpz'' (gzip-compressed STEP), ''decomposed-mesh'' (triangulated JSON), ''gltf'' (glTF 2.0 binary .glb). Note: ''step'' and ''stpz'' are mutually exclusive - choose one or the other, not both.'
    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.
    UnfoldFaceToFlatBody:
      type: object
      properties:
        stepFileId:
          type: string
          minLength: 1
          description: ID of the previously uploaded STEP file (returned by the file upload endpoint). Both plain STEP (.step/.stp) and gzip-compressed STEP (.stpz) uploads are accepted - compression is detected automatically.
        faceIndex:
          default: 0
          description: 0-based index of the developable face (in the shape's BRepGraph face array) to unfold.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        outputs:
          description: Output formats for the flattened face geometry. Defaults to glTF.
          $ref: '#/components/schemas/OutputOptions'
      required:
      - stepFileId
      additionalProperties: false
      description: Unfold a single developable face of an uploaded STEP shape to a flat face.
    OutputOptions:
      type: object
      properties:
        formats:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/OutputFormat'
          description: Output formats to generate. Multiple formats can be requested (e.g. ['gltf', 'stpz']) - each produces a separate downloadable result. Do not include both 'step' and 'stpz' - only one STEP variant is supported per request.
        meshPrecision:
          description: Tessellation precision for mesh-based outputs (decomposed-mesh and gltf). Lower values produce denser meshes. Only ignored when output is limited to step/stpz formats.
          $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
      required:
      - formats
      additionalProperties: false
      description: Controls which output formats are generated and their quality settings
    UnfoldSolidBody:
      type: object
      properties:
        stepFileId:
          type: string
          minLength: 1
          description: ID of the previously uploaded STEP file (returned by the file upload endpoint). Both plain STEP (.step/.stp) and gzip-compressed STEP (.stpz) uploads are accepted - compression is detected automatically.
        kFactor:
          default: 0.5
          description: Sheet-metal K-factor (neutral-axis position), typically ~0.5.
          type: number
          minimum: 0
          maximum: 1
        thicknessOverride:
          default: 0
          description: Sheet thickness override in model units; 0 auto-detects thickness from face pairs.
          type: number
          minimum: 0
        outputs:
          description: Output formats for the flattened patterns. For 'gltf'/'step'/'stpz', every solid's flat is combined into one compound output. The 'decomposed-mesh' format instead returns one mesh per solid (each tagged with its 'solidIndex'). Defaults to glTF.
          $ref: '#/components/schemas/OutputOptions'
      required:
      - stepFileId
      additionalProperties: false
      description: Flatten every constant-thickness sheet-metal solid in an uploaded STEP file AND return the per-solid metrics report - both in one call.
    UnfoldSolidToFlatBody:
      type: object
      properties:
        stepFileId:
          type: string
          minLength: 1
          description: ID of the previously uploaded STEP file (returned by the file upload endpoint). Both plain STEP (.step/.stp) and gzip-compressed STEP (.stpz) uploads are accepted - compression is detected automatically.
        kFactor:
          default: 0.5
          description: Sheet-metal K-factor (neutral-axis position), typically ~0.5.
          type: number
          minimum: 0
          maximum: 1
        thicknessOverride:
          default: 0
          description: Sheet thickness override in model units; 0 auto-detects thickness from face pairs.
          type: number
          minimum: 0
        outputs:
          description: Output formats for the flattened patterns. Every solid's flat is combined into one compound output per format. Defaults to glTF.
          $ref: '#/components/schemas/OutputOptions'
      required:
      - stepFileId
      additionalProperties: false
      description: Flatten every constant-thickness sheet-metal solid in an uploaded STEP file to flat patterns.
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
      - ok
      - error
      additionalProperties: false
      description: Standard error envelope
    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
    UnfoldSolidReportBody:
      type: object
      properties:
        stepFileId:
          type: string
          minLength: 1
          description: ID of the previously uploaded STEP file (returned by the file upload endpoint). Both plain STEP (.step/.stp) and gzip-compressed STEP (.stpz) uploads are accepted - compression is detected automatically.
        kFactor:
          default: 0.5
          description: Sheet-metal K-factor (neutral-axis position), typically ~0.5.
          type: number
          minimum: 0
          maximum: 1
        thicknessOverride:
          default: 0
          description: Sheet thickness override in model units; 0 auto-detects thickness from face pairs.
          type: number
          minimum: 0
      required:
      - stepFileId
      additionalProperties: false
      description: Compute per-solid sheet-metal unfold metrics for every solid in an uploaded STEP file.
    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
    MeshPrecision:
      type: number
      minimum: 0.0001
      maximum: 10
      description: 'Mesh tessellation precision (lower = finer). Range: [0.0001, 10]'
      example: 0.1
    UnfoldFaceReportBody:
      type: object
      properties:
        stepFileId:
          type: string
          minLength: 1
          description: ID of the previously uploaded STEP file (returned by the file upload endpoint). Both plain STEP (.step/.stp) and gzip-compressed STEP (.stpz) uploads are accepted - compression is detected automatically.
        faceIndex:
          default: 0
          description: 0-based index of the face to analyze.
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
      - stepFileId
      additionalProperties: false
      description: Compute the sheet-metal unfold metrics report for a single face of an uploaded STEP shape.
  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.'