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:

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.


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

Book a Demo

Genie is now in limited Beta. Complete the form below and one of our sales representitives will reach out to you within 24 hours to setup an in-person demo of our platform.