bitbybit-dev Models API

openapi: 3.2.0
info:
  title: Bitbybit CAD Cloud Models 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
paths:
  /api/v1/models:
    get:
      tags:
      - Models
      summary: Models - list available models
      description: Lists every parametric model available for generation, by name. Use the returned names with the definitions and generation endpoints to discover each model's parameter schema and defaults before submitting a job.
      responses:
        '200':
          description: Model name list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelListResponse'
      operationId: getApiV1Models
      x-operation-id-source: derived
  /api/v1/models/definitions:
    post:
      tags:
      - Models
      summary: Models - batch-fetch definitions
      description: Returns parameter schemas and defaults for the requested model names.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DefinitionsBody'
      responses:
        '200':
          description: Model definitions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelBatchDefinitionsResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postApiV1ModelsDefinitions
      x-operation-id-source: derived
  /api/v1/models/{modelName}:
    post:
      tags:
      - Models
      summary: Models - execute a parametric model
      description: Generic endpoint - works for any registered model. See model-specific endpoints for fully typed parameters. Always returns 202 with a task ID for polling.
      parameters:
      - name: modelName
        in: path
        required: true
        schema:
          type: string
        description: Model slug (e.g. dragon-cup, phone-nest)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModelSubmissionBody'
      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'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postApiV1ModelsByModelName
      x-operation-id-source: derived
  /api/v1/models/{modelName}/batch:
    post:
      tags:
      - Models
      summary: Models - generate a batch
      description: Creates a compound task with one sub-task per item. Each item can have different parameters but shares the same output config.
      parameters:
      - name: modelName
        in: path
        required: true
        schema:
          type: string
        description: Model slug (e.g. dragon-cup, phone-nest)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchModelSubmissionBody'
      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'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postApiV1ModelsByModelNameBatch
      x-operation-id-source: derived
  /api/v1/models/{modelName}/params:
    get:
      tags:
      - Models
      summary: Models - get parameter definitions
      description: Returns parameter schema, types, defaults, and limits for the specified model.
      parameters:
      - name: modelName
        in: path
        required: true
        schema:
          type: string
        description: Model slug (e.g. dragon-cup, phone-nest)
      responses:
        '200':
          description: Model definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelDefinitionResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getApiV1ModelsByModelNameParams
      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.'
    ModelBatchDefinitionsResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/ModelBatchDefinitions'
      required:
      - ok
      - data
      additionalProperties: false
      description: Success envelope containing multiple model definitions
    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)'
    ModelList:
      type: object
      properties:
        models:
          type: array
          items:
            type: string
          description: Available model slugs that can be used with the /models/{name} endpoints
      required:
      - models
      additionalProperties: false
      description: List of all available parametric models
    ModelSubmissionBody:
      type: object
      properties:
        params:
          description: Model-specific parameters. Omitted params use their defaults. See model definition for available options.
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        outputs:
          $ref: '#/components/schemas/OutputOptions'
      required:
      - outputs
      additionalProperties: false
      description: Submit a parametric model for generation with specified parameters and output formats
    ModelParamDefinition:
      type: object
      properties:
        name:
          type: string
          description: Parameter name as used in the request body
        type:
          description: Expected data type for this parameter
          $ref: '#/components/schemas/ModelParamApiType'
        description:
          type: string
          description: Human-readable explanation of what this parameter controls
        default:
          description: Default value used when the parameter is omitted
        items:
          description: Element type descriptor (only present for array parameters)
          type: object
          properties:
            type:
              type: string
          required:
          - type
          additionalProperties: false
      required:
      - name
      - type
      - description
      - default
      additionalProperties: false
      description: Schema definition for a single model parameter
    ModelParamApiType:
      type: string
      enum:
      - number
      - integer
      - boolean
      - array
      description: 'Data type of a model parameter: ''number'' (float), ''integer'' (whole number), ''boolean'' (true/false), ''array'' (list of values)'
    ModelDefinition:
      type: object
      properties:
        name:
          type: string
          description: Model slug used in API paths (e.g. 'dragon-cup')
        displayName:
          type: string
          description: Human-friendly model name for UI display
        description:
          type: string
          description: What this model creates and its key characteristics
        params:
          type: array
          items:
            $ref: '#/components/schemas/ModelParamDefinition'
          description: All accepted parameters with types, descriptions, and defaults
        defaults:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
          description: Complete default parameter values map
      required:
      - name
      - displayName
      - description
      - params
      - defaults
      additionalProperties: false
      description: Full definition of a parametric model including all parameters and their constraints
    BatchModelSubmissionBody:
      type: object
      properties:
        items:
          minItems: 1
          maxItems: 50
          type: array
          items:
            type: object
            properties:
              params:
                type: object
                propertyNames:
                  type: string
                additionalProperties: {}
          description: Array of parameter variations. Each item produces a separate output with the same model.
        outputs:
          description: Output format configuration applied to every item in the batch
          $ref: '#/components/schemas/OutputOptions'
      required:
      - items
      - outputs
      description: Submit multiple parameter variations of the same model for parallel generation
    MeshPrecision:
      type: number
      minimum: 0.0001
      maximum: 10
      description: 'Mesh tessellation precision (lower = finer). Range: [0.0001, 10]'
      example: 0.1
    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
    DefinitionsBody:
      type: object
      properties:
        names:
          minItems: 1
          type: array
          items:
            type: string
            minLength: 1
          description: Array of model slugs to fetch definitions for (e.g. ['dragon-cup', 'phone-nest'])
      required:
      - names
      additionalProperties: false
      description: Fetch parameter definitions for one or more parametric models. Returns available parameters, types, defaults, and constraints.
    ModelBatchDefinitions:
      type: object
      properties:
        definitions:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            $ref: '#/components/schemas/ModelDefinition'
          description: Model definitions keyed by slug. Each contains parameter schemas and defaults.
      required:
      - definitions
      additionalProperties: false
      description: Definitions for multiple models in a single response
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
      - ok
      - error
      additionalProperties: false
      description: Standard error envelope
    ModelDefinitionResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/ModelDefinition'
      required:
      - ok
      - data
      additionalProperties: false
      description: Success envelope containing a single model's definition
    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
    ModelListResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/ModelList'
      required:
      - ok
      - data
      additionalProperties: false
      description: Success envelope containing the list of available models
    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
    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.'