bitbybit-dev Convert API

openapi: 3.2.0
info:
  title: Bitbybit CAD Cloud Convert 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: Convert
paths:
  /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'
      operationId: postApiV1ConvertStepToGltf
      x-operation-id-source: derived
  /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'
      operationId: postApiV1ConvertStepToGltfAdvanced
      x-operation-id-source: derived
  /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'
      operationId: postApiV1ConvertStepToGltfWithDraco
      x-operation-id-source: derived
  /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'
      operationId: postApiV1ConvertStepToGltfAdvancedWithDraco
      x-operation-id-source: derived
components:
  schemas:
    GltfTransformFormat:
      type: string
      enum:
      - compact
      - mat4
      - trs
      description: Transform representation in glTF output
    StepToGltfBody:
      type: object
      properties:
        stepFileId:
          type: string
          minLength: 1
          description: ID of the previously uploaded STEP file (returned by the file upload endpoint)
        meshPrecision:
          description: Mesh linear deflection. When meshRelative is true (default), this is a fraction of each edge's length (e.g. 0.005 = 0.5%). When false, it is an absolute value in model units (mm for STEP).
          $ref: '#/components/schemas/MeshPrecision'
        meshAngle:
          description: Angular deflection in radians for mesh tessellation - controls curvature approximation. Smaller values produce smoother curved surfaces.
          $ref: '#/components/schemas/MeshAngle'
        meshRelative:
          description: Use size-aware relative deflection per face. When true, meshPrecision is a fraction of each edge's length. Set to false for absolute deflection in model units.
          type: boolean
        internalVerticesMode:
          description: Add interior vertices for better curved face fidelity (slower, set false for speed).
          type: boolean
        controlSurfaceDeflection:
          description: Extra post-pass refining triangles that bulge beyond the deflection (slower, set false for speed).
          type: boolean
      required:
      - stepFileId
      additionalProperties: false
      description: Convert a STEP file to glTF format with default settings. Upload the STEP file first, then pass its ID here.
    DracoCompressionOptions:
      type: object
      properties:
        useDraco:
          description: Apply Draco geometry compression to the glTF output. Defaults to true for the *-with-draco endpoints.
          type: boolean
        dracoCompressionLevel:
          description: Draco compression level (0 = fastest/largest, 10 = slowest/smallest). Typical good default is 7.
          type: integer
          minimum: 0
          maximum: 10
        dracoQuantizePositionBits:
          description: 'Quantization bits for vertex positions (higher = more precise, larger file). Typical: 14.'
          type: integer
          minimum: 0
          maximum: 31
        dracoQuantizeNormalBits:
          description: 'Quantization bits for normal vectors. Typical: 10.'
          type: integer
          minimum: 0
          maximum: 31
        dracoQuantizeTexcoordBits:
          description: 'Quantization bits for texture coordinates. Typical: 12.'
          type: integer
          minimum: 0
          maximum: 31
        dracoQuantizeColorBits:
          description: 'Quantization bits for vertex colors. Typical: 8.'
          type: integer
          minimum: 0
          maximum: 31
        dracoQuantizeGenericBits:
          description: 'Quantization bits for generic vertex attributes. Typical: 12.'
          type: integer
          minimum: 0
          maximum: 31
        dracoUnifiedQuantization:
          description: Use unified quantization across all meshes (better when meshes share a coordinate frame).
          type: boolean
      additionalProperties: false
      description: Draco geometry compression options applied during glTF export.
    StepToGltfWithDracoBody:
      type: object
      properties:
        stepFileId:
          type: string
          minLength: 1
          description: ID of the previously uploaded STEP file (returned by the file upload endpoint)
        meshPrecision:
          description: Mesh linear deflection. When meshRelative is true (default), this is a fraction of each edge's length (e.g. 0.005 = 0.5%). When false, it is an absolute value in model units (mm for STEP).
          $ref: '#/components/schemas/MeshPrecision'
        meshAngle:
          description: Angular deflection in radians for mesh tessellation - controls curvature approximation. Smaller values produce smoother curved surfaces.
          $ref: '#/components/schemas/MeshAngle'
        meshRelative:
          description: Use size-aware relative deflection per face. When true, meshPrecision is a fraction of each edge's length. Set to false for absolute deflection in model units.
          type: boolean
        internalVerticesMode:
          description: Add interior vertices for better curved face fidelity (slower, set false for speed).
          type: boolean
        controlSurfaceDeflection:
          description: Extra post-pass refining triangles that bulge beyond the deflection (slower, set false for speed).
          type: boolean
        draco:
          description: Draco compression options. If omitted, sensible defaults are used (level 7, 14/10/12/8/12 bits).
          $ref: '#/components/schemas/DracoCompressionOptions'
      required:
      - stepFileId
      additionalProperties: false
      description: Convert a STEP file to Draco-compressed glTF with default settings. Upload the STEP file first, then pass its ID here.
    StepToGltfAdvancedWithDracoBody:
      type: object
      properties:
        stepFileId:
          type: string
          minLength: 1
          description: ID of the previously uploaded STEP file (returned by the file upload endpoint)
        options:
          description: Advanced conversion settings. If omitted, sensible defaults are used.
          $ref: '#/components/schemas/ConvertAdvancedOptions'
        draco:
          description: Draco compression options. If omitted, sensible defaults are used (level 7, 14/10/12/8/12 bits).
          $ref: '#/components/schemas/DracoCompressionOptions'
      required:
      - stepFileId
      additionalProperties: false
      description: Convert a STEP file to Draco-compressed glTF with full control over tessellation, naming, coordinate systems, output format, and Draco quantization.
    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.
    MeshAngle:
      type: number
      minimum: 0.01
      maximum: 3.141592653589793
      description: 'Mesh angular deflection in radians. Range: [0.01, π]'
    StepToGltfAdvancedBody:
      type: object
      properties:
        stepFileId:
          type: string
          minLength: 1
          description: ID of the previously uploaded STEP file (returned by the file upload endpoint)
        options:
          description: Advanced conversion settings. If omitted, sensible defaults are used.
          $ref: '#/components/schemas/ConvertAdvancedOptions'
      required:
      - stepFileId
      additionalProperties: false
      description: Convert a STEP file to glTF with full control over tessellation, naming, coordinate systems, and output format.
    PositiveScale:
      type: number
      minimum: 1.0e-06
      maximum: 1000
      description: 'Uniform scale factor. Range: [1e-6, 1000]'
    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
    GltfNameFormat:
      type: string
      enum:
      - empty
      - product
      - instance
      - instanceOrProduct
      - productOrInstance
      - productAndInstance
      - productAndInstanceAndOcaf
      description: How node/mesh names are derived from STEP product/instance labels
    ConvertAdvancedOptions:
      type: object
      properties:
        readColors:
          description: Extract color attributes from the STEP file and apply to glTF materials
          type: boolean
        readNames:
          description: Extract product/instance names from the STEP file and apply to glTF node names
          type: boolean
        readMaterials:
          description: Extract material definitions from the STEP file
          type: boolean
        readLayers:
          description: Extract layer/group structure from the STEP file
          type: boolean
        readProps:
          description: Extract custom properties (e.g. part numbers, metadata) from the STEP file
          type: boolean
        meshDeflection:
          description: Mesh linear deflection. When meshRelative is true (default), this is a fraction of each edge's length (e.g. 0.005 = 0.5%) so deflection auto-scales with feature size. When false, it is absolute in model units (mm for STEP).
          $ref: '#/components/schemas/MeshPrecision'
        meshAngle:
          description: Angular deflection for mesh tessellation (radians) - controls curvature approximation
          $ref: '#/components/schemas/MeshAngle'
        meshParallel:
          description: Enable parallel tessellation for faster processing
          type: boolean
        meshRelative:
          description: Use size-aware relative deflection per face. When true, meshDeflection is a fraction of each edge's length. Set to false for absolute deflection in model units.
          type: boolean
        internalVerticesMode:
          description: Add interior vertices for better curved face fidelity (slower, set false for speed).
          type: boolean
        controlSurfaceDeflection:
          description: Extra post-pass refining triangles that bulge beyond the deflection (slower, set false for speed).
          type: boolean
        faceCountThreshold:
          description: Face count threshold for per-sub-shape meshing fallback. Default -1 means single-pass meshing of the whole compound (fastest). Set to a positive value (e.g. 100000) to fall back to per-solid meshing for very large assemblies in memory-constrained environments.
          type: integer
          minimum: -1
          maximum: 500000
        mergeFaces:
          description: Merge co-planar adjacent faces to reduce mesh complexity
          type: boolean
        splitIndices16:
          description: Split meshes so each uses 16-bit index buffers (max 65535 vertices per mesh). Improves compatibility with some renderers.
          type: boolean
        parallelWrite:
          description: Write glTF output in parallel for faster file generation
          type: boolean
        embedTextures:
          description: Embed texture data directly in the .glb file instead of referencing external URIs
          type: boolean
        forceUVExport:
          description: Generate UV coordinates even when no textures are present (useful for post-processing)
          type: boolean
        nodeNameFormat:
          description: Strategy for naming glTF nodes from STEP product/instance labels
          $ref: '#/components/schemas/GltfNameFormat'
        meshNameFormat:
          description: Strategy for naming glTF meshes from STEP product/instance labels
          $ref: '#/components/schemas/GltfNameFormat'
        transformFormat:
          description: 'Transform representation in glTF: ''compact'' (default), ''mat4'' (4x4 matrix), or ''trs'' (translation/rotation/scale)'
          $ref: '#/components/schemas/GltfTransformFormat'
        adjustZtoY:
          description: Convert from Z-up (CAD convention) to Y-up (glTF/WebGL convention) coordinate system
          type: boolean
        scale:
          description: Uniform scale factor applied to the entire model (e.g. 0.001 to convert mm to meters)
          $ref: '#/components/schemas/PositiveScale'
      additionalProperties: false
      description: 'Fine-grained options controlling STEP → glTF conversion: tessellation quality, attribute extraction, coordinate systems, and output format.'
    MeshPrecision:
      type: number
      minimum: 0.0001
      maximum: 10
      description: 'Mesh tessellation precision (lower = finer). Range: [0.0001, 10]'
      example: 0.1
    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
  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.'