openapi: 3.0.1
info:
  title: Formlabs Web API
  description: >-
    The Formlabs Web API (Dashboard Developer API) provides remote monitoring
    and management of Internet-connected Formlabs products registered to a
    Dashboard account. It exposes read access to printers, prints, resin tanks,
    and cartridges, an event history feed, and full CRUD management of printer
    groups and their print queues. Typical use cases include automated reports
    on printer and material usage, job history exports, and integration of
    printer status into ERP / MES / custom systems.
  termsOfService: https://formlabs.com/terms-of-service/
  contact:
    name: Formlabs Developer Support
    url: https://support.formlabs.com/s/topic/Developer-Portal
  version: '1.0'
servers:
  - url: https://api.formlabs.com/developer/v1
    description: Formlabs Web API (Dashboard Developer API)
security:
  - OAuth2ClientCredentials: []
paths:
  /printers/:
    get:
      operationId: listPrinters
      tags:
        - Printers
      summary: List printers
      description: List all printers registered to the authenticated Dashboard account.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: per_page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A paginated list of printers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrinterList'
  /printers/{printer_serial}/:
    get:
      operationId: getPrinter
      tags:
        - Printers
      summary: Retrieve a printer
      description: Retrieve a single printer by its serial number.
      parameters:
        - name: printer_serial
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested printer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Printer'
  /printers/{printer_serial}/prints/:
    get:
      operationId: listPrinterPrints
      tags:
        - Prints
      summary: List prints for a printer
      description: List prints run on a specific printer.
      parameters:
        - name: printer_serial
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
        - name: per_page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A paginated list of prints for the printer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintList'
  /prints/:
    get:
      operationId: listPrints
      tags:
        - Prints
      summary: List and search prints
      description: >-
        List and search all prints across the account, with filtering by date,
        material, name, status, machine type, and printer.
      parameters:
        - name: date
          in: query
          schema:
            type: string
            format: date-time
        - name: date__gt
          in: query
          schema:
            type: string
            format: date-time
        - name: date__lt
          in: query
          schema:
            type: string
            format: date-time
        - name: material
          in: query
          schema:
            type: string
        - name: name
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum:
              - QUEUED
              - PREPRINT
              - PRINTING
              - PAUSING
              - PAUSED
              - FINISHED
              - ABORTING
              - ABORTED
              - ERROR
              - WAITING_FOR_RESOLUTION
              - PREHEAT
              - PRECOAT
              - POSTCOAT
        - name: machine_type_id
          in: query
          schema:
            type: array
            items:
              type: string
        - name: printer
          in: query
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
        - name: per_page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A paginated list of prints.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintList'
  /tanks/:
    get:
      operationId: listTanks
      tags:
        - Consumables
      summary: List resin tanks
      description: List all resin tanks associated with the account.
      responses:
        '200':
          description: A paginated list of resin tanks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TankList'
  /cartridges/:
    get:
      operationId: listCartridges
      tags:
        - Consumables
      summary: List resin cartridges
      description: List all resin cartridges associated with the account.
      responses:
        '200':
          description: A paginated list of resin cartridges.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartridgeList'
  /events/:
    get:
      operationId: listEvents
      tags:
        - Events
      summary: List events
      description: >-
        List the event history (print started/finished, errors, consumable
        changes, etc.) for the account. This is a polling endpoint; the Formlabs
        Web API does not publish push webhooks. Filter by printer, cartridge,
        tank, print run, type, and date range.
      parameters:
        - name: printer
          in: query
          schema:
            type: string
        - name: cartridge
          in: query
          schema:
            type: string
        - name: tank
          in: query
          schema:
            type: string
        - name: print_run
          in: query
          schema:
            type: string
        - name: type
          in: query
          schema:
            type: string
        - name: date__gt
          in: query
          schema:
            type: string
            format: date-time
        - name: date__lt
          in: query
          schema:
            type: string
            format: date-time
        - name: page
          in: query
          schema:
            type: integer
        - name: per_page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A paginated list of events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventList'
  /groups/:
    get:
      operationId: listGroups
      tags:
        - Groups
      summary: List printer groups
      description: List all printer groups the authenticated account can access.
      responses:
        '200':
          description: A list of printer groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupList'
    post:
      operationId: createGroup
      tags:
        - Groups
      summary: Create a printer group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupWrite'
      responses:
        '201':
          description: The created group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
  /groups/{group_id}/:
    patch:
      operationId: updateGroup
      tags:
        - Groups
      summary: Update a printer group
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupWrite'
      responses:
        '200':
          description: The updated group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
    delete:
      operationId: deleteGroup
      tags:
        - Groups
      summary: Delete a printer group
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: The group was deleted.
  /groups/bulk-add-printers/:
    post:
      operationId: bulkAddPrintersToGroup
      tags:
        - Groups
      summary: Move printers into a group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group:
                  type: string
                printers:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Printers were moved to the group.
  /groups/{group_id}/members/:
    post:
      operationId: inviteGroupMember
      tags:
        - Groups
      summary: Invite a user to a group
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupMemberWrite'
      responses:
        '201':
          description: The user was invited.
    put:
      operationId: updateGroupMember
      tags:
        - Groups
      summary: Update a group membership
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupMemberWrite'
      responses:
        '200':
          description: The membership was updated.
    delete:
      operationId: removeGroupMember
      tags:
        - Groups
      summary: Remove a group member
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
        - name: user
          in: query
          schema:
            type: string
      responses:
        '204':
          description: The member was removed.
  /groups/{group_id}/queue/:
    get:
      operationId: listGroupQueue
      tags:
        - Groups
      summary: List group queue items
      description: List queued print jobs for a printer group.
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of queue items for the group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueItemList'
components:
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      description: >-
        OAuth 2.0 Client Credentials flow. Exchange a client_id and
        client_secret at the token endpoint for a Bearer access token valid for
        24 hours, scoped to developer-api. The Formlabs identity provider also
        supports OpenID Connect for interactive sign-in via PreForm / Local API.
      flows:
        clientCredentials:
          tokenUrl: https://api.formlabs.com/developer/v1/o/token/
          scopes:
            developer-api: Access the Formlabs Dashboard Developer API
  schemas:
    Printer:
      type: object
      properties:
        serial:
          type: string
        alias:
          type: string
        machine_type_id:
          type: string
        printer_status:
          type: object
          properties:
            status:
              type: string
            last_pinged_at:
              type: string
              format: date-time
        firmware_version:
          type: string
        location:
          type: string
        group:
          type: string
    PrinterList:
      type: object
      properties:
        count:
          type: integer
        next:
          type: string
          nullable: true
        previous:
          type: string
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/Printer'
    Print:
      type: object
      properties:
        guid:
          type: string
        name:
          type: string
        printer:
          type: string
        status:
          type: string
        material:
          type: string
        layer_thickness_mm:
          type: number
        volume_ml:
          type: number
        layer_count:
          type: integer
        current_layer:
          type: integer
        z_height_offset_mm:
          type: number
        print_started_at:
          type: string
          format: date-time
        print_finished_at:
          type: string
          format: date-time
        estimated_duration_ms:
          type: integer
        elapsed_duration_ms:
          type: integer
        cartridge:
          type: string
        tank:
          type: string
        user:
          type: string
        thumbnail:
          type: string
        group:
          type: string
    PrintList:
      type: object
      properties:
        count:
          type: integer
        next:
          type: string
          nullable: true
        previous:
          type: string
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/Print'
    Tank:
      type: object
      properties:
        serial:
          type: string
        material:
          type: string
        total_print_time_ms:
          type: integer
        layer_count:
          type: integer
        connected_printer:
          type: string
    TankList:
      type: object
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Tank'
    Cartridge:
      type: object
      properties:
        serial:
          type: string
        material:
          type: string
        initial_volume_ml:
          type: number
        volume_dispensed_ml:
          type: number
        is_empty:
          type: boolean
        connected_printer:
          type: string
    CartridgeList:
      type: object
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Cartridge'
    Event:
      type: object
      properties:
        id:
          type: string
        printer:
          type: string
        created_at:
          type: string
          format: date-time
        type:
          type: string
        type_label:
          type: string
        action:
          type: string
        message:
          type: string
        print_run:
          type: string
        tank:
          type: string
        cartridge:
          type: string
        read:
          type: boolean
        group:
          type: string
    EventList:
      type: object
      properties:
        count:
          type: integer
        next:
          type: string
          nullable: true
        previous:
          type: string
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    Group:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        members:
          type: array
          items:
            $ref: '#/components/schemas/GroupMember'
    GroupWrite:
      type: object
      required:
        - name
      properties:
        name:
          type: string
    GroupList:
      type: object
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Group'
    GroupMember:
      type: object
      properties:
        user:
          type: string
        email:
          type: string
        role:
          type: string
    GroupMemberWrite:
      type: object
      required:
        - email
      properties:
        email:
          type: string
        role:
          type: string
    QueueItem:
      type: object
      properties:
        guid:
          type: string
        name:
          type: string
        material:
          type: string
        position:
          type: integer
        status:
          type: string
    QueueItemList:
      type: object
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/QueueItem'