LabOS Instrument API - Genie Life Sciences

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.

Resources