1 Quickstart

This assumes remote access is already switched on at the Kilobaser. If the first call does not connect, start at connect and authenticate.

1.1 Log in

curl --insecure -c cookies.txt \
  -X POST https://kilobaser.lab.example.org/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username": "apibot", "password": "..."}'

{
  "id": "55d56ae5-6484-44f2-9f60-2b75fa3f0b96",
  "expiresAt": "2026-09-09T22:08:26.625789374Z",
  "user": { "id": "apibot", "name": "Robot", "role": "user" }
}

The session is a cookie, saved here in cookies.txt and sent with -b from now on. --insecure is needed because the device's certificate is self-signed; see connect and authenticate for how to stop doing that.

1.2 Queue an oligo

curl --insecure -b cookies.txt \
  -X POST https://kilobaser.lab.example.org/api/processRuns/queue \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "LAMP-042_RPP30-F3",
    "processType": "synthesis",
    "cartridgeType": "2",
    "chipKind": "2",
    "answers": { "sequence": "GACCTGCTAGATCGTACG" }
  }'

cartridgeType 2 and chipKind 2 are the standard cartridge and standard chip, which is what an unmodified oligo needs. Synthesis model covers the rest.

The Content-Type header is not optional — without it the request is rejected with 415.

1.3 Find what you queued

The response to that POST does not include the new entry's id. Read the queue to get it:

curl --insecure -b cookies.txt https://kilobaser.lab.example.org/api/init \
  | jq '.processRunQueue[] | {id, priority, title, processTypes}'

{
  "id": "2026-08-09T22:05:25Z-0be17442",
  "priority": 1,
  "title": "LAMP-042_RPP30-F3",
  "processTypes": ["insertChip", "cartridgeInit", "cartridgeActivate",
                   "initializeSystem", "insertChip", "synthesis"]
}

processTypes is the machine telling you what it will actually do. Six steps here, because this machine has just been switched on and has to set itself up first; a second oligo behind this one would show two.

That is the whole submission path. If your integration only needs to send work to the Kilobaser, you are done — somebody starts it at the touchscreen. Everything below is for integrations that drive the machine as well.

1.4 Start it

curl --insecure -b cookies.txt \
  -X POST https://kilobaser.lab.example.org/api/processRuns \
  -H 'Content-Type: application/json' \
  -d '{"id": "2026-08-09T22:05:25Z-0be17442"}'

Only the first entry in the queue can be started.

1.5 Answer the machine

The machine will stop and wait for someone. Ask it what for:

curl --insecure -b cookies.txt https://kilobaser.lab.example.org/api/status \
  | jq '{mode: .currentState.mode, pendingAnswers, currentProcessRunId}'

{
  "mode": "check",
  "pendingAnswers": ["placeholderInsertConfirmed"],
  "currentProcessRunId": "2026-08-09T22:05:25Z-0be17442"
}

mode is check and there is a pending answer: the machine is waiting. Once the thing it is asking about has actually been done, confirm it:

curl --insecure -b cookies.txt \
  -X PUT https://kilobaser.lab.example.org/api/processRuns/2026-08-09T22:05:25Z-0be17442/control \
  -H 'Content-Type: application/json' \
  -d '{"answers": {"placeholderInsertConfirmed": "true"}}'

Then it carries on until the next checkpoint, and you repeat. Note that "true" is a string.

Polling /api/status is fine for a first look and wrong for real use — subscribe to the event stream instead, see live state.

1.6 The same thing in Python

from kb_client import Kilobaser

kb = Kilobaser("kilobaser.lab.example.org", "apibot", "...", verify=False)
kb.login()

entry = kb.queue_oligo("LAMP-042_RPP30-F3", "GACCTGCTAGATCGTACG")
print(entry["id"], "->", " -> ".join(entry["processTypes"]))

kb.start(entry)

kb_client.py handles the session cookie, unwraps error messages into something readable, and reads the queue back for you. The rest of this guide uses it.

1.7 Where to go next

Sending a whole assay in one call: queue oligos
Which cartridge and chip an oligo needs: synthesis model
A mixed batch with modifications: plan a batch
Live progress instead of polling: live state