API overview

Habitat exposes its hardware operations through multiple interfaces. All interfaces provide equivalent access to the same underlying hardware — choose the one that fits your environment.

Interface	Status	Best for
REST	Available	Any language, curl, HTTP clients
Python (openculture)	Available	Python workflows, typed SDK
MCP	Available	AI agents — drive it in natural language

REST conventions

Habitat's REST API is served by FastAPI. All endpoints accept and return JSON.

Base URL

Each Habitat device serves its API on your local network at http://<device-name>.local:8000/ — for example http://mistyforest.local:8000/. Replace mistyforest with your device's name (ask your Open Culture contact if you're unsure). All examples in these docs use the demo device mistyforest.

Authentication

Habitat runs on your local network. Depending on how your device is provisioned, the REST API may be open or may require an API token — check with your Open Culture contact. If your device is token-protected, send the token as a Bearer header:

Authorization: Bearer <your-token>

The MCP connector authenticates separately, through its own sign-in.

Units

• Volumes are always in microliters (µL). Field suffix: _ul.
• Volumes at the API and action layer are floats. Drivers convert to hardware-specific increments internally.
• Time is reported in seconds where applicable.

Pump addresses

Pump addresses are zero-indexed integers. /pumps/{addr} expects the integer address. The pump role (dispense / aspirate) is defined in the YAML config, not inferred from the address.

Error responses

Failures come back as application/problem+json with type, title, status, and detail fields — plus structured context (addr, chip_id, step) where relevant.

Status	Meaning
400	Invalid parameters, or a precondition wasn't met
404	Unknown resource (pump, job, protocol, …)
409	Conflict — a safety interlock blocked the command, or an idempotency key was reused with a different body
422	Request body failed schema validation
500	Hardware-level failure

System & configuration endpoints

Read-only status and configuration live at the root of the API.

Method	Endpoint	Purpose
GET	/health	Device identity and driver status
GET	/system/status	Runtime status
GET	/system/metrics	Per-route latency metrics
GET	/system/timezone	Display timezone
GET	/config	Full configuration snapshot (includes the port map)
GET	/config/schema	JSON Schema for the configuration

See Configuration for the port map the snapshot contains.

Python SDK namespaces

The openculture package wraps the full public REST surface — 99 endpoints across 13 namespaces. Each REST tag maps to a sub-client on HabitatClient.

from openculture import HabitatClient

with HabitatClient("http://mistyforest.local:8000") as h:
    h.system        # health, status, metrics, timezone
    h.config        # read the device configuration
    h.pumps         # CENTRIS syringe pumps
    h.valves        # multi-position smart valves
    h.peristaltic   # peristaltic pumps
    h.atomics       # primitive operations
    h.routines      # multi-step workflows
    h.protocols     # protocol library + authoring
    h.schedule      # event scheduling
    h.jobs          # job submission and status
    h.reagents      # reagent registry
    h.environmental # CO₂ / temperature / humidity
    h.devices       # device registry

Namespace	Endpoints	Covers
h.system	10	Health, runtime status, info, capabilities, metrics, timezone
h.config	2	Read the configuration snapshot and its JSON Schema
h.pumps	19	CENTRIS syringe pump control
h.valves	11	SmartValve multi-position control
h.peristaltic	16	Peristaltic pump control
h.atomics	3	List and run primitive operations
h.routines	10	List and run routines; author your own
h.protocols	9	Protocol library, user-protocol CRUD, validation, run
h.schedule	6	Event scheduling — queue, inspect, cancel
h.jobs	5	Job submission and status
h.environmental	5	CO₂ / temperature / humidity sensor
h.devices	2	Device registry
h.reagents	1	Reagent registry

All request and response shapes are exported from openculture.client.habitat.models. Use dir(h.<namespace>) to list available methods.

Endpoint reference

The full endpoint surface is grouped by area — each page shows all interfaces side by side:

• System — device health and status
• Pumps — CENTRIS syringe pump control
• Peristaltic — Pololu Tic peristaltic pumps
• Valves — multi-position smart valves
• Atomics — single-step primitives
• Routines — multi-step workflows
• Protocols — protocol library and execution
• Schedule — event scheduling
• Jobs — job submission and status
• Devices — device registry and telemetry
• Environmental — CO₂ / temperature / humidity
• Reagents — reagent registry
• Config — device configuration

Or explore the whole REST surface interactively in Try it.