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.


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

idUnique identifier of the object.
nameUser given name. The name doesn’t need to be unique.
descriptionUser given description of the object.
createdByUser who created this object
createdAtDate when the object was created (e.g. 2022-04-07T15:25:53.429Z)
updatedByUser who last updated the object
updatedAtDate when the object was last updated
tagsUser settable set of tags
aclAccess control list specifies the level of access various roles have on this object.


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.

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 is accomplished by passing in a sort query parameter.

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


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

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


Projections are accomplished by passing in a fields query parameter.

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


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

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

Status Codes

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

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

Error Messages

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

codeHTTP Status Code (e.g., 400)
messageUser readable error message.
detailsOptional technical details regarding the error, such as a stack trace.
Ready to unleash Genie in your lab?