API Integration v2.1

The Authentication tab consists of API command for users to log into their account.

API Command	Description	Parameter			Response
		Parameter Name	Parameter Type	Description
[POST] /api/v2.1/token	Generates a token against username and password.	username	Request Body	Username of the FLO i8 account	200 ‒ Token generated successfully. 400 ‒ Token generation command cannot be completed at the moment. Error response includes an error message.
		password		Password of the FLO i8 account

The Device tab contains a list of API commands for instrument movements.

API Command	Description	Parameter			Response
		Parameter Name	Parameter Type	Description
[POST] /api/v2.1/devices/home	Home all or specific devices.	device	Request Body	Device group identifier. It can be set to Deck, Spanner, Stem, or null if targeting all devices.	200 ‒ Home command successfully completed. 400 ‒ The Home command cannot be completed at the moment. 401 ‒ Unauthorized token is missing.
		index		Set the index of the device to home. Parameters are commanded as an array. Available indices are 0 to 7 for Spanner and Stem device groups. If the device property is null or set to Deck, parameters are not necessary.
		Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.
[POST] /api/v2.1/devices/move-absolute	Move devices to an absolute position.	device	Request Body	Device group identifier. It can be set to Deck, Spanner, or Stem.	200 ‒ Move absolute command successfully completed. 400 ‒ Move absolute command cannot be completed at the moment. 401 ‒ Unauthorized token is missing.
		parameter		Parameters of movement, including velocity, acceleration, jerk, wait, and motion-parameters. The details of each parameter are explained below. Format: velocity: Velocity of the motor, specified linear units (mm/s). acceleration: Motor acceleration, specified linear units (mm/s^2). jerk: Motor jerk, specified linear units (mm/s^3). wait: A flag to indicate whether the request should wait for the motor movement. Setting it to true will block the request thread until motor motion is completed. motion-parameters: index: Available indices are 0 to 7 for Spanner and Stem device groups. For Deck, index is not necessary. position: Target position of the movement, specified linear units (mm).
		Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.
[POST] /api/v2.1/devices/move-relative	Move devices for a specific distance from the current position.	device	Request Body	Device group identifier. It can be set to Deck, Spanner, or Stem.	200 ‒ Move relative command successfully completed. 400 ‒ Move relative command cannot be completed at the moment. 401 ‒ Unauthorized token is missing.
		parameter		Parameters of movement, including velocity, acceleration, jerk, wait, and motion-parameters. The details of each parameter are explained below. Format: velocity: Velocity of the motor, specified linear units (mm/s). acceleration: Motor acceleration, specified linear units (mm/s^2). jerk: Motor jerk, specified linear units (mm/s^3). wait: A flag to indicate whether the request should wait for the motor movement. Setting it to true will block the request thread until motor motion is completed. motion-parameters: index: Available indices are 0 to 7 for Spanner and Stem device groups. For Deck, index is not necessary. distance: Target distance of the movement, specified linear units (mm).
		Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.
[POST] /api/v2.1/devices/sensor/door/enable	Enable/disable the door sensor.	is-enable	Request Body	Define whether the door sensor is enabled or not. Set it to true to enable the door sensor.	200 ‒ Enable or disable door sensor command successfully completed. 400 ‒ Enable or disable door sensor command cannot be completed at the moment. 401 ‒ Unauthorized token is missing.
		Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.
[POST] /api/v2.1/devices/sensor/waste-bin/enable	Enable/disable the Waste Bin sensor.	is-enable	Request Body	Define whether the Waste Bin sensor is enabled or not. Set it to true to enable the waste-bin sensor.	200 ‒ Enable or disable Waste Bin sensor command successfully completed. 400 ‒ Enable or disable Waste Bin sensor command cannot be completed at the moment. 401 ‒ Unauthorized token is missing.
		Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.
[POST] /api/v2.1/devices/camera/scan-tip-box	Scan for a tip box on specified deck positions to determine the remaining tips inside.	parameters	Request Body	deck-slot: The specified positions on deck user wants to scan. tip-capacity: The tip box capacity can be specified as 'p20', 'p200', 'p1000'. Leave it blank ('') for the system to determine automatically.	200 - Tip boxes scanned successfully. 400 - Tip box scanning failed at the moment. Detailed information about the issue is included in the response body.

The Labware tab consists of API commands related to labware saved in the system.

API Command	Description	Parameter			Response
		Parameter Name	Parameter Type	Description
[GET] /api/v2.1/labwares	Retrieve available labware definitions on the instrument.	name	Request Body	Search for a labware name. Leaving empty will return all available labware.	200 ‒ List of available labware 400 ‒ The labware list cannot be retrieved at the moment. Error response includes an error message. 401 ‒ Unauthorized token is missing.
		max		Maximum number of results to get. Leaving the parameters empty will return all matched results.
		Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.

The Pipetting Profile tab consists of API command related to pipetting profiles saved in the system.

API Command	Description	Parameter			Response
		Parameter Name	Parameter Type	Description
[GET] /api/v2.1/pipetting-profiles	Retrieve pipetting profiles against logged in user on the instrument.	name	Request Body	Search for a pipetting profile name. Leaving empty will return all available pipetting profiles against the logged in user.	200 ‒ List of available pipetting profiles against the logged in user 400 ‒ The pipetting profile list cannot be retrieved at the moment. Error response includes an error message. 401 ‒ Unauthorized token is missing.
		max		Maximum number of results to get. Leaving the parameters empty will return all matched results.
		Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.

The Protocol tab consists of API commands for protocol preparation, execution, and recovery.

API Command	Description	Parameter			Response
		Parameter Name	Parameter Type	Description
[GET] /api/v2.1/protocols	Retrieve available protocols against logged in user on the instrument.	name	Request Body	Search for a protocol name. Leaving empty will return all available protocols against the logged in user.	200 ‒ List of available protocols against logged in user 400 ‒ The protocol list cannot be retrieved at the moment. Error response includes an error message. 401 ‒ Unauthorized token is missing.
		max		Maximum number of results to get. Leaving the parameters empty will return all matched results.
		Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.
[POST] /api/v2.1/protocols/{id}/validate	Validate specific protocol identified by its ID. After a protocol is validated, it is now ready to be run. The instrument state will be set to Busy, and other requests for protocol validation can not be performed until the protocol execution done or aborted and instrument state back to Idle.	id	Request Body	The GUID of protocol to run	200 ‒ Specified protocol successfully validated. 400 ‒ Protocol validation failed at that moment. Detailed information about the issue is included in the response body. 401 ‒ Unauthorized token is missing. 404 ‒ Specified protocol does not exist on the current instrument.
		tipPreferences	Request URL	(Optional) Formatted string describes tip preference selection to use on the specified protocol. Available values are p20, p200, and p1000. It is case-insensitive, and it allows multiple tip selections. For multiple tip selection, each type should be separated by a comma (e.g. "p200" or "p20,p200"). Invalid values will be ignored. If all values are invalid, the request will be rejected.
		Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.
[GET] /api/v2.1/protocols/current/status	Get the status of the protocol currently running.	Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.	200 ‒ Current protocol status successfully retrieved. 400 ‒ Current protocol status cannot be retrieved at the moment. 401 ‒ Unauthorized token is missing.
[GET] /api/v2.1/protocols/current/proposed-deck	Get the last updated proposed deck layout.	Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.	200 ‒ Current protocol proposed deck successfully retrieved. 400 ‒ Current protocol proposed deck cannot be retrieved at an invalid state. 401 ‒ Unauthorized token is missing. 404 ‒ Current protocol proposed deck cannot be retrieved at the moment.
[POST] /api/v2.1/protocols/skip-scan-deck	Skip scanning specified deck positions.	parameters	Request Body	deck-slot: The specified deck positions user wants to skip scanning. labware-height: The height of the labware or object on the specified deck position, so the system can avoid it to prevent collision.	200 - Scanning specified deck positions will be skipped at protocol execution time. 400 - Deck scanning failed at the moment. Detailed information about the issue is included in the response body.
[POST] /api/v2.1/protocols/current/execute	Execute protocol which is currently in validated state with specified options.	require-check-tip	Request Body	If the value is True, then system will check the tip availability by scanning the deck before running the protocol.	200 ‒ Protocol execution command successfully sent to the instrument. A status update will be available through the status endpoint. 400 ‒ Protocol execution command cannot be sent at the moment. 401 ‒ Unauthorized token is missing.
		tip-caddy-positions		Information regarding the tip box position. Format: tip-capacity: The tip type by its maximum capacity. labware-seat-pos: The tip box position on the deck, including: lane-id: column number (e.g. rack id 5 = column 0, rack id 4 = column 1, …, rack id 1 = column 4 ) pos-id: row number (e.g. rack id 1-5 = row 1 and rack 6-10 = row 2). position: The deck id to identify tip box location. num-of-tips: Minimum required number of tips in the tip box.
		labware-positions		Information regarding the labware position. Format: labware-full-id: The labware ID labware-name: The labware name in the current protocol. position: Rack ID of the labware location. use-as-source-at: The pipetting step ID where the source labware is located. use-as-destination-at: The pipetting step ID where the destination labware is located.
		Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.
[PATCH] /api/v2.1/protocols/current/pause	Pause the running protocol.	Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.	200 ‒ Protocol pause command successfully sent to the instrument. A status update will be available through the status endpoint. 400 ‒ Pause command cannot be sent at the moment. 401 ‒ Unauthorized token is missing.
[PATCH] /api/v2.1/protocols/current/resume	Resume the paused protocol.	Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.	200 ‒ Protocol resume command successfully sent to the instrument. A status update will be available through the status endpoint. 400 ‒ The resume command cannot be sent at the moment. 401 ‒ Unauthorized token is missing.
[DELETE] /api/v2.1/protocols/current/abort	Abort the running protocol or current protocol on preparation.	Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.	200 ‒ Protocol abort command successfully sent to the instrument. A status update will be available through the status endpoint. 400 ‒ Abort command cannot be sent at the moment. 401 ‒ Unauthorized token is missing.
[PATCH] /api/v2.1/protocols/current/confirm	Confirm the User Confirmation step of the current protocol.	Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.	200 ‒ User Confirmation step of the current protocol successfully confirmed. Proceed to the next protocol steps if any. 400 ‒ Confirm command cannot be performed at the moment. 401 ‒ Unauthorized token is missing.
[PATCH] /api/v2.1/protocols/current/skip-delay	Skip the Delay step of the current protocol	Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.	200 ‒ Delay step of the current protocol successfully skipped. Proceed to the next protocol steps if any. 400 ‒ Skip delay command cannot be performed at the moment. 401 ‒ Unauthorized token is missing.
[PATCH] /api/v2.1/protocols/current/confirm-tip	Confirm new tip preferences of the current protocol. The tip preference can be changed after the protocol is validated (before the protocol runs) and during protocol execution (while the protocol runs).	tipPreferences	Request Body	The available values are p20, p200, and p1000.	200 ‒ Tip preference of the current protocol successfully confirmed. The updated deck layout will be available through the proposed-deck endpoint. 400 ‒ Confirm tip command cannot be performed at the moment. 401 ‒ Unauthorized token is missing.
		Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.
[PATCH] /api/v2.1/protocols/current/recover	Recover the current failed protocol execution.	Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.	200 ‒ Clear last task execution error. No additional recovery options were performed. 400 ‒ Recovery action cannot be performed at the moment. 401 ‒ Unauthorized token is missing.
[PATCH] /api/v2.1/protocols/current/recovery/retry	Recover the current failed protocol execution and perform the retry operation.	dispenseBack	Request Body	Boolean option to recover the remaining liquid in the current tips to the source. It will automatically be set to False if this parameter isn’t provided. If it is set to True, the remaining liquid will be dispensed back to the source. Otherwise, the tip will be ejected into the Waste Bin.	200 ‒ Recover and attempt to retry the failed protocol execution. Additional options can be performed if available. See the description of parameters for details. 400 ‒ Cannot retry to recover at the moment. 401 ‒ Unauthorized token is missing.
		ejectAndPickTip		Boolean option to switch the current tip with the new one. When the dispenseBack option is provided and this parameter isn’t provided, it will automatically be set to True. If it is set to True, tip changing operation will be performed. Otherwise, the tip-changing operation will not be performed.
		Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.
[PATCH] /api/v2.1/protocols/current/recovery/set-actions	Set additional recovery actions during the recovery operation.	recoveryActions	Request Body	Additional recovery actions to be executed. recoveryActions: Skip: Skip transfer. Retry: Retry the failed process. Refill: Pipetting error recovery.   recovery-option: dispense-liquid-in-bad-tips-back-to-source: Boolean option to recover the remaining liquid in the current tips to the sources. insert-eject-and-pick-tip: Boolean option to switch the current tip. skip-for-all-impacted-task: Boolean option to skip all affected tasks. continue-anyway: Boolean option to continue to the next process.	200 ‒ Specify the recovery actions to be performed on the next error recovery attempt. 400 ‒ Set recovery action cannot be performed at the moment. 401 ‒ Unauthorized token is missing.
		Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.
[PATCH] /api/v2.1/protocols/current/recovery/skip	Skip the recovery action of the current failed protocol execution.	Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.	200 ‒ Skip to recover on the next error recovery attempt. 400 ‒ Skip recovery action cannot be performed at the moment. 401 ‒ Unauthorized token is missing.
[PATCH] /api/v2.1/protocols/set-waste-bin-emptied	Confirm that the Waste Bin has been emptied.	Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.	200 ‒ Set the Waste Bin state as Empty. 400 ‒ Set Waste Bin status cannot be performed at the moment. 401 ‒ Unauthorized token is missing.
[POST] /api/v2.1/protocols/validate-csv-protocol	Validate protocol file with CSV format	csvProtocol	Request Body	Protocol file with CSV format.	200 ‒ Specified protocol successfully validated. 400 ‒ Protocol validation failed at that moment. Detailed information about the issue is included in the response body. 401 ‒ Unauthorized token is missing.
		tipPreferences	Request URL	(Optional) Formatted string describes tip preference selection to use on the specified protocol. Available values are p20, p200, and p1000. It is case-insensitive and allows multiple tip selection. For multiple tip selection, each type should be separated by a comma (e.g. "p200" or "p20,p200"). Invalid values will be ignored. If all values are invalid, the request will be rejected.
		Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.
[GET] /api/v2.1/protocols/last-dispense-report	Get the dispense report of the last protocol run.	Authorization	Request Header	Generated token from the /api/v2.1/token endpoint. Format: Bearer<space><token>.	200 ‒ Last dispense report is successfully retrieved. 401 ‒ Unauthorized token is missing. 404 ‒ Last dispense report not found.

The Models tab provides the list of schemes/models that appear in the Device and Protocol commands.

Models	Description
ApiResponse	General response after API command execution
ApiResponseErrorCode	API error code returned by the system
SimpleErrorResponse	Response when an error occurs after API command execution
GenericErrorResponse	Generic response when an error occurs after API command execution
DeviceHomeParameters	Input parameter for specific devices to home
DeviceGroup	Name of device type (i.e.: Deck, Spanner, Stem)
HomeMotorParameters	Input parameter needed for motor homing
DeviceMoveAbsoluteParameters	Input parameters for specific devices to move to an absolute position
MoveAbsoluteParameters	All the input parameters for the motor to move to an absolute position
MoveAbsoluteMotorParameters	Additional input parameter for the motor to move to an absolute position
DeviceMoveRelativeParameters	Input parameter for device to move relative to its original position
MoveRelativeParameters	All the input parameters for the motor to move relative to its original position
MoveRelativeMotorParameters	Additional input parameters for the motors to move relative to their original position
SetDoorSensorEnableDto	Input parameter for the door sensor to be enabled/disabled
SetWasteBinSensorEnabledDto	Input parameter for the Waste Bin to be enabled/disabled
LabwareResponse	Response when the system successfully retrieves labware lists
LabwareList	List of labware data
LabwareData	General information of the labware
PipettingProfileResponse	Response when the system successfully retrieves pipetting profile lists.
PipettingProfileList	List of pipetting profile properties
PipettingProfileData	General information on pipetting profiles
ProtocolResponse	Response when the system successfully retrieves protocol lists
ProtocolList	List of protocols
ProtocolData	General information of the protocol
ProtocolValidatedResponse	Response when the system successfully validates specified protocol
ProposedDeckLayout	Proposed deck layout in the system
PlatePositions	List of labware and tip boxes positions
LabwarePosPair	Labware position and properties
TipCaddyDataUi	Tip box properties with the proposed position
TipCaddyData	Tip box position and properties
TipCapacity	The maximum volume capacity of the current tip
LabwareSeatPos	The labware position on the deck
PreferredTipType	Preferred tip type to be used in the protocol
InitialStock	List of initial volumes that are required before running protocols
InitialStockItem	Volume data that the user should prepare before running protocols
WellData	Information of wells that will be used in the protocol
Stock	Stock information in specific well
ConcentrationUnit	Liquid concentration unit used in the protocol (mM, M, uM, Copies/µL, au)
VolumeUnit	Unit used in the protocol for measuring liquid volume (µL, mL)
StockUsage	Stock volume used in a transfer card
ProtocolErrorCode	Protocol error enumeration
ProtocolValidationErrorResponse	Response when the specific protocol gets validation errors
ProtocolRunningStatus	Current status of the running protocol
RunningStatusDetail	Current progress of the running protocol
FloTaskType	Task type enumeration
UIFlags	User Interface flag enumeration
UISubstate	User Interface substate enumeration
EnclosureState	Door state enumeration
ProtocolExecutionParameters	Protocol input parameter to be executed
ProtocolExecutorErrorCleared	Event that is published when an error in a protocol is cleared
RecoveryActions	Recovery action enumeration
RecoveryOption	Boolean option for additional recovery
DispenseReport Response	Response when the system successfully retrieves the dispense report lists
DispenseReportList	List of dispense report data
DispenseReportData	Single dispense info

1. Do authentication by sending a POST request to the /api/v2.1/token endpoint and inputting your username and password in the request body:

   

   Input the Username and Password

   A token will be generated, and you can retrieve it from the response body:

   

   Generated Token in the Response Body

   This token needs to be included in the request header for every API call. The format is "Bearer<space><token>".

2. Make sure no other user is running any protocol by sending a GET request to the /api/v2.1/protocols/current/status endpoint. The response payload for "status" should indicate "Idle".

   

   Response Payload for Status is Idle

3. To run an existing protocol: Make sure that a list of protocols is available in Protocol Explorer. You can send a GET request to the /api/v2.1/protocols endpoint to retrieve all available protocols.

4. To run a protocol with a CSV file: Prepare your CSV file with the correct template. For more information, see the guidelines in the CSV File Format Guideline section.

Step Type	Source Labware Name	Source Well (Well Number)	Destination Labware Name	Destination Well (Well Number)	Transfer Volume in µL (rounded to 2 digits)	Pipetting Profile (Leave the cell blank to use default profile)
User Confirmation (Start Protocol?)
Simple Transfer 1	Eppendorf Microplate 96/U	A12	Eppendorf Microplate 96/U (1)	A12	25	Factory Profile
Simple Transfer 1	Eppendorf Microplate 96/U	B12	Eppendorf Microplate 96/U (1)	B12	25	Factory Profile
Delay (10) (Wait for it)
Simple Transfer 2	Eppendorf Microplate 96/U	A11	Eppendorf Microplate 96/U (1)	A11	25	Above Well Bottom
Simple Transfer 2	Eppendorf Microplate 96/U	B11	Eppendorf Microplate 96/U (1)	B11	25	Above Well Bottom

CSV File Example

1. Get the CSV file by choosing from the following options:

   • Download a CSV file template from the Import Workflow dialog box.

     

     GET TEMPLATE Button

   • Export a protocol in a CSV file from Protocol Explorer.

2. To prevent any error during loading data, you must follow the required/default column header format, including:

   1. Step Type

   2. Source Labware Name

   3. Source Well (Well Number)

   4. Destination Labware Name

   5. Destination Well (Well Number)

   6. Transfer Volume in μL (rounded to 2 digits)

   7. Pipetting Profile (leave the cell blank to use default profile)

3. The Source Labware Name and Destination Labware Name must match the names on the system. Send a GET request to the /api/v2.1/labwares endpoint to get the existing labware list in the Labware Manager.

   Tip: To identify labware with the same name, add an index number. For example, Eppendorf Microplate 96/U, Eppendorf Microplate 96/U (1), and Eppendorf Microplate 96/U (2).

4. Running protocol using CSV files only supports Simple Transfer, User Confirmation, and Delay steps.

5. The User Confirmation step contains a confirmation message within parentheses. Leave the other columns empty.

6. The Delay step contains delay time in seconds within parentheses. Leave the other columns empty.

7. To get the pipetting profile list from Pipetting Profile Explorer, send a GET request to the /api/v2.1/pipetting-profiles endpoint.

1. Home all channels by sending a GET request to the /api/v2.1/devices/home endpoint.

   Tip: You can send a GET request to the /api/v2.1/protocols/current/status endpoint periodically until the status shows that the device is idle while waiting for this movement to finish.

   

   Current Status Indicates the Instrument is in Idle Position

2. Send a GET request to the /api/v2.1/protocols endpoint to retrieve all available protocols in the Protocol Explorer. Get the protocol ID from the response body:

   

   Get the Protocol ID

3. To validate the protocol, send a POST request to the /api/v2.1/protocols/{id}/validate endpoint, and replace {id} with the protocol ID obtained from the previous step.

   Note: If the protocol validation fails, check its status. If it's not idle, you must first abort the current protocol by sending a DELETE request to the /api/v2/protocols/current/abort endpoint. Otherwise, it indicates that you've sent an invalid request.

4. Identify the plate and tip box placement position from the summary-plate-positions property in the response body:

   

   The summary-plate-positions in Response Body

   • The tip box position is represented by tip-caddy-positions, which contains the following properties:

     • tip-capacity: The tip type by its maximum capacity.

     • labware-seat-pos: The tip box position on the deck, including:

       1. lane-id as column number (e.g. rack id 5 = column 0, rack id 4 = column 1, …, rack id 1 = column 4).

       2. pos-id as row number (e.g. rack id 1-5 = row 1 and rack 6-10 = row 2).

     • position: Rack ID of the plate’s location.

     • num-of-tips: Minimum required number of tips in the tip box.

       

       The tip-caddy-positions Payload

   • The plate position is represented by labware-positions, which contains the following properties:

     • labware-full-id: The plate’s ID.

     • labware-name: The plate’s name in the current protocol.

     • position: Rack ID of the plate’s location.

     • use-as-source-at: The pipetting step ID where the source plate is located.

     • use-as-destination-at: The pipetting step ID where the destination plate is located.

       

       The labware-positions Payload

5. If you prefer the system's suggested positions, leave the summary-plate-positions unchanged. For custom positions aligning with your desired labware and tip box setup, refer to the Overriding Labware Position section.

6. Place the required plate and tip boxes on the instrument’s deck according to the summary-plate-positions.

7. Send a POST request to the /api/v2.1/protocols/current/execute endpoint with tip-caddy-positions and labware-positions input parameter from the protocol validation result in step #4.

   

   Execute a Protocol After it is Validated

8. If the response body indicates "None" for the error-code, it means the protocol execution has started successfully. Otherwise, an error has occurred, either a deck validation error or a hardware error. See the details on Error Codes.

   

   No Error Found

9. You can get the current protocol running status by periodically sending a GET request to the /api/v2.1/protocols/status endpoint.

   

   Current Status Indicates Protocol is Running

   Note: There are 4 protocol task types shown in current-task-type property: None, UserConfirmationTask, DelayTask, and PipettingTask.

10. If the current-task-type is UserConfirmationTask you need to send a PATCH request to the /api/v2.1/protocols/confirm endpoint to confirm the User Confirmation step, and continue the protocol execution.

11. If the current-task-type is DelayTask, the protocol will be paused for a duration based on the user input in the protocol. Alternatively, you can skip the Delay step by sending a PATCH request to the /api/v2.1/protocols/skip-delay endpoint.

12. If you encounter an error during protocol execution, run the recovery commands. See the details on Error Codes.

13. Once the current protocol execution status is Done, you can retrieve the dispense report from the last protocol execution by sending a GET request to the /api/v2.1/protocols/last-dispense-report endpoint.

    

    Current Status Indicates Protocol Execution is Done

    

    Last Dispense Report Payload

Important: Only Administrator and Regular user accounts are permitted to run protocol using CSV file.

1. Home all channels by sending a GET request to the /api/v2.1/devices/home endpoint.

   Tip: You can send a GET request to the /api/v2.1/protocols/current/status endpoint periodically until the status shows that the device is idle while waiting for this movement to finish.

   

   Current Status Indicates the Instrument is in Idle Position

2. Send a POST request to the /api/v2.1/protocols/validate-csv-protocol endpoint with CSV file and tip capacity preferences (optional) as the input parameter. You will get response code 200 if the validation is successful. Otherwise, you will get code 400 with an error payload.

   Note: The CSV file and the generated protocol are not saved in the system database.

   Tip: You can see the CSV Validation Error section for the error details.

3. Identify the plate and tip box placement position from the summary-plate-positions property in the response body:

   

   The summary-plate-positions in the Response Body

   • The tip box position is represented by tip-caddy-positions, which contains the following properties:

     • tip-capacity: The tip type by its maximum capacity.

     • labware-seat-pos: The tip box position on the deck, including:

       1. lane-id as column number (e.g. rack id 5 = column 0, rack id 4 = column 1, …, rack id 1 = column 4).
       2. pos-id as row number (e.g. rack id 1-5 = row 1 and rack 6-10 = row 2).

     • position: Rack ID of the plate’s location.

     • num-of-tips: Minimum required number of tips in the tip box.

       

       The tip-caddy-positions Payload

   • The plate position is represented by labware-positions, which contains the following properties:

     • labware-full-id: The plate’s ID.

     • labware-name: The plate’s name in the current protocol.

     • position: Rack ID of the plate’s location.

     • use-as-source-at: The pipetting step ID where the source plate is located.

     • use-as-destination-at: The pipetting step ID where the destination plate is located.

       

       The labware-positions Payload

4. If you prefer the system's suggested positions, leave the summary-plate-positions unchanged. For custom positions aligning with your desired labware and tip box setup, refer to the Overriding Labware Position section.

5. Place the required plate and tip boxes on the instrument’s deck according to summary-plate-positions.

6. After your CSV file is successfully validated, send a POST request to the /api/v2.1/protocols/current/execute endpoint with labware-positions and tip-caddy-positions in step #3 as input parameters.

   

   Execute a Protocol After it is Validated

7. If the response body indicates "None" for the error-code, it means the protocol execution has started successfully. Otherwise, an error has occurred, either a deck validation error or a hardware error. See the details on Error Codes.

   

   No Error Found

8. You can get the current protocol running status by periodically sending a GET request to the /api/v2.1/protocols/status endpoint.

   

   Current Status Indicates Protocol is Running

   Note: There are 4 protocol task types shown in current-task-type property: None, UserConfirmationTask, DelayTask, and PipettingTask.

9. If the current-task-type is UserConfirmationTask you need to send a PATCH request to the /api/v2.1/protocols/confirm endpoint to confirm the User Confirmation step, and continue the protocol execution.

10. If the current-task-type is DelayTask, the protocol will be paused for a duration based on the user input in the protocol. Alternatively, you can skip the Delay step by sending a PATCH request to the /api/v2.1/protocols/skip-delay endpoint.

11. If you encounter an error during protocol execution, run the recovery commands. See the details on Error Codes.

12. Once the current protocol execution status is Done, you can retrieve the dispense report from the last protocol execution by sending a GET request to the /api/v2.1/protocols/last-dispense-report endpoint.

    

    Current Status Indicates Protocol Execution is Done

    

    Last Dispense Report Payload

1. Identify the plate and tip box placement position from the summary-plate-positions property in the response body of /api/v2.1/protocols/{id}/validate endpoint:

   Note: Ignore other payload properties that aren't mentioned in the following response body.

   

   The summary-plate-positions in Response Body

   • The plate position is represented by labware-positions, which contains the following properties:

     • labware-full-id: The plate’s ID.
     • labware-name: The plate’s name in the current protocol.
     • position: Rack ID of the plate’s location.
     • use-as-source-at: The pipetting step ID where the source plate is located.
     • use-as-destination-at: The pipetting step ID where the destination plate is located.

     

     The labware-positions Payload

   • The tip box position is represented by tip-caddy-positions, which contains the following properties:

     • tip-capacity: The tip type by its maximum capacity.

     • labware-seat-pos: The tip box position on the deck, including:

       1. lane-id as column number (e.g. rack id 5 = column 0, rack id 4 = column 1, …, rack id 1 = column 4).
       2. pos-id as row number (e.g. rack id 1-5 = row 1 and rack 6-10 = row 2).

     • position: Rack ID of the plate’s location.

     • num-of-tips: Minimum required number of tips in the tip box.

     

     The tip-caddy-positions Payload

2. Refer to the conversion table below to convert deck numbers from position to labware-seat-pos (lane-id and pos-id).

   

   Conversion Table of position and labware-seat-pos

   • To change the plate position, ONLY modify the position property.
   • To change the tip box position, ONLY modify the position and labware-seat-pos properties.
   • To add more tip boxes, include the additional tip box inside the tip-caddy-positions property. Please specify the tip-capacity, position, and labware-seat-pos. Meanwhile, set the proposed-position to 0 to indicate that it is an additional tip box not suggested by the system.

    

   To illustrate the scenario above, see the following example.

   1. Change destination labware position from deck number 6 to 8.
   2. Change source labware position from deck number 7 to 10.
   3. Change tip box p200 from deck number 8 to 6.
   4. Add additional tip boxes p200 in deck number 7.

   

   Overriding Labware Position Example

3. Copy the modified values of labware-positions and tip-caddy-positions from summary-plate-positions to the request body of the /api/v2.1/protocols/current/execute endpoint.

   

   The modified summary-plate-positions in Response Body

1. Send a POST request to the /api/v2.1/devices/camera/scan-tip-box endpoint with parameters indicating the tip box position on deck and its tip capacity.

   Note: The capacity of the tip box can be specified as “p20”, “p200”, or “p1000”. Leave it blank (“”) for the system to determine automatically.

   

   The scan tip box Request Body

2. Retrieve the result of the scanned tip box in the num-of-tips parameter as described below:

   • If you perform a scan on a deck position where the object is not detected as a tip box or where there is no labware or tip box present, the return value will be null.
   • If you leave the tip capacity blank, the system will override the “tip-capacity” parameter with the correct value based on detection. This process may take longer as it needs to check all tip capacities.

   

   The scan tip box Response Body

You can skip scanning the specified deck positions to:

• Keep labware or objects which are not used in the current protocol on the deck without triggering deck scanning errors.
• Speed up the deck scanning process because you are sure which deck positions will be occupied with labware and which ones will not be.

Note: If you want to add additional tip boxes that are expected to be used in the protocol execution, you don't need to skip scanning for these tip boxes. Instead, include them in the request body of the execute API command. You can refer to Override the labware or tip box positions section for more details.

To skip scanning specified deck positions:

Important: This step should be performed between the protocol validation (either API command for the /api/v2.1/protocols/{id}/validate endpoint or /api/v2.1/protocols/validate-csv-protocol end point) and protocol execution (API command for the /api/v2.1/protocols/current/execute endpoint).

1. Send a POST request to the /api/v2.1/protocols/skip-scan-deck endpoint with parameters indicating the deck slot you want to skip, and the height of the labware or object on the specified deck position.

2. For the labware-height-mm, you can input 0 to indicate no labware or objects present. You can also define it as 140 if you don't know the exact height. This height is safe for almost all labware.

   

   The skip scan deck Request Body

Note: The skip scanning specified deck positions setting will only be applied for the current protocol execution. It will be reset once you rerun the protocol validation in the next protocol.

Listed below are the error codes that you can use when you encounter errors while calling API commands to validate your CSV file.

Error Code	Error Payload	Description
ExceptionThrown	Failed to Get CSV File	There’s no CSV file input when executing CSV validation.
InvalidRequest	TransferVolumeIsNegative	The transfer volume value is < 0.
	TransferVolumeBelowMinimumValue	The transfer volume is lower than the minimum threshold of 0.5 μL.
	TransferVolumeIsNotNumber	There’s a non-numeric character in transfer volume.
	TransferVolumeIsNull	The transfer volume value is empty.
	DestinationWellNotExist	The specified well doesn’t exist in the current destination labware.
	DestinationWellNotFound	The destination well value is empty.
	SourceWellNotExist	The specified well doesn’t exist in the current destination labware.
	SourceWellNotFound	The source well value is empty.
	DestinationLabwareNameNotFound	The destination labware name is empty.
	SourceLabwareNameNotFound	The source labware name is empty.
	WrongHeaderDetected	Incorrect CSV header format
	UndefinedError	There’s a system exception when validating the CSV file.
	InvalidDelayFormat	Invalid delay step type format
	DelayMessageTooLong	The Delay message exceeds 1000 characters.
	InvalidUserConfirmationFormat	Invalid User Confirmation step type format
	UserConfirmationTooLong	The User Confirmation message exceeds 1000 characters.
	PipettingProfileCannotBeFound	The Pipetting Profile doesn’t exist in the system.
	CsvEmpty	There’s no CSV row content.
	LabwaresExceedDeckCapacity	The number of required labware exceeds the maximum deck capacity.
	SourceWellAlreadyEmpty	The source well for current transfer has been empty.
Unauthorized	Run-Only user is not authorized to use this API.	This action is restricted and cannot be performed by a Run-Only user account.

You may encounter certain errors during protocol execution. Listed below are the error codes and descriptions.

Error Code	Error Name	Description
-1	Aborted	The user or system aborts the protocol execution.
-10	LiquidNotEnough	Insufficient source to run the protocol.
-20	MultipleErrors	The system encounters multiple errors in multiple pipetting channels.
-21	MultipleCollisionErrors	The system encounters multiple collision errors in multiple pipetting channels.
-22	UnknownError	The system encounters an error that is unable to be categorized in the detail error code.
-30	NotEnoughTip	Insufficient tips in the tip box to be picked or ejected during protocol execution.
-40	ImpossibleLabwarePos	Unable to execute protocol because some wells are unreachable by the pipetting channels.
-50	HardwareError	The instrument encounters a general error.
-51	Collision	The pipetting channel is obstructed by objects or touched by the user.
-52	ActuatorError	The system encounters a motor error that is unable to be categorized in detail error code.
-53	ActuatorFollowingError	There is an error between the motor commanded position and actual position.
-54	ActuatorAborted	The motor movement is aborted before it is completed.
-55	ActuatorDisabled	The system encounters a disabled motor error.
-57	ActuatorIllegalPos	The motor is commanded to position outside its limit.
-58	ActuatorNotReady	The motor is not homed yet and not ready to execute movement command.
-59	ActuatorWaitMotionTimeout	The motor movement is never done until the time limit.
-61	ActuatorEncoderError	The system encounters an error on the encoder device.
-62	ActuatorMecNoMove	The motor is commanded but does not perform a movement.
-63	ActuatorEnableFailed	The system encounters an error while enabling the motor.
-64	ActuatorUnknownError	The system encounters a motor error that is not categorized above.
-79	LiquidBreachDetected	The system detects liquid breach above the pipetting channel.
-80	ActuatorEmergencyStop	The system stops all devices, including the movement and pipetting process, due to an emergency error.
-85	WasteBinFull	The waste bin is full. User is expected to clean it up before continuing protocol execution.
-86	WasteBinMissing	The waste bin is not placed within the instrument.
-90	TooManyLabwares	The system detects too many labware or tip box with the requirements placed on the deck.
-91	WrongLabwareLocation	The system detects incorrect required labware location on the deck.
-92	WrongTipCaddyLocation	The system detects incorrect required tip box location on the deck.
-93	WrongTipCaddyAndLabwareLocation	The system detects incorrect labware and tip box location on the deck.
-94	MissingLabware	The system detects no labware on the required deck position.
-95	MissingTipCaddy	The system detects no tip box on the required deck position.
-96	MissingTipCaddyAndLabware	The system detects no labware and tip box on the required deck position.
-97	WrongTipCaddyCapacity	The system detects incorrect tip box type on the required deck position.
-101	TipCaddyScanFailed	The system failed to detect tip box.
-102	MultipleLabwareAndTipCaddyError	The system encounters multiple errors during deck validation process.
-110	Busy	The system encounters an error when user attempts to run a protocol while the system is executing another protocol.
-112	AnyPipettingErrors	The system encounters a pipetting error that is unable to be categorized in detail error code.
-200	PickTipValidationFailed	The pipetting channel detects a bad tip after completing picking-up tip.
-201	PickTipNoSensorTriggered	The pipetting channel failed to pick tip due to failure in detecting tip’s position, or the tip is not available in the tip box.
-202	PickTipValidationFailedMaxRetry	The pipetting channel exceeds the maximum attempts to recover from tip validation error.
-300	SurfaceNotFound	The pipetting channel failed to find any surface during liquid level detection process.
-301	PipettingTimeout	The pipetting command is never done until the time limit.
-302	InvalidPressure	The pipetting channel encounters a problem with an invalid value during pressure validation.
-304	TouchOffNotTriggered	The pipetting channel failed to touch the well side.
-307	AirAspirationDetected	The pipetting channel encounters air aspiration during aspirate process.
-308	ClogDetected	The pipetting channel encounters clogs during executing pipetting process.
-309	InvalidVolume	The pipetting channel is commanded to transfer invalid volume.
-310	PipettingBusy	The pipetting channel is commanded to do pipetting process while still doing another process.
-311	PipettingCancelled	The pipetting process is canceled.
-400	EnclosureOpened	Door is open.
-401	EnclosureClosed	Door is closed.
-500	PipettingError	The system encounters a pipetting error.
-600	VisionError	The system encounters an error in the camera module

Use the listed recovery options to address errors that might occur during the protocol execution via API Integration.

Recovery Option	Verb	API Command	Parameter Name	Payload
Recover	PATCH	/api/v2.1/protocols/current/recover	N/A	N/A
Retry	PATCH	/api/v2.1/protocols/current/recovery/retry	dispenseBack	true/false
			ejectAndPickTip	true/false
Skip	PATCH	/api/v2.1/protocols/current/recovery/skip	N/A	N/A
Continue Anyway	PATCH	/api/v2.1/protocols/current/recovery/set-actions	recoveryActions	[ { "pipette-index": 0, "recovery-action": "Retry", "recovery-option": { "continue-anyway": true } } ]
Recover & Retry	PATCH	/api/v2.1/protocols/current/recovery/set-actions	recoveryActions	[ { "pipette-index": 0, "recovery-action": "Retry", "recovery-option": { "dispense-liquid-in-bad-tips-back-to-source": true } } ]
Eject & Retry	PATCH	/api/v2.1/protocols/current/recovery/set-actions	recoveryActions	[ { "pipette-index": 0, "recovery-action": "Retry", "recovery-option": { "dispense-liquid-in-bad-tips-back-to-source": false, "insert-eject-and-pick-tip": true } } ]
Recover & Skip This Transfer	PATCH	/api/v2.1/protocols/current/recovery/set-actions	recoveryActions	[ { "pipette-index": 0, "recovery-action": "Skip", "recovery-option": { "dispense-liquid-in-bad-tips-back-to-source": true } } ]
Skip This Transfer	PATCH	/api/v2.1/protocols/current/recovery/set-actions	recoveryActions	[ { "pipette-index": 0, "recovery-action": "Skip", "recovery-option": { "dispense-liquid-in-bad-tips-back-to-source": false } } ]
Recover & Skip Affected Transfer	PATCH	/api/v2.1/protocols/current/recovery/set-actions	recoveryActions	[ { "pipette-index": 0, "recovery-action": "Skip", "recovery-option": { "dispense-liquid-in-bad-tips-back-to-source": true, "skip-for-all-impacted-task": true } } ]
Skip Affected Transfer	PATCH	/api/v2.1/protocols/current/recovery/set-actions	recoveryActions	[ { "pipette-index": 0, "recovery-action": "Skip", "recovery-option": { "dispense-liquid-in-bad-tips-back-to-source": false, "skip-for-all-impacted-task": true } } ]
Abort	DELETE	/api/v2.1/protocols/current/abort	N/A	N/A