API docs by Redocly

Opentrons HTTP API Spec (4)

Download OpenAPI specification:Download

This OpenAPI spec describes the HTTP API for Opentrons robots. It may be retrieved from a robot on port 31950 at /openapi. Some schemas used in requests and responses use the x-patternProperties key to mean the JSON Schema patternProperties behavior.

v1

Query the current network connectivity state

Gets information about the robot's network interfaces including their connectivity, their addresses, and their networking info

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "status": "full",
  • "interfaces": {
    }
}

Scan for visible Wi-Fi networks

Returns the list of the visible wifi networks along with some data about their security and strength.

query Parameters
rescan
boolean (Rescan)
Default: false

If true, forces a rescan for beaconing Wi-Fi networks. This is an expensive operation that can take ~10 seconds, so only do it based on user needs like clicking a "scan network" button, not just to poll. If false, returns the cached Wi-Fi networks, letting the system decide when to do a rescan.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Configure the robot's Wi-Fi

Configures the wireless network interface to connect to a network

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
ssid
required
string (Ssid)

The SSID to connect to. If this isn't an SSID that is being broadcast by a network, you should also set hidden to true.

hidden
boolean (Hidden)
Default: false

true if the network is hidden (not broadcasting an SSID). false (default if key is not present) otherwise.

securityType
string (NetworkingSecurityType)
Enum: "wpa-eap" "wpa-psk" "none" "unsupported"

Top-level type of network security

psk
string <password> (Psk)

If this is a PSK-secured network (securityType is "wpa-psk"), the PSK

object (Eapconfig)

All options required to configure EAP access to the Wi-Fi. All options should match one of the cases described in /wifi/eap-options; for instance, configuring for peap/mschapv2 should have "peap/mschapv2" as the eapType; it should have "identity" and "password" props, both of which are identified as mandatory in /wifi/eap-options; and it may also have "anonymousIdentity" and "caCert" properties, both of which are identified as present but not required.

Responses

Request samples

Content type
application/json
{
  • "ssid": "linksys"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "ssid": "string"
}

Get Wi-Fi keys

Get a list of key files known to the system

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

Add a Wi-Fi key

Send a new key file to the robot

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: multipart/form-data
required
key
required
string <binary> (Key)

Responses

Response samples

Content type
application/json
{
  • "uri": "string",
  • "id": "string",
  • "name": "string",
  • "message": "string"
}

Delete a Wi-Fi key

Delete a key file from the robot

path Parameters
key_uuid
required
string (Key Uuid)

The ID of key to delete, as determined by a previous call to GET /wifi/keys

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Get EAP options

Get the supported EAP variants and their configuration parameters

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "options": [
    ]
}

Disconnect the robot from Wi-Fi

Deactivates the Wi-Fi connection and removes it from known connections

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
ssid
required
string (Ssid)

The network's SSID

Responses

Request samples

Content type
application/json
{
  • "ssid": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Blink the lights

Blink the gantry lights so you can pick it out of a crowd

query Parameters
seconds
required
integer (Seconds)

Time to blink the lights for

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Get robot positions Deprecated

Get a list of useful positions.

Deprecated: This data only makes sense for OT-2 robots, not Flex robots. There is currently no public way to get these positions for Flex robots.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "positions": {
    }
}

Move the robot Deprecated

Move the robot's gantry to a position (usually to a position retrieved from GET /robot/positions).

Deprecated: Run a moveToCoordinates command in a maintenance run instead. See the /maintenance_runs endpoints.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
target
required
string (MotionTarget)
Enum: "pipette" "mount"

What should be moved. If mount, move the nominal position of the mount; if pipette, move the nozzle of the pipette

point
required
Array of numbers (Point) = 3 items

A point in deck coordinates (x, y, z)

mount
required
string (Mount)
Enum: "right" "left"

Which mount to move

model
string (Model)

A pipette model that matches the pipette attached to the specified mount. Required if target is pipette

Responses

Request samples

Content type
application/json
{
  • "target": "mount",
  • "point": [
    ],
  • "mount": "left"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Home the robot

Home the robot.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
target
required
string (HomeTarget)
Enum: "pipette" "robot"

What to home. Robot means to home all axes; pipette, only that pipette's carriage and pipette axes

mount
string (Mount)
Enum: "right" "left"

Which mount to home, if target is pipette (required in that case)

Responses

Request samples

Content type
application/json
{
  • "target": "robot"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Get whether the lights are on

Get the current status of the robot's rail lights

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "on": true
}

Turn the lights on or off

Turn the rail lights on or off

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
on
required
boolean (On)

The light state

Responses

Request samples

Content type
application/json
{
  • "on": true
}

Response samples

Content type
application/json
{
  • "on": true
}

Get settings

Get a list of available advanced settings (feature flags) and their values

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "settings": [
    ],
  • "links": {
    }
}

Change a setting

Change an advanced setting (feature flag)

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
id
required
string (Id)

The ID of the setting to change (something returned by GET /settings)

value
boolean (Value)

The new value to set. If null, reset to default

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "value": true
}

Response samples

Content type
application/json
{
  • "settings": [
    ],
  • "links": {
    }
}

Set the local log level

Set the minimum level of logs saved locally

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
log_level
string (LogLevels)
Enum: "debug" "info" "warning" "error"

The value to set (conforming to Python log levels)

Responses

Request samples

Content type
application/json
{
  • "log_level": "debug"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Set the upstream log level Deprecated

Set the minimum level of logs sent upstream via syslog-ng to Opentrons. Removed in robot software v7.2.0.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
log_level
string (LogLevels)
Enum: "debug" "info" "warning" "error"

The value to set (conforming to Python log levels)

Responses

Request samples

Content type
application/json
{
  • "log_level": "debug"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errorCode": "string"
}

Get the things that can be reset

Get the robot settings and data that can be reset through POST /settings/reset.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "options": [
    ]
}

Reset specific settings or data

Perform a reset of the requested robot settings or data.

The valid properties are given by GET /settings/reset/options.

You should always restart the robot after using this endpoint to reset something.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
property name*
additional property
boolean

Responses

Request samples

Content type
application/json
{
  • "property1": true,
  • "property2": true
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Get Robot Settings

Get the current robot config

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{ }

Get Pipette Settings

List all settings for all known pipettes by id. Only available on OT-2.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Get Pipette Setting

Get the settings of a specific pipette by ID. Only available on OT-2.

path Parameters
pipette_id
required
string (Pipette Id)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "info": {
    },
  • "fields": {
    }
}

Patch Pipette Setting

Change the settings of a specific pipette. Only available on OT-2.

path Parameters
pipette_id
required
string (Pipette Id)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
object (Fields)

Responses

Request samples

Content type
application/json
{
  • "fields": {
    }
}

Response samples

Content type
application/json
{
  • "info": {
    },
  • "fields": {
    }
}

Get Calibration Status

Get the calibration status

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "deckCalibration": {
    },
  • "instrumentCalibration": {
    }
}

Execute a command on a specific module Deprecated

Command a module to take an action. Valid actions depend on the specific module attached, which is the model value from GET /modules/{serial}/data or GET /modules.

Deprecated: Removed with Opentrons-Version: 3. Use POST /commands instead.

path Parameters
serial
required
string (Serial)

Serial number of the module

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
command_type
required
string (Command Type)

The name of the module function to call

args
Array of any (Args)

The ordered args list for the call

Responses

Request samples

Content type
application/json
{
  • "command_type": "set_Temperature",
  • "args": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Initiate a firmware update on a specific module

Command robot to flash its bundled firmware file for this module's type to this specific module

path Parameters
serial
required
string (Serial)

Serial number of the module

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Get the pipettes currently attached

This endpoint lists properties of the pipettes currently attached to the robot like name, model, and mount.

If you're controlling a Flex, and not an OT-2, you might prefer the GET /instruments endpoint instead.

query Parameters
refresh
boolean (Refresh)
Default: false

If false, query a cached value. If true, actively scan for attached pipettes.

Warning: Actively scanning disables the pipette motors and should only be done when no protocol is running and you know it won't cause a problem.

Warning: Actively scanning is only valid on OT-2s. On Flex robots, it's unnecessary, and the behavior is currently undefined.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "left": {
    },
  • "right": {
    }
}

Get Engaged Motors

Query which motors are engaged and holding

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "x": {
    },
  • "y": {
    },
  • "z_l": {
    },
  • "z_r": {
    },
  • "p_l": {
    },
  • "p_r": {
    },
  • "q": {
    },
  • "g": {
    }
}

Post Disengage Motors

Disengage a motor or set of motors

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
axes
required
Array of strings (MotorName)
Items Enum: "x" "y" "z_l" "z_r" "z_g" "p_l" "p_r" "q" "g" "z" "a" "b" "c"

Responses

Request samples

Content type
application/json
{
  • "axes": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Post Picture Capture

Capture an image from the OT-2's on-board camera and return it

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
null

Get troubleshooting logs

Get the robot's troubleshooting logs.

If you want the list of steps executed in a protocol, like "aspirated 5 µL from well A1...", you probably want the protocol analysis commands (GET /protocols/{id}/analyses/{id}) or run commands (GET /runs/{id}/commands) instead.

path Parameters
log_identifier
required
string (LogIdentifier)
Enum: "api.log" "serial.log" "server.log" "combined_api_server.log" "touchscreen.log"

Identifier of the log

query Parameters
format
string (Log format type)
Default: "text"
Enum: "text" "json"

Format to use for log records

records
integer (Number of records to retrieve) ( 0 .. 100000 ]
Default: 50000

Responses

Response samples

Content type
application/json
null

Get server health

Get information about the health of the robot server.

Use the health endpoint to check that the robot server is running and ready to operate. A 200 OK response means the server is running. The response includes information about the software and system.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "name": "Otie",
  • "robot_model": "OT-2 Standard",
  • "api_version": "3.15.2",
  • "fw_version": "v2.15.0",
  • "board_revision": "2.1",
  • "logs": [
    ],
  • "system_version": "1.2.1",
  • "maximum_protocol_api_version": [
    ],
  • "minimum_protocol_api_version": [
    ],
  • "robot_serial": "OT2CEP20190604A02",
  • "links": {
    }
}

Networking

Query the current network connectivity state

Gets information about the robot's network interfaces including their connectivity, their addresses, and their networking info

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "status": "full",
  • "interfaces": {
    }
}

Scan for visible Wi-Fi networks

Returns the list of the visible wifi networks along with some data about their security and strength.

query Parameters
rescan
boolean (Rescan)
Default: false

If true, forces a rescan for beaconing Wi-Fi networks. This is an expensive operation that can take ~10 seconds, so only do it based on user needs like clicking a "scan network" button, not just to poll. If false, returns the cached Wi-Fi networks, letting the system decide when to do a rescan.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Configure the robot's Wi-Fi

Configures the wireless network interface to connect to a network

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
ssid
required
string (Ssid)

The SSID to connect to. If this isn't an SSID that is being broadcast by a network, you should also set hidden to true.

hidden
boolean (Hidden)
Default: false

true if the network is hidden (not broadcasting an SSID). false (default if key is not present) otherwise.

securityType
string (NetworkingSecurityType)
Enum: "wpa-eap" "wpa-psk" "none" "unsupported"

Top-level type of network security

psk
string <password> (Psk)

If this is a PSK-secured network (securityType is "wpa-psk"), the PSK

object (Eapconfig)

All options required to configure EAP access to the Wi-Fi. All options should match one of the cases described in /wifi/eap-options; for instance, configuring for peap/mschapv2 should have "peap/mschapv2" as the eapType; it should have "identity" and "password" props, both of which are identified as mandatory in /wifi/eap-options; and it may also have "anonymousIdentity" and "caCert" properties, both of which are identified as present but not required.

Responses

Request samples

Content type
application/json
{
  • "ssid": "linksys"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "ssid": "string"
}

Get Wi-Fi keys

Get a list of key files known to the system

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

Add a Wi-Fi key

Send a new key file to the robot

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: multipart/form-data
required
key
required
string <binary> (Key)

Responses

Response samples

Content type
application/json
{
  • "uri": "string",
  • "id": "string",
  • "name": "string",
  • "message": "string"
}

Delete a Wi-Fi key

Delete a key file from the robot

path Parameters
key_uuid
required
string (Key Uuid)

The ID of key to delete, as determined by a previous call to GET /wifi/keys

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Get EAP options

Get the supported EAP variants and their configuration parameters

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "options": [
    ]
}

Disconnect the robot from Wi-Fi

Deactivates the Wi-Fi connection and removes it from known connections

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
ssid
required
string (Ssid)

The network's SSID

Responses

Request samples

Content type
application/json
{
  • "ssid": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Control

Blink the lights

Blink the gantry lights so you can pick it out of a crowd

query Parameters
seconds
required
integer (Seconds)

Time to blink the lights for

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Get robot positions Deprecated

Get a list of useful positions.

Deprecated: This data only makes sense for OT-2 robots, not Flex robots. There is currently no public way to get these positions for Flex robots.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "positions": {
    }
}

Move the robot Deprecated

Move the robot's gantry to a position (usually to a position retrieved from GET /robot/positions).

Deprecated: Run a moveToCoordinates command in a maintenance run instead. See the /maintenance_runs endpoints.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
target
required
string (MotionTarget)
Enum: "pipette" "mount"

What should be moved. If mount, move the nominal position of the mount; if pipette, move the nozzle of the pipette

point
required
Array of numbers (Point) = 3 items

A point in deck coordinates (x, y, z)

mount
required
string (Mount)
Enum: "right" "left"

Which mount to move

model
string (Model)

A pipette model that matches the pipette attached to the specified mount. Required if target is pipette

Responses

Request samples

Content type
application/json
{
  • "target": "mount",
  • "point": [
    ],
  • "mount": "left"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Home the robot

Home the robot.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
target
required
string (HomeTarget)
Enum: "pipette" "robot"

What to home. Robot means to home all axes; pipette, only that pipette's carriage and pipette axes

mount
string (Mount)
Enum: "right" "left"

Which mount to home, if target is pipette (required in that case)

Responses

Request samples

Content type
application/json
{
  • "target": "robot"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Get whether the lights are on

Get the current status of the robot's rail lights

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "on": true
}

Turn the lights on or off

Turn the rail lights on or off

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
on
required
boolean (On)

The light state

Responses

Request samples

Content type
application/json
{
  • "on": true
}

Response samples

Content type
application/json
{
  • "on": true
}

Settings

Get settings

Get a list of available advanced settings (feature flags) and their values

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "settings": [
    ],
  • "links": {
    }
}

Change a setting

Change an advanced setting (feature flag)

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
id
required
string (Id)

The ID of the setting to change (something returned by GET /settings)

value
boolean (Value)

The new value to set. If null, reset to default

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "value": true
}

Response samples

Content type
application/json
{
  • "settings": [
    ],
  • "links": {
    }
}

Set the local log level

Set the minimum level of logs saved locally

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
log_level
string (LogLevels)
Enum: "debug" "info" "warning" "error"

The value to set (conforming to Python log levels)

Responses

Request samples

Content type
application/json
{
  • "log_level": "debug"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Set the upstream log level Deprecated

Set the minimum level of logs sent upstream via syslog-ng to Opentrons. Removed in robot software v7.2.0.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
log_level
string (LogLevels)
Enum: "debug" "info" "warning" "error"

The value to set (conforming to Python log levels)

Responses

Request samples

Content type
application/json
{
  • "log_level": "debug"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "errorCode": "string"
}

Get the things that can be reset

Get the robot settings and data that can be reset through POST /settings/reset.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "options": [
    ]
}

Reset specific settings or data

Perform a reset of the requested robot settings or data.

The valid properties are given by GET /settings/reset/options.

You should always restart the robot after using this endpoint to reset something.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
property name*
additional property
boolean

Responses

Request samples

Content type
application/json
{
  • "property1": true,
  • "property2": true
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Get Robot Settings

Get the current robot config

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{ }

Get Pipette Settings

List all settings for all known pipettes by id. Only available on OT-2.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Get Pipette Setting

Get the settings of a specific pipette by ID. Only available on OT-2.

path Parameters
pipette_id
required
string (Pipette Id)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "info": {
    },
  • "fields": {
    }
}

Patch Pipette Setting

Change the settings of a specific pipette. Only available on OT-2.

path Parameters
pipette_id
required
string (Pipette Id)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
object (Fields)

Responses

Request samples

Content type
application/json
{
  • "fields": {
    }
}

Response samples

Content type
application/json
{
  • "info": {
    },
  • "fields": {
    }
}

Deck Calibration

Get Calibration Status

Get the calibration status

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "deckCalibration": {
    },
  • "instrumentCalibration": {
    }
}

Modules

Execute a command on a specific module Deprecated

Command a module to take an action. Valid actions depend on the specific module attached, which is the model value from GET /modules/{serial}/data or GET /modules.

Deprecated: Removed with Opentrons-Version: 3. Use POST /commands instead.

path Parameters
serial
required
string (Serial)

Serial number of the module

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
command_type
required
string (Command Type)

The name of the module function to call

args
Array of any (Args)

The ordered args list for the call

Responses

Request samples

Content type
application/json
{
  • "command_type": "set_Temperature",
  • "args": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Initiate a firmware update on a specific module

Command robot to flash its bundled firmware file for this module's type to this specific module

path Parameters
serial
required
string (Serial)

Serial number of the module

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Pipettes

Get the pipettes currently attached

This endpoint lists properties of the pipettes currently attached to the robot like name, model, and mount.

If you're controlling a Flex, and not an OT-2, you might prefer the GET /instruments endpoint instead.

query Parameters
refresh
boolean (Refresh)
Default: false

If false, query a cached value. If true, actively scan for attached pipettes.

Warning: Actively scanning disables the pipette motors and should only be done when no protocol is running and you know it won't cause a problem.

Warning: Actively scanning is only valid on OT-2s. On Flex robots, it's unnecessary, and the behavior is currently undefined.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "left": {
    },
  • "right": {
    }
}

Motors

Get Engaged Motors

Query which motors are engaged and holding

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "x": {
    },
  • "y": {
    },
  • "z_l": {
    },
  • "z_r": {
    },
  • "p_l": {
    },
  • "p_r": {
    },
  • "q": {
    },
  • "g": {
    }
}

Post Disengage Motors

Disengage a motor or set of motors

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
axes
required
Array of strings (MotorName)
Items Enum: "x" "y" "z_l" "z_r" "z_g" "p_l" "p_r" "q" "g" "z" "a" "b" "c"

Responses

Request samples

Content type
application/json
{
  • "axes": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Camera

Post Picture Capture

Capture an image from the OT-2's on-board camera and return it

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
null

Logs

Get troubleshooting logs

Get the robot's troubleshooting logs.

If you want the list of steps executed in a protocol, like "aspirated 5 µL from well A1...", you probably want the protocol analysis commands (GET /protocols/{id}/analyses/{id}) or run commands (GET /runs/{id}/commands) instead.

path Parameters
log_identifier
required
string (LogIdentifier)
Enum: "api.log" "serial.log" "server.log" "combined_api_server.log" "touchscreen.log"

Identifier of the log

query Parameters
format
string (Log format type)
Default: "text"
Enum: "text" "json"

Format to use for log records

records
integer (Number of records to retrieve) ( 0 .. 100000 ]
Default: 50000

Responses

Response samples

Content type
application/json
null

Health

Get server health

Get information about the health of the robot server.

Use the health endpoint to check that the robot server is running and ready to operate. A 200 OK response means the server is running. The response includes information about the software and system.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "name": "Otie",
  • "robot_model": "OT-2 Standard",
  • "api_version": "3.15.2",
  • "fw_version": "v2.15.0",
  • "board_revision": "2.1",
  • "logs": [
    ],
  • "system_version": "1.2.1",
  • "maximum_protocol_api_version": [
    ],
  • "minimum_protocol_api_version": [
    ],
  • "robot_serial": "OT2CEP20190604A02",
  • "links": {
    }
}

Run Management

Get all runs

Get a list of all active and inactive runs, in order from oldest to newest.

query Parameters
pageLength
integer (Pagelength)

The maximum number of runs to return. If this is less than the total number of runs, the most-recently created runs will be returned. If this is omitted or null, all runs will be returned.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Create a run

Create a new run to track robot interaction.

When too many runs already exist, old ones will be automatically deleted to make room for the new one.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
object (Data)

the document’s 'primary data'

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a run

Get a specific run by its unique identifier.

path Parameters
runId
required
string (Runid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a run

Delete a specific run by its unique identifier.

path Parameters
runId
required
string (Runid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{ }

Update a run

Update a specific run, returning the updated resource.

path Parameters
runId
required
string (Runid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
required
object (Data)

the document’s 'primary data'

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a list of all protocol commands in the run

Get a list of all commands in the run and their statuses.

The commands are returned in order from oldest to newest.

This endpoint returns command summaries. Use GET /runs/{runId}/commands/{commandId} to get all information available for a given command.

path Parameters
runId
required
string (Runid)
query Parameters
cursor
integer (Cursor)

The starting index of the desired first command in the list. If unspecified, a cursor will be selected automatically based on the currently running or most recently executed command.

pageLength
integer (Pagelength)
Default: 20

The maximum number of commands in the list to return.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Enqueue a command

Add a single command to the run. You can add commands to a run for two reasons:

  • Setup commands (data.source == "setup")
  • Protocol commands (data.source == "protocol")
  • Fixit commands (data.source == "fixit")

Setup commands may be enqueued before the run has been started. You could use setup commands to prepare a module or run labware calibration procedures.

Protocol commands may be enqueued anytime using this endpoint. You can create a protocol purely over HTTP using protocol commands. If you are running a protocol from a file(s), then you will likely not need to enqueue protocol commands using this endpoint.

Fixit commands may be enqueued while the run is awaiting-recovery state. These commands are intended to fix a failed command. They will be executed right after the failed command and only if the run is in a awaiting-recovery state.

Once enqueued, setup commands will execute immediately with priority, while protocol commands will wait until a play action is issued. A play action may be issued while setup commands are still queued, in which case all setup commands will finish executing before the run moves on to protocol commands.

If you are running a protocol file(s), use caution with this endpoint, as added commands may interfere with commands added by the protocol

path Parameters
runId
required
string (Runid)
query Parameters
waitUntilComplete
boolean (Waituntilcomplete)
Default: false

If false, return immediately, while the new command is still queued. If true, only return once the new command succeeds or fails, or when the timeout is reached. See the timeout query parameter.

timeout
integer (Timeout) > 0

If waitUntilComplete is true, the maximum time in milliseconds to wait before returning. The default is infinite.

The timer starts as soon as you enqueue the new command with this request, not when the new command starts running. So if there are other commands in the queue before the new one, they will also count towards the timeout.

If the timeout elapses before the command succeeds or fails, the command will be returned with its current status.

Compatibility note: on robot software v6.2.0 and older, the default was 30 seconds, not infinite.

failedCommandId
string (Failedcommandid)

FIXIT command use only. Reference of the failed command id we are trying to fix.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
required
any (Data)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get all commands of a completed run as a list of pre-serialized commands

Get all commands of a completed run as a list of pre-serialized commands.Warning: This endpoint is experimental. We may change or remove it without warning.

The commands list will only be available after a run has completed (whether successful, failed or stopped) and its data has been committed to the database. If a request is received before the run is completed, it will return a 503 Unavailable error. This is a faster alternative to fetching the full commands list using GET /runs/{runId}/commands. For large protocols (10k+ commands), the above endpoint can take minutes to respond, whereas this one should only take a few seconds.

path Parameters
runId
required
string (Runid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get full details about a specific command in the run

Get a command along with any associated payload, result, and execution information.

path Parameters
runId
required
string (Runid)
commandId
required
string (Commandid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Issue a control action to the run

Provide an action in order to control execution of the run.

path Parameters
runId
required
string (Runid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
required
object (Data)

the document’s 'primary data'

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Add a labware offset to a run

Add a labware offset to an existing run, returning the created offset.

There is no matching GET /runs/{runId}/labware_offsets endpoint. To read the list of labware offsets currently on the run, see the run's labwareOffsets field.

path Parameters
runId
required
string (Runid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
required
object (Data)

the document’s 'primary data'

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Add a labware definition to a run

Add a labware definition to a run, returning the added definition's URI.

path Parameters
runId
required
string (Runid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
required
object (Data)

the document’s 'primary data'

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get the definitions of a run's loaded labware

Get the definitions of all the labware that the given run has loaded so far.

When the run is first created, this list will be empty. As it executes and goes through loadLabware commands, those commands' result.definitions will be added to this list. Repeated definitions will be deduplicated.

path Parameters
runId
required
string (Runid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Maintenance Run Management

Create a maintenance run

Create a new maintenance run to track robot interaction.

If a maintenance run already exists, it will be cleared and a new one will be created.

Will raise an error if a protocol run exists and is not idle.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
object (Data)

the document’s 'primary data'

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get the current maintenance run

Get the currently active maintenance run, if any

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "links": {
    }
}

Get a maintenance run

Get a specific run by its unique identifier.

path Parameters
runId
required
string (Runid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a run

Delete a specific run by its unique identifier.

path Parameters
runId
required
string (Runid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{ }

Get a list of all commands in the run

Get a list of all commands in the run and their statuses. This endpoint returns command summaries. Use GET /maintenance_runs/{runId}/commands/{commandId} to get all information available for a given command.

path Parameters
runId
required
string (Runid)
query Parameters
cursor
integer (Cursor)

The starting index of the desired first command in the list. If unspecified, a cursor will be selected automatically based on the currently running or most recently executed command.

pageLength
integer (Pagelength)
Default: 20

The maximum number of commands in the list to return.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Enqueue a command

Add a single command to the maintenance run.

These commands will execute immediately and in the order they are enqueued. The execution of these commands cannot be paused, but a maintenance run can be deleted at any point, as long as there are no commands running.

path Parameters
runId
required
string (Runid)
query Parameters
waitUntilComplete
boolean (Waituntilcomplete)
Default: false

If false, return immediately, while the new command is still queued. If true, only return once the new command succeeds or fails, or when the timeout is reached. See the timeout query parameter.

timeout
integer (Timeout) > 0

If waitUntilComplete is true, the maximum time in milliseconds to wait before returning. The default is infinite.

The timer starts as soon as you enqueue the new command with this request, not when the new command starts running. So if there are other commands in the queue before the new one, they will also count towards the timeout.

If the timeout elapses before the command succeeds or fails, the command will be returned with its current status.

Compatibility note: on robot software v6.2.0 and older, the default was 30 seconds, not infinite.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
required
any (Data)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get full details about a specific command in the run

Get a command along with any associated payload, result, and execution information.

path Parameters
runId
required
string (Runid)
commandId
required
string (Commandid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Add a labware offset to a maintenance run

Add a labware offset to an existing run, returning the created offset.

There is no matching GET /maintenance_runs/{runId}/labware_offsets endpoint. To read the list of labware offsets currently on the run, see the run's labwareOffsets field.

path Parameters
runId
required
string (Runid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
required
object (Data)

the document’s 'primary data'

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Add a labware definition to a maintenance run

Add a labware definition to a run, returning the added definition's URI.

path Parameters
runId
required
string (Runid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
required
object (Data)

the document’s 'primary data'

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Protocol Management

Get uploaded protocols

Return all stored protocols, in order from first-uploaded to last-uploaded.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Upload a protocol

Upload a protocol to your device. You may include the following files:

  • A single Python protocol file and 0 or more custom labware JSON files
  • A single JSON protocol file (any additional labware files will be ignored)

When too many protocols already exist, old ones will be automatically deleted to make room for the new one. A protocol will never be automatically deleted if there's a run referring to it, though. (See the /runs/ endpoints.)

If you upload the exact same set of files multiple times, the first protocol resource will be returned instead of creating duplicate ones.

When a new protocol resource is created, an analysis is started for it. A new analysis is also started if the same protocol file is uploaded but with a different set of run-time parameter values than the most recent request. See the /protocols/{id}/analyses/ endpoints for more details.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: multipart/form-data
required
files
required
Array of strings <binary> (Files) [ items <binary > ]
key
string (Key)

An arbitrary client-defined string to attach to the new protocol resource. This should be no longer than ~100 characters or so. It's intended to store something like a UUID, to help clients that store protocols locally keep track of which local files correspond to which protocol resources on the robot.

runTimeParameterValues
string (Runtimeparametervalues)

Key-value pairs of run-time parameters defined in a protocol. Note that this is expected to be a string holding a JSON object. Also, if this data is included in the request, the server will always trigger an analysis (for now).

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

[Internal] Get uploaded protocol IDs

Get the IDs of all protocols stored on the server.

Warning: This is an experimental endpoint and is only meant for internal use by Opentrons. We might remove it or change its behavior without warning.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get an uploaded protocol

Get an uploaded protocol by ID.

Args: protocolId: Protocol identifier to fetch, pulled from URL. protocol_store: In-memory database of protocol resources. analysis_store: In-memory database of protocol analyses.

path Parameters
protocolId
required
string (Protocolid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "links": {
    }
}

Delete an uploaded protocol

Delete an uploaded protocol by ID.

Arguments: protocolId: Protocol identifier to delete, pulled from URL. protocol_store: In-memory database of protocol resources.

path Parameters
protocolId
required
string (Protocolid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{ }

Get a protocol's analyses

Get a protocol's full analyses list.

Analyses are returned in order from least-recently started to most-recently started.

Arguments: protocolId: Protocol identifier to delete, pulled from URL. protocol_store: Database of protocol resources. analysis_store: Database of analysis resources.

path Parameters
protocolId
required
string (Protocolid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Analyze the protocol

Generate an analysis for the protocol, based on last analysis and current request data.

path Parameters
protocolId
required
string (Protocolid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
object (Data)

the document’s 'primary data'

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get one of a protocol's analyses

Get a protocol analysis by analysis ID.

Arguments: protocolId: The ID of the protocol, pulled from the URL. analysisId: The ID of the analysis, pulled from the URL. protocol_store: Protocol resource storage. analysis_store: Analysis resource storage.

path Parameters
protocolId
required
string (Protocolid)
analysisId
required
string (Analysisid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

[Experimental] Get one of a protocol's analyses as a raw document

Warning: This endpoint is experimental. We may change or remove it without warning.

This is a faster alternative to GET /protocols/{protocolId}/analyses and GET /protocols/{protocolId}/analyses/{analysisId}. For large analyses (10k+ commands), those other endpoints can take minutes to respond, whereas this one should only take a few seconds.

For a completed analysis, this returns the same JSON data as the GET /protocols/:id/analyses/:id endpoint, except that it's not wrapped in a top-level data object.

For a pending analysis, this returns a 404 response, unlike those other endpoints, which return a 200 response with "status": "pending".

path Parameters
protocolId
required
string (Protocolid)
analysisId
required
string (Analysisid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
null

Simple Commands

Get a list of queued and executed commands

Get a list of commands that have been run on the device since boot. Only returns command run via the /commands endpoint.

query Parameters
cursor
integer (Cursor)

The starting index of the desired first command in the list. If unspecified, a cursor will be selected automatically based on the currently running or most recently executed command.

pageLength
integer (Pagelength)
Default: 20

The maximum number of commands in the list to return.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Add a command to be executed

Run a single command on the robot. This endpoint is meant for simple, stateless control of the robot. For complex control, create a run with POST /runs and issue commands on that run.

query Parameters
waitUntilComplete
boolean (Waituntilcomplete)
Default: false

If false, return immediately, while the new command is still queued. If true, only return once the new command succeeds or fails, or when the timeout is reached. See the timeout query parameter.

timeout
integer (Timeout) > 0

If waitUntilComplete is true, the maximum time in milliseconds to wait before returning. The default is infinite.

The timer starts as soon as you enqueue the new command with this request, not when the new command starts running. So if there are other commands in the queue before the new one, they will also count towards the timeout.

If the timeout elapses before the command succeeds or fails, the command will be returned with its current status.

Compatibility note: on robot software v6.2.0 and older, the default was 30 seconds, not infinite.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
required
any (Data)

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a single stateless command.

Get a single stateless command that has been queued or executed. Only returns command run via the /commands endpoint.

path Parameters
commandId
required
string (Commandid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Flex Deck Configuration

Get the Flex deck configuration

Get the robot's current deck configuration. See PUT /deck_configuration for background information.

Warning: The behavior of this endpoint is currently only defined for Flex robots, not OT-2 robots.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Set the Flex deck configuration

Inform the robot how its deck is physically set up.

When you use the /runs and /maintenance_runs endpoints to command the robot to move, the robot will automatically dodge the obstacles that you declare here.

If a run command tries to do something that inherently conflicts with this deck configuration, such as loading a labware into a staging area slot that this deck configuration doesn't provide, the run command will fail with an error.

After you set the deck configuration, it will persist, even across reboots, until you set it to something else.

Warning: Currently, you can call this endpoint at any time, even while there is an active run. However, the robot can't adapt to deck configuration changes in the middle of a run. The robot will effectively take a snapshot of the deck configuration when the run is first played. In the future, this endpoint may error if you try to call it in the middle of an active run, so don't rely on being able to do that.

Warning: Only use this on Flex robots, never OT-2 robots. The behavior on OT-2 robots is currently undefined and it may interfere with protocol execution.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
required
object (Data)

the document’s 'primary data'

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
Example
{
  • "data": {
    }
}

Attached Modules

Get attached modules.

Get a list of all modules currently attached to the robot.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Attached Instruments

Get attached instruments

Get a list of all instruments (pipettes & gripper) currently attached to the robot.

Warning: The behavior of this endpoint is currently only defined for Flex robots. For OT-2 robots, use /pipettes instead.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

OT-2 Calibration Sessions

Get all OT-2 calibration sessions Deprecated

Warning: These /sessions/ endpoints are tightly coupled to the Opentrons App and are not intended for general public use.

query Parameters
session_type
string (SessionType)
Enum: "calibrationCheck" "tipLengthCalibration" "deckCalibration" "pipetteOffsetCalibration"

Will limit the results to only this session type

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Create an OT-2 calibration session Deprecated

Create a session to perform a calibration procedure on an OT-2.

Warning: These /sessions/ endpoints are tightly coupled to the Opentrons App and are not intended for general public use.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
required
CalibrationCheckCreateAttributes (object) or TipLengthCalibrationCreateAttributes (object) or DeckCalibrationCreateAttributes (object) or PipetteOffsetCalibrationCreateAttributes (object) (Data)

the document’s 'primary data'

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "links": {
    }
}

Get an OT-2 calibration session Deprecated

Warning: These /sessions/ endpoints are tightly coupled to the Opentrons App and are not intended for general public use.

path Parameters
sessionId
required
string (Sessionid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "links": {
    }
}

Delete an OT-2 calibration session Deprecated

Warning: These /sessions/ endpoints are tightly coupled to the Opentrons App and are not intended for general public use.

path Parameters
sessionId
required
string (Sessionid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "links": {
    }
}

Execute an OT-2 calibration command Deprecated

Warning: These /sessions/ endpoints are tightly coupled to the Opentrons App and are not intended for general public use.

path Parameters
sessionId
required
string (Sessionid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
required
SessionCommandRequest[Literal[<ProtocolCommand.start_run: 'protocol.startRun'>, <ProtocolCommand.start_simulate: 'protocol.startSimulate'>, <ProtocolCommand.cancel: 'protocol.cancel'>, <ProtocolCommand.pause: 'protocol.pause'>, <ProtocolCommand.resume: 'protocol.resume'>, <CalibrationCommand.move_to_tip_rack: 'calibration.moveToTipRack'>, <CalibrationCommand.move_to_point_one: 'calibration.moveToPointOne'>, <CalibrationCommand.move_to_deck: 'calibration.moveToDeck'>, <CalibrationCommand.move_to_reference_point: 'calibration.moveToReferencePoint'>, <CalibrationCommand.pick_up_tip: 'calibration.pickUpTip'>, <CalibrationCommand.confirm_tip_attached: 'calibration.confirmTip'>, <CalibrationCommand.invalidate_tip: 'calibration.invalidateTip'>, <CalibrationCommand.save_offset: 'calibration.saveOffset'>, <CalibrationCommand.exit: 'calibration.exitSession'>, <CalibrationCommand.invalidate_last_action: 'calibration.invalidateLastAction'>, <DeckCalibrationCommand.move_to_point_two: 'calibration.deck.moveToPointTwo'>, <DeckCalibrationCommand.move_to_point_three: 'calibration.deck.moveToPointThree'>, <CheckCalibrationCommand.compare_point: 'calibration.check.comparePoint'>, <CheckCalibrationCommand.switch_pipette: 'calibration.check.switchPipette'>, <CheckCalibrationCommand.return_tip: 'calibration.check.returnTip'>, <CheckCalibrationCommand.transition: 'calibration.check.transition'>], EmptyModel, EmptyModel] (object) or SessionCommandRequest[Literal[<EquipmentCommand.load_labware: 'equipment.loadLabware'>], LoadLabwareCreate, LoadLabwareResult] (object) or SessionCommandRequest[Literal[<EquipmentCommand.load_pipette: 'equipment.loadPipette'>], LoadPipetteCreate, LoadPipetteResult] (object) or SessionCommandRequest[Literal[<PipetteCommand.aspirate: 'pipette.aspirate'>], AspirateCreate, AspirateResult] (object) or SessionCommandRequest[Literal[<PipetteCommand.dispense: 'pipette.dispense'>], DispenseCreate, DispenseResult] (object) or SessionCommandRequest[Literal[<PipetteCommand.pick_up_tip: 'pipette.pickUpTip'>], PickUpTipCreate, PickUpTipResult] (object) or SessionCommandRequest[Literal[<PipetteCommand.drop_tip: 'pipette.dropTip'>], DropTipCreate, DropTipResult] (object) or SessionCommandRequest[Literal[<CalibrationCommand.jog: 'calibration.jog'>], JogPosition, EmptyModel] (object) or SessionCommandRequest[Literal[<CalibrationCommand.set_has_calibration_block: 'calibration.setHasCalibrationBlock'>], SetHasCalibrationBlockRequestData, EmptyModel] (object) or SessionCommandRequest[Literal[<CalibrationCommand.load_labware: 'calibration.loadLabware'>], LoadLabwareByDefinitionRequestData, EmptyModel] (object) (Data)

the document’s 'primary data'

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "links": {
    }
}

Labware Calibration Management

Fetch all saved labware calibrations from the robot Deprecated

This endpoint has been removed. Use the /runs endpoints to manage labware offsets.

query Parameters
loadName
string (Loadname)
namespace
string (Namespace)
version
integer (Version)
parent
string (Parent)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Get a saved labware calibration by ID Deprecated

This endpoint has been removed. Use the /runs endpoints to manage labware offsets.

path Parameters
calibrationId
required
string (Calibrationid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
null

Remove a saved labware calibration by ID Deprecated

This endpoint has been removed. Use the /runs endpoints to manage labware offsets.

path Parameters
calibrationId
required
string (Calibrationid)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
null

Pipette Offset Calibration Management

Get all pipette offset calibrations

Fetch all saved pipette offset calibrations from the robot

query Parameters
pipette_id
string (Pipette Id)
mount
string (MountType)
Enum: "left" "right"

Pipette mount type

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Delete a pipette offset calibration

Delete one specific pipette calibration by pipette serial and mount.

query Parameters
pipette_id
required
string (Pipette Id)
mount
required
string (MountType)
Enum: "left" "right"

Pipette mount type

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
null

Tip Length Calibration Management

Search the robot for any saved tip length calibration

Fetch all saved tip length calibrations from the robot

query Parameters
tiprack_hash
string (Tiprack Hash)
Deprecated

Filter results by their tiprack field. This is deprecated because it was prone to bugs where semantically identical definitions had different hashes. Use tiprack_uri instead.

pipette_id
string (Pipette Id)

Filter results by their pipette field.

tiprack_uri
string (Tiprack Uri)

Filter results by their uri field.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Delete Specific Tip Length Calibration

Delete one specific tip length calibration by pipette serial and tiprack uri

query Parameters
pipette_id
required
string (Pipette Id)

The pipette field value of the calibration you want to delete. (See GET /calibration/tip_length.)

tiprack_hash
string (Tiprack Hash)
Deprecated

The tiprack field value of the calibration you want to delete. (See GET /calibration/tip_length.)

This is deprecated because it was prone to bugs where semantically identical definitions had different hashes. Use tiprack_uri instead.

You must supply either this or tiprack_uri.

tiprack_uri
string (Tiprack Uri)

The uri field value of the calibration you want to delete. (See GET /calibration/tip_length.)

You must supply either this or tiprack_hash.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
null

System Control

Fetch system time & date

Get robot's time status, which includes- current UTC date & time, local timezone, whether robot time is synced with an NTP server &/or it has an active RTC.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "links": {
    }
}

Set robot time

Update system time

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Request Body schema: application/json
required
required
object (Data)

the document’s 'primary data'

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "links": {
    }
}

Flex Subsystem Management

Get all attached subsystems

Get the details of all hardware subsystems attached to the robot.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get a specific attached subsystem

Get the details of a single hardware subsystem attached to the robot.

path Parameters
subsystem
required
any (SubSystem)
Enum: "gantry_x" "gantry_y" "head" "pipette_left" "pipette_right" "gripper" "rear_panel" "hepa_uv" "motor_controller_board"

Specific hardware elements of the robot system.

Only certain subsystems might be valid for a certain robot, and not all subsystems might be attached at any given time. In general, specific subsystems should only be provided if general queries indicate that they are present.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get all ongoing subsystem updates

Get a list of currently-running subsystem firmware updates. This is a good snapshot of what, if anything, is currently being updated and may block other robot work. To guarantee data about an update you were previously interested in, get its id using /subsystems/updates/all.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get the ongoing update for a specific subsystem

As /subsystems/updates/current, but filtered by the route parameter.

path Parameters
subsystem
required
any (SubSystem)
Enum: "gantry_x" "gantry_y" "head" "pipette_left" "pipette_right" "gripper" "rear_panel" "hepa_uv" "motor_controller_board"

Specific hardware elements of the robot system.

Only certain subsystems might be valid for a certain robot, and not all subsystems might be attached at any given time. In general, specific subsystems should only be provided if general queries indicate that they are present.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get all subsystem updates

Get a list of all updates, including both ongoing updates and updates that started since the last boot but are now complete.

While an update might complete and therefore disappear from/subsystems/updates/current, you can always find that update in the response to this endpoint by its id.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get a specific subsystem update

As /subsystems/updates/all, but returning only one resource: the one with the id matching the route parameter (if it exists).

path Parameters
id
required
string (Id)
header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Start an update for a subsystem

Begin a firmware update for a given subsystem.

path Parameters
subsystem
required
any (SubSystem)
Enum: "gantry_x" "gantry_y" "head" "pipette_left" "pipette_right" "gripper" "rear_panel" "hepa_uv" "motor_controller_board"

Specific hardware elements of the robot system.

Only certain subsystems might be valid for a certain robot, and not all subsystems might be attached at any given time. In general, specific subsystems should only be provided if general queries indicate that they are present.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Robot

Get connected estop status.

Get the current estop status of the robot, as well as a list of connected estops.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Acknowledge and clear an Estop event.

If the estop is currently logically engaged (the estop was previously pressed but is now released), this endpoint will reset the state to reflect the current physical status.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get the status of the robot door.

Get whether the robot door is open or closed.

header Parameters
required
Opentrons-Version (string) or Opentrons-Version (integer) (Opentrons-Version)

The HTTP API version to use for this request. Must be 2 or higher. To use the latest version unconditionally, specify *.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}