bitbybit-dev Tasks API

openapi: 3.2.0
info:
  title: Bitbybit CAD Cloud Tasks 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: Tasks
paths:
  /api/v1/tasks:
    get:
      tags:
      - Tasks
      summary: Tasks - list tasks
      description: Returns a paginated list of your tasks, newest first, each with its id, kind, status, creation time and result link when finished. Filter by status to poll only what is still running, or by kind to separate model generation, STEP conversion, pipelines and compound runs. This is the endpoint to build a job dashboard on rather than polling every task id individually.
      parameters:
      - name: page
        in: query
        required: false
        description: 1-based page number. Defaults to the first page.
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        required: false
        description: How many tasks to return per page.
        schema:
          type: integer
          default: 20
      - name: status
        in: query
        required: false
        description: Return only tasks in this state. waiting and queued are not started yet, processing is running, completed has a downloadable result, failed carries an error, cancelled was stopped by you, and expired means the result has been cleaned up.
        schema:
          type: string
          enum:
          - waiting
          - queued
          - processing
          - completed
          - failed
          - cancelled
          - expired
      - name: kind
        in: query
        required: false
        description: 'Return only tasks of this kind: cad for a single operation, model for a registered parametric model, convert-simple and convert-advanced for STEP conversions, pipeline for a chained run, compound for a parallel run.'
        schema:
          type: string
          enum:
          - cad
          - model
          - convert-simple
          - convert-advanced
          - pipeline
          - compound
      responses:
        '200':
          description: Task list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskListResponse'
      operationId: getApiV1Tasks
      x-operation-id-source: derived
  /api/v1/tasks/{taskId}:
    get:
      tags:
      - Tasks
      summary: Tasks - get task status
      description: Returns the current status and metadata of a task.
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Task ID
      responses:
        '200':
          description: Task status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskDetailResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getApiV1TasksByTaskId
      x-operation-id-source: derived
    delete:
      tags:
      - Tasks
      summary: Tasks - cancel a task
      description: Cancels a waiting or queued task. Has no effect on completed/failed tasks.
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Task ID
      responses:
        '200':
          description: Task cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelTaskResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: deleteApiV1TasksByTaskId
      x-operation-id-source: derived
  /api/v1/tasks/{taskId}/result:
    get:
      tags:
      - Tasks
      summary: Tasks - get result (default format)
      description: Returns a download URL for the task's primary result. For compound tasks, returns a manifest with per-sub-task download links.
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Task ID
      responses:
        '200':
          description: Result download link (standard) or compound manifest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskOrCompoundResultResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Task is not yet completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getApiV1TasksByTaskIdResult
      x-operation-id-source: derived
  /api/v1/tasks/{taskId}/result/{format}:
    get:
      tags:
      - Tasks
      summary: Tasks - get result in a specific format
      description: Returns a download URL for the requested output format (e.g. glb, step, stpz).
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Task ID
      - name: format
        in: path
        required: true
        schema:
          type: string
        description: Result format (e.g. glb, step, stpz, metadata, decomposed-mesh)
      responses:
        '200':
          description: Result download link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResultResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Task is not yet completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getApiV1TasksByTaskIdResultByFormat
      x-operation-id-source: derived
  /api/v1/tasks/{taskId}/results:
    get:
      tags:
      - Tasks
      summary: Tasks - get all results
      description: Returns download URLs for every available result format in a single call. Use this instead of making multiple requests to /result/{format}.
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Task ID
      responses:
        '200':
          description: Download links for all available formats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResultsResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Task is not yet completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getApiV1TasksByTaskIdResults
      x-operation-id-source: derived
  /api/v1/tasks/{taskId}/retry:
    post:
      tags:
      - Tasks
      summary: Tasks - retry a failed or cancelled task
      description: Re-queues a failed or cancelled task with the same parameters.
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Task ID
      responses:
        '202':
          description: Task re-queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskAcceptedResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Task is not in a retryable state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postApiV1TasksByTaskIdRetry
      x-operation-id-source: derived
components:
  schemas:
    CancelTaskResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/CancelResult'
      required:
      - ok
      - data
      additionalProperties: false
      description: Success response for task cancellation
    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.
    CompoundResultEntry:
      type: object
      properties:
        taskId:
          type: string
          description: Sub-task ID
        index:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Position in the compound task
        status:
          $ref: '#/components/schemas/TaskStatus'
        downloadUrls:
          description: Download URLs keyed by format (only if completed)
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
      required:
      - taskId
      - index
      - status
      additionalProperties: false
      description: Status/result info for one sub-task in a compound manifest
    CompoundResultManifest:
      type: object
      properties:
        manifest:
          type: array
          items:
            $ref: '#/components/schemas/CompoundResultEntry'
          description: Per-sub-task status and download links
      required:
      - manifest
      additionalProperties: false
      description: Result manifest for a completed compound task
    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)'
    TaskResultsResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/TaskResultsDownload'
      required:
      - ok
      - data
      additionalProperties: false
      description: Success envelope containing download links for all result formats
    TaskResultsDownload:
      type: object
      properties:
        downloads:
          type: array
          items:
            type: object
            properties:
              format:
                type: string
                description: Result format key (e.g. 'glb', 'step', 'metadata')
              downloadUrl:
                type: string
                description: Pre-signed URL to download the result file. Expires after 1 hour.
                format: uri
              filename:
                type: string
                description: Suggested filename for the download
                example: result.glb
            required:
            - format
            - downloadUrl
            - filename
            additionalProperties: false
          description: Download links for all available result formats
      required:
      - downloads
      additionalProperties: false
      description: Download information for all available result formats of a completed task
    ResultPartMeta:
      type: object
      properties:
        mime:
          type: string
          description: MIME type of the result file (e.g. 'model/gltf-binary', 'application/step')
        bytes:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Size of the result file in bytes
      required:
      - mime
      - bytes
      additionalProperties: false
      description: Metadata about a single downloadable result part
    TaskKind:
      type: string
      enum:
      - cad
      - model
      - convert-simple
      - convert-advanced
      - pipeline
      - compound
      - tenant
      description: 'Type of work: ''cad'' (single operation), ''model'' (parametric model), ''convert-simple''/''convert-advanced'' (file conversion), ''pipeline'' (sequential chain), ''compound'' (parallel batch), ''tenant'' (tenant-scoped)'
    TaskResultDownload:
      type: object
      properties:
        downloadUrl:
          type: string
          description: Pre-signed URL to download the result file. Expires after 1 hour.
          format: uri
        filename:
          type: string
          description: Suggested filename for the download
          example: result.glb
      required:
      - downloadUrl
      - filename
      additionalProperties: false
      description: Download information for a completed task result
    TaskList:
      type: object
      properties:
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/TaskDetail'
        page:
          type: integer
          exclusiveMinimum: 0
          maximum: 1000
        limit:
          type: integer
          exclusiveMinimum: 0
          maximum: 50
        total:
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
      - tasks
      - page
      - limit
      - total
      additionalProperties: false
      description: Paginated list of tasks with total count
    TaskDetailResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/TaskDetail'
      required:
      - ok
      - data
      additionalProperties: false
      description: Success envelope containing a single task's full details
    CancelResult:
      type: object
      properties:
        cancelled:
          type: boolean
          const: true
        previousStatus:
          type: string
          description: Status before cancellation
      required:
      - cancelled
      - previousStatus
      additionalProperties: false
      description: Confirmation that a task was successfully cancelled
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
      - ok
      - error
      additionalProperties: false
      description: Standard error envelope
    TaskDetail:
      type: object
      properties:
        taskId:
          type: string
          description: Unique task identifier for polling and result retrieval
          format: uuid
        kind:
          $ref: '#/components/schemas/TaskKind'
        label:
          type: string
          description: Human-readable task label
          example: 'Model: dragon-cup'
        status:
          $ref: '#/components/schemas/TaskStatus'
        progress:
          anyOf:
          - type: number
          - type: 'null'
          description: Completion percentage (0–100) or null if progress is not tracked for this task kind
        error:
          anyOf:
          - type: string
          - type: 'null'
          description: Error message when status is 'failed'. Null for all other statuses.
        resultParts:
          anyOf:
          - type: object
            propertyNames:
              type: string
            additionalProperties:
              $ref: '#/components/schemas/ResultPartMeta'
          - type: 'null'
          description: Available result files keyed by format (e.g. 'glb', 'step'). Null until task completes.
        metadata:
          anyOf:
          - type: object
            propertyNames:
              type: string
            additionalProperties: {}
          - type: 'null'
          description: Additional task metadata (e.g. resolved parameters, model name). Shape varies by task kind.
        createdAt:
          type: string
          description: ISO 8601 timestamp when the task was created
        startedAt:
          anyOf:
          - type: string
          - type: 'null'
          description: ISO 8601 timestamp when processing began. Null if still queued.
        finishedAt:
          anyOf:
          - type: string
          - type: 'null'
          description: ISO 8601 timestamp when the task completed (success or failure). Null if still running.
        expiresAt:
          type: string
          description: ISO 8601 timestamp when task results will be automatically deleted
      required:
      - taskId
      - kind
      - label
      - status
      - progress
      - error
      - resultParts
      - metadata
      - createdAt
      - startedAt
      - finishedAt
      - expiresAt
      additionalProperties: false
      description: Complete task status including lifecycle timestamps, progress, and result metadata
    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
    TaskOrCompoundResultResponse:
      anyOf:
      - $ref: '#/components/schemas/TaskResultResponse'
      - $ref: '#/components/schemas/CompoundResultManifestResponse'
      description: Result download link for standard tasks, or a compound manifest with per-sub-task download links
    TaskResultResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/TaskResultDownload'
      required:
      - ok
      - data
      additionalProperties: false
      description: Success envelope containing a download link for a task result
    TaskListResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/TaskList'
      required:
      - ok
      - data
      additionalProperties: false
      description: Success envelope containing a paginated task list
    CompoundResultManifestResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/CompoundResultManifest'
      required:
      - ok
      - data
      additionalProperties: false
      description: Success envelope containing the compound task result manifest with per-sub-task download links
    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
  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.'