Opentrons Protocol Management API

openapi: 3.1.0
info:
  title: Opentrons HTTP Attached Instruments Protocol 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: Protocol Management
  description: Upload, manage, and analyze protocols
paths:
  /protocols:
    post:
      tags:
      - Protocol Management
      summary: Upload a protocol
      description: Upload a new protocol file (Python or JSON) to the robot. The protocol will be analyzed after upload.
      operationId: uploadProtocol
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Protocol file(s) to upload (Python .py or JSON .json)
                runTimeParameterValues:
                  type: string
                  description: JSON-encoded runtime parameter values
                runTimeParameterFiles:
                  type: string
                  description: JSON-encoded runtime parameter CSV file associations
                protocolKind:
                  type: string
                  enum:
                  - standard
                  - quick-transfer
                  description: The kind of protocol being uploaded
              required:
              - files
      responses:
        '201':
          description: Protocol uploaded and analysis queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtocolResponse'
        '422':
          description: Protocol file is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Protocol Management
      summary: Get uploaded protocols
      description: Get a list of all protocols that have been uploaded to the robot.
      operationId: getProtocols
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: protocolKind
        in: query
        description: Filter by protocol kind
        schema:
          type: string
          enum:
          - standard
          - quick-transfer
      responses:
        '200':
          description: List of uploaded protocols
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtocolListResponse'
  /protocols/{protocolId}:
    get:
      tags:
      - Protocol Management
      summary: Get an uploaded protocol
      description: Get details for a specific uploaded protocol by its ID.
      operationId: getProtocol
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: protocolId
        in: path
        required: true
        schema:
          type: string
        description: The protocol's unique identifier
      responses:
        '200':
          description: Protocol details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtocolResponse'
        '404':
          description: Protocol not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Protocol Management
      summary: Delete an uploaded protocol
      description: Delete a specific protocol from the robot by its ID.
      operationId: deleteProtocol
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: protocolId
        in: path
        required: true
        schema:
          type: string
        description: The protocol's unique identifier
      responses:
        '200':
          description: Protocol deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtocolResponse'
        '404':
          description: Protocol not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Protocol is in use by a run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /protocols/{protocolId}/analyses:
    post:
      tags:
      - Protocol Management
      summary: Analyze the protocol
      description: Trigger a new analysis of a protocol with the given runtime parameter values.
      operationId: analyzeProtocol
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: protocolId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalysisRequest'
      responses:
        '200':
          description: Analysis queued or completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisSummaryResponse'
    get:
      tags:
      - Protocol Management
      summary: Get a protocol's analyses
      description: Get all analyses for a given protocol.
      operationId: getProtocolAnalyses
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: protocolId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of analyses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisListResponse'
  /protocols/{protocolId}/analyses/{analysisId}:
    get:
      tags:
      - Protocol Management
      summary: Get one of a protocol's analyses
      description: Get the full details of a specific analysis by its ID.
      operationId: getProtocolAnalysis
      parameters:
      - $ref: '#/components/parameters/OTVersionHeader'
      - name: protocolId
        in: path
        required: true
        schema:
          type: string
      - name: analysisId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Analysis details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtocolAnalysis'
components:
  schemas:
    ProtocolFile:
      type: object
      properties:
        name:
          type: string
          description: The filename
        role:
          type: string
          enum:
          - main
          - labware
          - data
          description: The file's role in the protocol
    Protocol:
      type: object
      description: A protocol uploaded to the robot
      properties:
        id:
          type: string
          description: Unique identifier for the protocol
        createdAt:
          type: string
          format: date-time
          description: When the protocol was uploaded
        protocolType:
          type: string
          enum:
          - python
          - json
          description: The type of protocol
        protocolKind:
          type: string
          enum:
          - standard
          - quick-transfer
          description: The kind of protocol
        metadata:
          $ref: '#/components/schemas/ProtocolMetadata'
        analysisSummaries:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisSummary'
        files:
          type: array
          items:
            $ref: '#/components/schemas/ProtocolFile'
        robotType:
          type: string
          enum:
          - OT-2 Standard
          - OT-3 Standard
          nullable: true
      required:
      - id
      - createdAt
      - protocolType
      - protocolKind
      - metadata
      - analysisSummaries
      - files
    AnalysisRequest:
      type: object
      properties:
        runTimeParameterValues:
          type: object
          additionalProperties: true
          description: Runtime parameter values keyed by parameter variable name
        runTimeParameterFiles:
          type: object
          additionalProperties:
            type: string
          description: CSV file IDs keyed by parameter variable name
        forceReAnalyze:
          type: boolean
          default: false
          description: Force a new analysis even if parameters haven't changed
    ProtocolResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Protocol'
        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
    AnalysisSummaryResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AnalysisSummary'
    ProtocolAnalysis:
      type: object
      description: The result of analyzing a protocol
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - pending
          - completed
        result:
          type: string
          enum:
          - ok
          - not-ok
          - parameter-value-required
          nullable: true
        pipettes:
          type: array
          items:
            type: object
        labware:
          type: array
          items:
            type: object
        modules:
          type: array
          items:
            type: object
        commands:
          type: array
          items:
            type: object
        errors:
          type: array
          items:
            type: object
        warnings:
          type: array
          items:
            type: object
        runTimeParameters:
          type: array
          items:
            type: object
    AnalysisListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProtocolAnalysis'
    AnalysisSummary:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - pending
          - completed
    ProtocolMetadata:
      type: object
      description: Metadata extracted from the protocol
      properties:
        protocolName:
          type: string
        author:
          type: string
        description:
          type: string
        created:
          type: number
        lastModified:
          type: number
        category:
          type: string
        subcategory:
          type: string
        tags:
          type: array
          items:
            type: string
    ProtocolListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Protocol'
        meta:
          $ref: '#/components/schemas/MultiBodyMeta'
    ErrorResponse:
      type: object
      description: Error response from the API
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
    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: '*'