Opentrons Run Management API

openapi: 3.1.0
info:
  title: Opentrons HTTP Attached Instruments Run Management 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: Run Management
  description: Create and control protocol runs
paths:
  /runs:
    post:
      tags:
      - Run Management
      summary: Create a run
      description: Create a new protocol run. A run can be created from an existing protocol or as an empty run for ad-hoc commands.
      operationId: createRun
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRunRequest'
      responses:
        '201':
          description: Run created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
    get:
      tags:
      - Run Management
      summary: Get all runs
      description: Get a list of all runs on the robot.
      operationId: getRuns
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: pageLength
        in: query
        schema:
          type: integer
          default: 20
        description: Maximum number of runs to return
      responses:
        '200':
          description: List of runs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunListResponse'
  /runs/{runId}:
    get:
      tags:
      - Run Management
      summary: Get a run
      description: Get the current state of a specific run by its ID.
      operationId: getRun
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: runId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Run details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
        '404':
          description: Run not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Run Management
      summary: Delete a run
      description: Delete a specific run from the robot.
      operationId: deleteRun
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: runId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Run deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
    patch:
      tags:
      - Run Management
      summary: Update a run
      description: Update properties of an existing run, such as setting it as the current run.
      operationId: updateRun
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: runId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRunRequest'
      responses:
        '200':
          description: Run updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
  /runs/{runId}/actions:
    post:
      tags:
      - Run Management
      summary: Issue a control action to the run
      description: Issue a control action such as play, pause, stop, or resume-from-recovery to a run.
      operationId: createRunAction
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: runId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunActionRequest'
      responses:
        '201':
          description: Action issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunActionResponse'
  /runs/{runId}/commands:
    post:
      tags:
      - Run Management
      summary: Enqueue a command
      description: Add a command to a run. Commands can be setup, protocol, or fixit commands.
      operationId: createRunCommand
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: runId
        in: path
        required: true
        schema:
          type: string
      - name: waitUntilComplete
        in: query
        schema:
          type: boolean
          default: false
        description: If true, wait for the command to complete before returning
      - name: timeout
        in: query
        schema:
          type: integer
        description: Timeout in milliseconds when waitUntilComplete is true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommandRequest'
      responses:
        '201':
          description: Command enqueued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResponse'
    get:
      tags:
      - Run Management
      summary: Get a list of all protocol commands in the run
      description: Get a paginated list of all commands in the run, including their current status.
      operationId: getRunCommands
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: runId
        in: path
        required: true
        schema:
          type: string
      - name: cursor
        in: query
        schema:
          type: integer
        description: Index to start returning results from
      - name: pageLength
        in: query
        schema:
          type: integer
          default: 20
        description: Number of commands to return
      responses:
        '200':
          description: List of commands
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandListResponse'
  /runs/{runId}/commands/{commandId}:
    get:
      tags:
      - Run Management
      summary: Get full details about a specific command in the run
      description: Get the complete details of a single command in a run by its ID.
      operationId: getRunCommand
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: runId
        in: path
        required: true
        schema:
          type: string
      - name: commandId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Command details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandResponse'
components:
  schemas:
    UpdateRunRequest:
      type: object
      properties:
        data:
          type: object
          properties:
            current:
              type: boolean
              description: Set this run as the current active run
    CommandResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Command'
    RunResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Run'
        links:
          type: object
    ErrorDetail:
      type: object
      properties:
        id:
          type: string
          description: Machine-readable error type identifier
        title:
          type: string
          description: Human-readable error title
        detail:
          type: string
          description: Human-readable error detail
        errorCode:
          type: string
          description: Opentrons error code
    RunActionRequest:
      type: object
      properties:
        data:
          type: object
          properties:
            actionType:
              type: string
              enum:
              - play
              - pause
              - stop
              - resume-from-recovery
              - resume-from-recovery-assuming-false-positive
              description: The type of control action to issue
          required:
          - actionType
      required:
      - data
    RunAction:
      type: object
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        actionType:
          type: string
          enum:
          - play
          - pause
          - stop
          - resume-from-recovery
          - resume-from-recovery-assuming-false-positive
    CreateRunRequest:
      type: object
      properties:
        data:
          type: object
          properties:
            protocolId:
              type: string
              description: The ID of the protocol to run
            labwareOffsets:
              type: array
              items:
                type: object
              description: Labware offsets to apply to this run
            runTimeParameterValues:
              type: object
              additionalProperties: true
              description: Runtime parameter values keyed by variable name
            runTimeParameterFiles:
              type: object
              additionalProperties:
                type: string
              description: CSV file IDs keyed by parameter variable name
    Command:
      type: object
      description: A command that was executed or is queued
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
          nullable: true
        completedAt:
          type: string
          format: date-time
          nullable: true
        commandType:
          type: string
        params:
          type: object
          additionalProperties: true
        result:
          type: object
          nullable: true
          additionalProperties: true
        status:
          type: string
          enum:
          - queued
          - running
          - succeeded
          - failed
        error:
          type: object
          nullable: true
        intent:
          type: string
          enum:
          - setup
          - protocol
          - fixit
        key:
          type: string
          nullable: true
    RunListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Run'
        meta:
          $ref: '#/components/schemas/MultiBodyMeta'
        links:
          type: object
    CommandRequest:
      type: object
      description: A command to execute on the robot
      properties:
        data:
          type: object
          properties:
            commandType:
              type: string
              description: The type of command to execute (e.g., 'aspirate', 'dispense', 'pickUpTip')
            params:
              type: object
              description: Command-specific parameters
              additionalProperties: true
            intent:
              type: string
              enum:
              - setup
              - protocol
              - fixit
              description: The intent of the command
            key:
              type: string
              description: Optional key to identify this command for error recovery
          required:
          - commandType
          - params
      required:
      - data
    Run:
      type: object
      description: A protocol run on the robot
      properties:
        id:
          type: string
          description: Unique identifier for the run
        createdAt:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - idle
          - running
          - paused
          - stop-requested
          - stopped
          - failed
          - succeeded
          - finishing
          description: The current status of the run
        current:
          type: boolean
          description: Whether this is the current active run
        actions:
          type: array
          items:
            $ref: '#/components/schemas/RunAction'
        errors:
          type: array
          items:
            type: object
        pipettes:
          type: array
          items:
            type: object
        labware:
          type: array
          items:
            type: object
        modules:
          type: array
          items:
            type: object
        protocolId:
          type: string
          nullable: true
          description: The ID of the protocol associated with this run
        runTimeParameters:
          type: array
          items:
            type: object
      required:
      - id
      - createdAt
      - status
      - current
      - actions
      - errors
      - pipettes
      - labware
      - modules
    ErrorResponse:
      type: object
      description: Error response from the API
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
    RunActionResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/RunAction'
    CommandListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Command'
        meta:
          $ref: '#/components/schemas/MultiBodyMeta'
        links:
          type: object
    MultiBodyMeta:
      type: object
      description: Pagination metadata for multi-item responses
      properties:
        cursor:
          type: integer
          description: The index of the first item in this page
        totalLength:
          type: integer
          description: The total number of items available
  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: '*'