openapi: 3.1.0
info:
  title: Opentrons HTTP Attached Instruments API
  description: The Opentrons HTTP API is a RESTful JSON-based interface exposed by Opentrons robots (Flex and OT-2) on the local network at port 31950. It enables developers to upload and manage protocols, create and control runs, issue atomic liquid handling commands, and query robot health and hardware state. The API is defined by an OpenAPI specification available directly from the robot at /openapi.json.
  version: '4'
  contact:
    name: Opentrons Support
    url: https://support.opentrons.com/
    email: support@opentrons.com
  license:
    name: Apache 2.0
    url: https://github.com/Opentrons/opentrons/blob/edge/LICENSE
  x-api-version-header: Opentrons-Version
  x-min-api-version: 2
servers:
- url: http://{robotIP}:31950
  description: Opentrons robot local network server
  variables:
    robotIP:
      default: 192.168.1.100
      description: The IP address of the Opentrons robot on the local network
tags:
- name: Attached Instruments
  description: Query attached pipettes and grippers
paths:
  /instruments:
    get:
      tags:
      - Attached Instruments
      summary: Get attached instruments
      description: Get a list of all instruments (pipettes and gripper) currently attached to the robot.
      operationId: getInstruments
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: refresh
        in: query
        schema:
          type: boolean
          default: false
        description: If true, refresh the instrument cache before returning
      responses:
        '200':
          description: List of attached instruments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstrumentListResponse'
components:
  schemas:
    Instrument:
      type: object
      description: A pipette or gripper attached to the robot
      properties:
        mount:
          type: string
          enum:
          - left
          - right
          - extension
          description: The mount position of the instrument
        instrumentType:
          type: string
          enum:
          - pipette
          - gripper
        instrumentModel:
          type: string
        serialNumber:
          type: string
        subsystems:
          type: array
          items:
            type: string
        data:
          type: object
          additionalProperties: true
    InstrumentListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Instrument'
  parameters:
    OTVersionHeader:
      name: Opentrons-Version
      in: header
      required: true
      description: The HTTP API version to use for this request. Must be 2 or higher. Use '*' to get the latest version.
      schema:
        oneOf:
        - type: string
          enum:
          - '*'
        - type: integer
          minimum: 2
          maximum: 4
      example: '*'