bitbybit-dev Models - Dragon Cup API

openapi: 3.2.0
info:
  title: Bitbybit CAD Cloud Models - Dragon Cup 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: Models - Dragon Cup
paths:
  /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'
      operationId: postApiV1ModelsDragonCup
      x-operation-id-source: derived
components:
  schemas:
    Point3:
      type: array
      prefixItems:
      - type: number
        minimum: -1000
        maximum: 1000
      - type: number
        minimum: -1000
        maximum: 1000
      - type: number
        minimum: -1000
        maximum: 1000
      description: 3D point as [x, y, z] tuple, each coordinate in [-1000, 1000]
    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.
    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
    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
    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
    DragonCupParams:
      type: object
      properties:
        height:
          description: Total cup height (cm)
          type: number
          exclusiveMinimum: 0
          maximum: 50
        radiusBottom:
          description: Radius at the base (cm)
          type: number
          exclusiveMinimum: 0
          maximum: 30
        radiusTopOffset:
          description: How much the top radius differs from bottom
          type: number
          minimum: 0
          maximum: 20
        radiusMidOffset:
          description: Mid-section radius offset
          type: number
          minimum: 0
          maximum: 20
        rotationTopAngle:
          description: Top twist angle (degrees)
          type: number
          minimum: -360
          maximum: 360
        rotationMidAngle:
          description: Mid twist angle (degrees)
          type: number
          minimum: -360
          maximum: 360
        nrSkinCellsVertical:
          description: Vertical skin cell count
          type: integer
          exclusiveMinimum: 0
          maximum: 30
        nrSkinCellsHorizontal:
          description: Horizontal skin cell count
          type: integer
          exclusiveMinimum: 0
          maximum: 50
        nrSkinCellDivisionsTop:
          description: Subdivisions at top of each cell
          type: integer
          exclusiveMinimum: 0
          maximum: 10
        nrSkinCellDivisionsBottom:
          description: Subdivisions at bottom of each cell
          type: integer
          exclusiveMinimum: 0
          maximum: 10
        skinCellOuterHeight:
          description: Outer cell extrusion height
          type: number
          exclusiveMinimum: 0
          maximum: 5
        skinCellInnerHeight:
          description: Inner cell extrusion height
          type: number
          exclusiveMinimum: 0
          maximum: 5
        skinCellBottomHeight:
          description: Bottom cell height
          type: number
          exclusiveMinimum: 0
          maximum: 5
        skinCellTopHeight:
          description: Top cell height
          type: number
          exclusiveMinimum: 0
          maximum: 5
        thickness:
          description: Shell wall thickness
          type: number
          exclusiveMinimum: 0
          maximum: 5
        bottomThickness:
          description: Bottom plate thickness
          type: number
          exclusiveMinimum: 0
          maximum: 5
        precision:
          description: Geometry precision (lower = finer)
          $ref: '#/components/schemas/MeshPrecision'
        rotation:
          description: Final rotation angle (degrees)
          type: number
          minimum: -360
          maximum: 360
        scale:
          description: Uniform scale factor
          $ref: '#/components/schemas/PositiveScale'
        origin:
          description: '[x, y, z] placement origin'
          $ref: '#/components/schemas/Point3'
        direction:
          description: '[x, y, z] up direction'
          $ref: '#/components/schemas/Point3'
      additionalProperties: false
      description: Dragon Cup model parameters - all optional, sane defaults apply
    MeshPrecision:
      type: number
      minimum: 0.0001
      maximum: 10
      description: 'Mesh tessellation precision (lower = finer). Range: [0.0001, 10]'
      example: 0.1
    DragonCupBody:
      type: object
      properties:
        params:
          $ref: '#/components/schemas/DragonCupParams'
        outputs:
          $ref: '#/components/schemas/OutputOptions'
      required:
      - outputs
      additionalProperties: false
      description: Request body for the Dragon Cup model
  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.'