LabOS REST API

Overview

This document is the starting point for understanding and using Genie’s Public API. Note that a Premium account is required to access Genie’s Public API.

API Token

You first need to generate an API Token. Simply login to the Genie platform and navigate to Preferences > Manage API Tokens. From this screen, generate a new token and download it as a token.txt file. Do not share your API token with anyone and always store it in a secure location. Anybody in possession of your API token can make REST API requests as you. The remainder of this document will refer to the API token (e.g., the contents of token.txt) as {token}. Genie’s API tokens are Bearer tokens and must be sent in the Authorization HTTP header with every REST request.

Write down the Public API URL displayed above the tokens table. The remainder of this document will refer to it as {url}.

Discovery Service

Genie’s cloud platform has an extensive Private API and we are continuously converting selected parts of these API endpoints to a Public API. The main difference between the Private and Public API is that Genie only guarantees backward compatibility for its Public API.

You can use the Discovery Service to enumerate all of the current Public API endpoints. Below is a simple example on how to use your {token} to interact with the Discovery Service.

Request / Response

GET {url}/discover returns all the available Public API endpoints:

method is the HTTP method supported by the REST API endpoint
: in the URL path (e.g., /:id/) indicates a parameter – often a unique identifier
? in the URL path (e.g., /:id?) indicates that the preceding parameter is optional. For example, "path": "/public/v1/instruments/:id?" allows for the following REST calls:
- GET /public/v1/instruments/ to return all instruments
- GET /public/v1/instruments/6458048287f19b42eb065089 to return a specific instrument

				
					{
    "data": [
        {
            "method": "GET",
            "path": "/public/v1/instruments/:id?"
        },
        {
            "method": "GET",
            "path": "/public/v1/instruments/:id/commands/:cid?"
        },
        {
            "method": "POST",
            "path": "/public/v1/instruments/:id/commands"
        },
        {
            "method": "POST",
            "path": "/public/v1/instruments/:id/commands/:cid/kill"
        },
        {
            "method": "GET",
            "path": "/public/v1/instruments/:id/actions/:aid?"
        }
    ]
}

Python Example

				
					from json import dumps
from requests import get
 
def discover(url: str, token: str) -> None:
    path = f'{url}/discover'
    headers = {'Authorization': f'Bearer {token}',
               'Content-type': 'application/json'}
    resp = get(path, headers=headers).json()
    print(dumps(resp, indent=4, sort_keys=True))

cURL Example

				
					curl -s -H "Content-type: application/json" -H "Authorization: Bearer ${TOKEN}" "${URL}/discover"

Common Patterns

This section describes a set of common patterns followed by most of Genie’s REST API endpoints.

Attributes

Objects returned by most of the REST services have at least the following attributes:

Attribute	Description
`id`	Unique identifier of the object.
`name`	User given name. The name doesn’t need to be unique.
`description`	User given description of the object.
`createdBy`	User who created this object
`createdAt`	Date when the object was created (e.g. `2022-04-07T15:25:53.429Z`)
`updatedBy`	User who last updated the object
`updatedAt`	Date when the object was last updated
`tags`	User settable set of tags
`acl`	Access control list specifies the level of access various roles have on this object.

CRUD

Most REST services follow a common CRUD pattern. The request URL includes the service type ( {type} below), which signifies the type of object to create, read, update or delete.

Endpoint	Description
`GET {url}/{type}`	Retrieves a list of objects
`GET {url}/{type}/{uid}`	Retrieves a specific object
`POST {url}/{type}`	Creates a new object and returns it
`PUT {url}/{type}/{uid}`	Replaces the specified object in its entirety. This action isn’t supported by all services but when supported it is idempotent.
`DELETE {url}/{type}/{uid}`	Deletes the specified object. This action is idempotent – it will return success whether an object was deleted or didn’t exist to begin with.
`PATCH {url}/{type}/{uid}`	Updates parts of the specified object. This action isn’t supported by all services.

Read Parameters

All top level GET calls (e.g., GET /public/v1/instruments/) support filtering, sorting, paging, and projections via URL parameters.

Sorting

Sorting is accomplished by passing in a sort query parameter.

Request	Description
`{url}/instruments?sort=name`	Retrieves all of the instruments and sorts them ascending by name
`{url}/instruments?sort=-name`	Retrieves all of the instruments and sorts them descending by name
`{url}/instruments?sort=name,-updatedAt`	Retrieves all of the instruments, first sorting ascending by name and then descending by `updatedAt`

Paging

Paging is accomplished through a combination of the limit and skip query parameters.

Request	Description
`{url}/instruments?limit=10&sort=name`	Retrieves the first 10 instruments sorted by name
`{url}/instruments?limit=10&skip=10&sort=name`	Retrieves the second group of 10 instruments (skipping the first 10), sorted by name

Projections

Projections are accomplished by passing in a fields query parameter.

Request	Description
`{url}/instruments?fields=name,description`	Retrieves all of the instruments but only populates the name and description fields. Note that the `id` field is always populated.

Filtering

Filtering is accomplished by passing in the name of the field you want to filter on as a query parameter.

Request	Description
`{url}/instruments?updatedAt>2023-05-01`	Retrieves all instruments updated after 2023-05-01 (May 1, 2023)
`{url}/instruments?family=@LiquidHandler`	Retrieves all liquid handlers
`{url}/instruments?actions.action=prime`	Retrieves all instruments that have an action called “prime”

Status Codes

Genie’s REST API return one of the following HTTP status codes

Code	Description
200	Standard response for successful HTTP requests.
201	The request has been fulfilled, resulting in the creation of a new resource
204	Request succeeded but no data is returned, such as during a `DELETE` call
400	Request rejected because it is invalid (e.g., malformed)
403	Request rejected because user isn’t authorized to make this request
404	Request rejected because the requested object could not be found
500	Internal server error while processing the request

Error Messages

4xx status codes are accompanies by an error message object with the following attributes:

Attribute	Description
`code`	HTTP Status Code (e.g., `400`)
`message`	User readable error message.
`details`	Optional technical details regarding the error, such as a stack trace.