1 The Kilobaser API

Every Kilobaser on a network serves a REST API on the same address and the same login as its web interface. Anything you can do from that interface, you can do from a program: put oligos in the synthesis queue, start them, answer the machine's questions, and follow what it is doing as it happens.

This guide is written for someone connecting another system to the Kilobaser — a LIMS, an ordering portal, an assay design tool — and it is built around a worked example carried from beginning to end. Every request and response you will read was captured from a running device, not written by hand.

1.1 What you can do with it

You want to	Start here
Send one oligo to the queue	quickstart
Send a whole assay at once	queue oligos
Say which cartridge and chip an oligo needs	synthesis model
Work out how to group a mixed batch	plan a batch
Start a run and answer the machine	run lifecycle
Show live progress in your own application	live state
Cancel, or deal with an error	cancel and errors
Look up an endpoint	endpoint reference
Understand an error code	error codes

1.2 What it cannot do

The API drives the software, not the hardware. Somebody still has to stand at the Kilobaser: chips and cartridges are put in by hand and the collection vial is placed and removed by hand. The lid and the cartridge move under motor control, but they never move until a person confirms it — which is what the checkpoint questions are. What the API can do is tell the machine that those things have been done, which is what the checkpoint questions in run lifecycle are for.

So a realistic integration fills the queue automatically and leaves a person to run the Kilobaser, or fills the queue and drives it while somebody is present. It cannot synthesize unattended.

This guide does not repeat how the Kilobaser is handled. For inserting chips and cartridges, placing the collection vial and collecting the product, see Operation in the Kilobaser manual.

Two further limits worth knowing before you design anything:

A browser cannot talk to the device directly for live updates. Ordinary requests work cross-origin, but the event stream does not. See Choosing where your code runs, below.
Sessions do not survive a device restart. They are held in memory. Any long-lived client has to expect to log in again; see connect and authenticate.

1.3 How much of this you need

Integrations divide fairly cleanly into three depths. Decide which one you are building before you read further, because the second half of this guide only matters for the third.

	What it does	What it has to keep track of
Submit	Puts oligos in the queue. A person starts and runs them at the Kilobaser.	Nothing. Each call stands alone.
Submit and observe	Also shows progress back in your own application.	A copy of the queue and the machine status, kept current from the event stream.
Drive	Also starts runs, answers the machine, cancels, and recovers from errors.	The above, plus where each run has got to and what it is waiting for.

Submitting is a few dozen lines and is covered by quickstart and queue oligos. Observing adds live state. Driving adds run lifecycle and cancel and errors, and is a genuinely different piece of software: the machine stops and asks questions, so the client has to be a state machine rather than a sequence of calls.

Most people should start by submitting, and add the rest when they find they want it.

1.4 Choosing where your code runs

Put the code that talks to the Kilobaser in your backend. Not in a browser, and not in a user's desktop application.

The immediate reason is technical. The device allows cross-origin requests to the REST API, so a web page on another domain can log in and queue oligos. But /api/subscribe, the live event stream, sends no cross-origin headers, so a browser cannot open it from another domain. If you want live updates — and anything beyond fire-and-forget submission does — the connection has to be made from a server.

The other reasons are ordinary good sense. Devices ship with a self-signed certificate, which a browser will refuse until each user clicks through a warning. There is one account per person, not per application, so a browser client would be asking every user for Kilobaser credentials. And a queue is shared: two of your users submitting at once are submitting to the same machine, which is much easier to reason about in one place.

So the shape that works is your application talking to your backend, and your backend holding one session with the Kilobaser.

1.5 What you need to get started

The Kilobaser on your network, with device visibility switched on. Remote access is off until somebody enables it at the touchscreen. See connect and authenticate.
An open gas supply. The Kilobaser cannot synthesize without it, and it must stay open whenever a chip is inserted.
An account on the device. The same username and password used for the web interface. A user account can do everything in this guide except manage other accounts and change security settings; those need an admin.
The device's address. Examples here use kilobaser.lab.example.org; substitute your own hostname or IP.

Everything in this guide was verified against software version 1.5. Check what you are running with GET /api/settingsUser/systemInformation, and mention that version if you contact support.

1.6 The example used throughout

One assay is carried through every chapter: LAMP-042, a six-primer LAMP set against RPP30, plus a dual-labeled detection probe.

Oligo	Length	Product
`LAMP-042_RPP30-F3`	18 nt	unmodified
`LAMP-042_RPP30-B3`	18 nt	unmodified
`LAMP-042_RPP30-FIP`	42 nt	unmodified
`LAMP-042_RPP30-BIP`	43 nt	unmodified
`LAMP-042_RPP30-LF`	20 nt	unmodified
`LAMP-042_RPP30-LB`	21 nt	unmodified
`LAMP-042_RPP30-P`	24 nt	5' 6-FAM, 3' BHQ-1

It was chosen because it is awkward in the two ways that real orders are awkward. The six primers come to 162 bases, which does not fit the 150 bases of a standard cartridge. And the probe needs a different cartridge and a different chip from everything else, which is what makes plan a batch worth reading.

The sequences are illustrative. They are not a validated assay and should not be ordered for laboratory use.

1.7 Example code

The guide is written around a small Python client that you can download and run:

File	What it is
kb_client.py	the shared library everything else uses
kb_watch.py	prints what the machine is doing, live; read only
kb_queue_assay.py	groups a FASTA file into pools and queues it
kb_run_head.py	starts a run and answers the machine
kb_lamp_primers.fasta	the example assay

They need Python 3 and requests, and nothing else. Curl examples in the text show the same calls without the library, so you can follow along in any language.

1.8 What this guide does not cover

The device has a second set of endpoints used by Kilobaser to develop and service the Kilobaser — /api/processes, /api/protocols, /api/runs, /api/ccsettings, /api/instructions and /api/settings. They are visible in older reference material, but they are restricted to developer accounts, they are not part of the supported interface, and they change without notice. Nothing in this guide needs them.