API Integration V2

The Application Programming Interface (API) in FLO i8 is a set of protocols and functions that enables your FLO i8 instrument to integrate with other systems or devices, allowing you to create more advanced laboratory automation right at your site.

Important: The FLO i8 API is restricted to your laboratory’s automation engineer or authorized IT personnel. Any inaccurate settings may cause instrument errors or damage. Contact support@formulatrix.com for more information and assistance.

The API is accessible using any programming language that supports REST API and JSON format. To explore FLO i8 API Integration details and try the API, you can go to the hostname of your FLO i8 instrument extended with :5005/restapi on your internet browser.

 

API Integration Flowchart

The flowchart below illustrates the process of integrating the FLO i8 APIs.

 

FLO i8 API Commands and Models

The FLO i8 API page consists of five tabs: Device, Labware, Pipetting Profile, Protocol, and Models, with each tab offering specific commands and functions for the integration process. An overview of the FLO i8 API page is displayed in the following picture, with each tab containing detailed information about its respective commands. To experiment with the API commands, you can use the Try it out button provided in each command tab. This button, along with others like Execute, Clear, and Cancel, allows you to explore the API integration procedures.

Authentication
Expand

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

Device
Expand

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

Labware
Expand

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

Pipetting Profile
Expand

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

Protocol
Expand

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

Models
Expand

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

Running Protocol Using API Commands

You can run a protocol via API in 2 ways: using an existing protocol in the Protocol Explorer or a CSV file.

Preparation
Expand

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

A token will be generated, and you can retrieve it from 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/protocols/current/status endpoint. The response payload for “status” should indicate “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/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.

CSV File Format Guideline
Expand

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

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

• 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/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/pipetting-profiles endpoint.

Run Existing Protocol
Expand

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

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

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

3. To validate the protocol, send a POST request to the /api/v2/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 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:

• lane-id as column number (e.g. rack id 5 = column 0, rack id 4 = column 1, …, rack id 1 = column 4).
• 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 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.

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/protocols/current/execute endpoint with tip-caddy-positions and labware-positions input parameter from the protocol validation result in step #4.

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.

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

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/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/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/protocols/last-dispense-report endpoint.

Run Protocol with CSV
Expand

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/devices/home endpoint.

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

2. Send a POST request to the /api/v2/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 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:

• lane-id as column number (e.g. rack id 5 = column 0, rack id 4 = column 1, …, rack id 1 = column 4).
• 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 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.

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 the summary-plate-positions.
6. After your CSV file is successfully validated, send a POST request to the /api/v2/protocols/current/execute endpoint with labware-positions and tip-caddy-positions in step #3 as input parameters.

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.

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

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/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/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/protocols/last-dispense-report endpoint.

Overriding Labware Position
Expand

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

Note: Ignore other payload properties that aren’t mentioned in the following 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 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:

• lane-id as column number (e.g. rack id 5 = column 0, rack id 4 = column 1, …, rack id 1 = column 4).
• 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.

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

• 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.

 

To illustrate the scenario above, see the following example.

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

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

Troubleshooting

This section provides error codes and description for troubleshooting during API integration.

CSV Validation Error
Expand

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

Error Codes
Expand

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

Error Recovery API
Expand

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

Related Topics:

• API Integration V1.1
• Importing Workflow
• Error Recovery
• Error Recovery Settings