LabOS Instrument API
Overview
Users can onboard various laboratory instruments into Genie’s cloud platform (LabOS). Each instrument exposes a set of actions that can be invoked through the UI or the REST API. This document describes the Instrument REST API, providing a few examples. A basic understanding of Genie’s REST API patterns (see LabOS REST API) is assumed.
Instrument CRUD
| Endpoint | Description |
|---|---|
GET {url}/instruments | Retrieves a list of instruments |
GET {url}/instruments/{uid} | Retrieves a specific instrument |
DELETE {url}/instruments/{uid} | Deletes the specified instrument. This action is idempotent – it will return success whether an object was deleted or it didn’t exist to begin with. |
Command API
Actions
Each instrument has a set of actions which can be executed through the REST API.
| Endpoint | Description |
|---|---|
GET {url}/instruments/{uid}/actions |
Returns information about all actions that can be run against the specified instrument. |
GET {url}/instruments/{uid}/actions/{cid} |
Returns information about a specific instrument action. {cid} is the name of the action. |
Action Attributes
| Attribute | Description |
|---|---|
action |
Name of the action |
parameters |
List of parameters that need to be passed in to the action |
Parameter Attributes
| Attribute | Description |
|---|---|
id |
Internal, unique identifier of the parameter. Parameters can be referenced by their unique identifiers or their names. |
name |
Parameter name |
type |
One of the following types: number, string, volume, time, file, json. |
options |
Optional attribute restricts the list of valid values (e.g., making the parameter an enum) |
min |
Optional attribute for number, volume, and time parameters to restrict their minimum value. In case of string parameters, this attribute restricts the size of the string to the specified value. |
max |
Optional attribute for number, volume, and time parameters to restrict their maximum value. In case of string parameters, this attribute restricts the size of the string to the specified value. |
Action Example
GET {url}/instruments/{uid}/actions/set_timed_shake
{
"action": "set_timed_shake",
"parameters": [
{
"id": "gokzgzjt",
"name": "Time",
"type": "time"
},
{
"id": "lkwkkevp",
"name": "RPM",
"type": "number",
"min": 0
}
]
}
Commands
A Command is the execution state of a scheduled action.
| Endpoint | Description |
|---|---|
POST {url}/instruments/{uid}/commands |
Schedules an action for immediate execution, thereby creating a command. |
GET {url}/instruments/{uid}/commands |
Returns all commands for a given instrument. |
GET {url}/instruments/{uid}/commands/{cid} |
Returns a specific command. |
POST {url}/instruments/{uid}/commands/{cid}/kill |
Aborts the specified command, if it is currently running. |
DELETE {url}/instruments/{uid}/commands/{cid} |
Aborts and deletes a command. |
Command Attributes
| Attribute | Description |
|---|---|
id |
Unique identifier of the command |
objectId |
Unique identifier of the parent instrument |
createdBy |
User who executed the command |
createdAt |
Date when the command was created |
updatedAt |
Date when the command was last updated |
payload |
Name of the action that was scheduled to execute |
values |
List of parameter values for the specified action. For example:
[
{
"parameterId": "Time",
"value": "15s"
},
{
"parameterId": "RPM",
"value": "500"
}
] |
status |
running, success, or failure |
output |
[Optional] Stdout/stderr output from the executed command |
message |
[Optional] User friendly success message |
error |
[Optional] Error message if status is set to failure |
results |
[Optional] JSON result data returned by the command |
Command Execution Example
To execute the
set_timed_shake action, which has a Time and RPM parameter, POST the following payload to {url}/instruments/{uid}/commands:
{
"action": "set_timed_shake",
"values": [
{
"parameterId": "Time",
"value": "15s"
},
{
"parameterId": "RPM",
"value": "500"
}
]
}
The API will return a Command object with its
status set to running. You can poll for its execution status with GET {url}/instruments/{uid}/commands/{cid} or abort it with POST {url}/instruments/{uid}/commands/{cid}/kill. 
