bitbybit-dev Files API

openapi: 3.2.0
info:
  title: Bitbybit CAD Cloud Files 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: Files
paths:
  /api/v1/files/upload:
    post:
      tags:
      - Files
      summary: Files - request an upload URL
      description: Returns a pre-signed URL for uploading a file via PUT.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileUploadBody'
      responses:
        '200':
          description: 'The same bytes were uploaded and confirmed under this key before (matched by sha256): the existing confirmed file, ready to reference. No PUT is needed.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmResponse'
        '201':
          description: Upload URL and file ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResponse'
        '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: postApiV1FilesUpload
      x-operation-id-source: derived
  /api/v1/files:
    get:
      tags:
      - Files
      summary: Files - list uploaded files
      description: Returns a paginated list of the files uploaded under your API key, newest first, with each file's id, original name, size, upload status and expiry. Use it to find the file id to pass to a conversion endpoint, and to check that an upload through a pre-signed URL actually completed before you reference it.
      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 files to return per page.
        schema:
          type: integer
          default: 20
      - name: status
        in: query
        required: false
        description: 'Return only files in this upload state: pending (a pre-signed URL was issued but the upload has not been confirmed), confirmed (the blob is stored and usable), or expired.'
        schema:
          type: string
          enum:
          - pending
          - confirmed
          - expired
      responses:
        '200':
          description: File list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileListResponse'
      operationId: getApiV1Files
      x-operation-id-source: derived
  /api/v1/files/{fileId}:
    get:
      tags:
      - Files
      summary: Files - get file details
      description: Returns metadata and download URL for a single file.
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: File ID
      responses:
        '200':
          description: File details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDetailResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getApiV1FilesByFileId
      x-operation-id-source: derived
    delete:
      tags:
      - Files
      summary: Files - delete a file
      description: Permanently deletes an uploaded file and the stored blob behind it. This cannot be undone, and any task result that still points at the blob stops resolving. Files also expire on their own, so call this only when you need the storage released sooner than that.
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: File ID
      responses:
        '200':
          description: File deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteFileResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: deleteApiV1FilesByFileId
      x-operation-id-source: derived
  /api/v1/files/{fileId}/confirm:
    post:
      tags:
      - Files
      summary: Files - confirm upload
      description: Confirms that the file was successfully uploaded to the pre-signed URL.
      parameters:
      - name: fileId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: File ID
      responses:
        '200':
          description: File confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postApiV1FilesByFileIdConfirm
      x-operation-id-source: derived
components:
  schemas:
    FileDetail:
      type: object
      properties:
        fileId:
          type: string
          description: Unique file identifier used to reference this file in CAD operations
          format: uuid
        filename:
          type: string
          description: Original filename as provided during upload request
        contentType:
          type: string
          description: MIME type of the file content
        bytes:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
          description: File size in bytes. Null while status is 'pending' (not yet uploaded).
        sha256:
          anyOf:
          - type: string
          - type: 'null'
          description: SHA-256 hex digest of the file content. Null if not provided during upload. Used for deduplication.
        status:
          $ref: '#/components/schemas/FileStatus'
        createdAt:
          type: string
          description: ISO 8601 timestamp when the upload was initiated
        confirmedAt:
          anyOf:
          - type: string
          - type: 'null'
          description: ISO 8601 timestamp when the upload was confirmed. Null if not yet confirmed.
        downloadUrl:
          description: Pre-signed download URL. Only present for confirmed files. Expires after 1 hour.
          type: string
      required:
      - fileId
      - filename
      - contentType
      - bytes
      - sha256
      - status
      - createdAt
      - confirmedAt
      additionalProperties: false
      description: Full metadata for an uploaded file
    FileUploadBody:
      type: object
      properties:
        filename:
          type: string
          minLength: 1
          maxLength: 255
          description: Original filename including extension (e.g. 'part.step', 'model.obj'). Used for display and format detection.
        contentType:
          type: string
          minLength: 1
          maxLength: 255
          description: MIME type of the file (e.g. 'application/step', 'model/gltf-binary'). Must match the actual file content.
        bytes:
          type: integer
          exclusiveMinimum: 0
          maximum: 1073741824
          description: 'Exact file size in bytes. Must match the Content-Length of the subsequent PUT to the upload URL. Maximum: 1 GB.'
        sha256:
          description: SHA-256 hex digest of the file content. When provided, enables server-side deduplication - if an identical file was previously uploaded under this API key, the existing file is reused and no upload is needed.
          type: string
          minLength: 1
          maxLength: 128
      required:
      - filename
      - contentType
      - bytes
      additionalProperties: false
      description: Request a pre-signed upload URL. After receiving the URL, PUT the raw file bytes to it within the expiration window.
    FileDetailResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/FileDetail'
      required:
      - ok
      - data
      additionalProperties: false
      description: Success envelope containing a single file's metadata
    UploadResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/UploadResult'
      required:
      - ok
      - data
      additionalProperties: false
      description: Success envelope containing the pre-signed upload URL and file metadata
    ConfirmResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/ConfirmResult'
      required:
      - ok
      - data
      additionalProperties: false
      description: Success envelope confirming a file upload was verified
    FileListResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/FileList'
      required:
      - ok
      - data
      additionalProperties: false
      description: Success envelope containing a paginated file list
    DeleteResult:
      type: object
      properties:
        deleted:
          type: boolean
          const: true
      required:
      - deleted
      additionalProperties: false
      description: Confirmation that a resource was successfully deleted
    FileStatus:
      type: string
      enum:
      - pending
      - confirmed
      - expired
      description: 'File lifecycle state: ''pending'' (upload URL issued, awaiting PUT), ''confirmed'' (upload verified and file is usable), ''expired'' (upload URL expired before completion)'
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
      - ok
      - error
      additionalProperties: false
      description: Standard error envelope
    FileList:
      type: object
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/FileDetail'
        page:
          type: integer
          exclusiveMinimum: 0
          maximum: 1000
        limit:
          type: integer
          exclusiveMinimum: 0
          maximum: 50
        total:
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
      - files
      - page
      - limit
      - total
      additionalProperties: false
      description: Paginated list of uploaded files with total count
    UploadResult:
      type: object
      properties:
        fileId:
          type: string
          description: Assigned file identifier - use this to reference the file in subsequent API calls
          format: uuid
        uploadUrl:
          type: string
          description: Pre-signed URL to PUT the raw file bytes to. Send the file content with Content-Type and Content-Length headers matching the request.
          format: uri
        expiresIn:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
          description: Seconds until the upload URL expires. You must complete the PUT within this window.
        maxBytes:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
          description: Maximum allowed file size in bytes for this upload. Determined by your plan tier.
        status:
          type: string
          const: pending
      required:
      - fileId
      - uploadUrl
      - expiresIn
      - maxBytes
      - status
      additionalProperties: false
      description: Response after requesting a file upload. Contains the pre-signed URL to PUT your file to.
    ConfirmResult:
      type: object
      properties:
        fileId:
          type: string
          description: File identifier that was confirmed
          format: uuid
        status:
          type: string
          const: confirmed
        bytes:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Actual file size in bytes as stored on the server
        contentType:
          type: string
          description: MIME type of the confirmed file
      required:
      - fileId
      - status
      - bytes
      - contentType
      additionalProperties: false
      description: Returned after a file upload is verified. The file is now ready to be used in CAD operations.
    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
    DeleteFileResponse:
      type: object
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/DeleteResult'
      required:
      - ok
      - data
      additionalProperties: false
      description: Success response for file deletion
  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.'