System

RESTPython

Every operation is a standard JSON-over-HTTP request. The full endpoint reference is below; try requests live from Try it.

Namespace: h.system — install with pip install openculture.

The openculture SDK is a typed REST client — it calls the same endpoints as the REST tab.

from openculture import HabitatClient

with HabitatClient("http://mistyforest.local:8000") as h:
    # Health
    h.system.health()
    # Healthz
    h.system.healthz()
    # Readyz
    h.system.readyz()
    # Capabilities
    h.system.capabilities()
    # Get System Events
    h.system.get_system_events()
    # Info
    h.system.info()
    # Metrics
    h.system.metrics()
    # Schema
    h.system.schema()
    # Status
    h.system.status()
    # Get Timezone
    h.system.get_timezone()

Endpoint reference

Habitat API — system 0.1.0

REST API for the Habitat tissue-culture automation platform by Open Culture Science. All endpoints accept and return JSON.

---

system

---

GET /health

Health

Responses

200 OK

application/json

Schema of the response body

---

GET /system/info

Info

Description

Return device identity and uptime metadata.

Responses

200 OK

application/json

Schema of the response body

{
    "additionalProperties": true,
    "type": "object",
    "title": "Response Info System Info Get"
}

---

GET /system/status

Status

Description

Return an aggregate health snapshot of the running system.

kinds is a dict mapping kind name to a list of per-instance entries. In phase A.3 the list contains exactly one entry (the kind-level summary) with instance_count=0 as a sentinel. Phase A.5 replaces this with real per-instance data.

Responses

200 OK

application/json

Schema of the response body

{
    "additionalProperties": true,
    "type": "object",
    "title": "Response Status System Status Get"
}

---

GET /system/metrics

Metrics

Description

Latency observability snapshot.

Default: the live in-process registry (per-route percentiles, in-flight, recent slow requests) plus the SSE slow-consumer drop count. With ?history=true returns stored request_metrics rollup windows (filterable by route template and since).

Input parameters

Parameter	In	Type	Default	Nullable	Description
history	query	boolean	False	No
limit	query	integer	200	No
route	query			No
since	query			No

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

{
    "type": "object",
    "additionalProperties": true,
    "title": "Response Metrics System Metrics Get"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /system/capabilities

Capabilities

Description

Return a kinds-aware capability tree from DEVICE_REGISTRY.

instance_count and instances reflect live driver state when instances_getter is wired (production app factory). In test builds that build their own minimal app and skip the getter, both fields fall back to empty/zero so smoke tests remain stable.

Responses

200 OK

application/json

Schema of the response body

{
    "additionalProperties": true,
    "type": "object",
    "title": "Response Capabilities System Capabilities Get"
}

---

GET /system/schema

Schema

Description

Redirect to FastAPI's auto-generated OpenAPI JSON document.

Responses

200 OK

application/json

Schema of the response body

---

GET /system/events

Get System Events

Description

Stream the firehose system channel as Server-Sent Events.

StreamManager.publish fans every per-channel event out to the system channel, so this endpoint surfaces every job lifecycle event, every device telemetry event, and every other system-level event in a single stream.

Honors Last-Event-ID for replay strictly after the given id (or full buffer when the id is unknown / evicted). Treats a missing Last-Event-ID as an empty string so first-time connects replay the full ring buffer before going live, matching :func:get_job_events.

?type=foo,bar restricts the stream to events whose type matches one of the listed values; whitespace around each entry is stripped. When type is omitted (or empty) every event is emitted.

Input parameters

Parameter	In	Type	Default	Nullable	Description
type	query			No	Comma-separated list of event types to include

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /healthz

Healthz

Description

Liveness probe — always 200 if the ASGI app is reachable.

Responses

200 OK

application/json

Schema of the response body

{
    "additionalProperties": {
        "type": "string"
    },
    "type": "object",
    "title": "Response Healthz Healthz Get"
}

---

GET /readyz

Readyz

Description

Readiness probe — 200 when drivers are initialized, 503 otherwise.

Deployment orchestrators (Kubernetes, ECS, Docker Compose healthcheck) poll this endpoint before routing traffic.

Responses

200 OK

application/json

Schema of the response body

{
    "additionalProperties": true,
    "type": "object",
    "title": "Response Readyz Readyz Get"
}

---

GET /system/timezone

Get Timezone

Description

Return the device's configured display timezone.

Logs and audit rows always store UTC timestamps for consistency, but they also capture the display timezone that was active when the entry was written. The GUI uses this value to format timestamp for human readers; agents reading /logs can format the same way or stay in UTC.

See PUT /system/timezone to change it.

Responses

200 OK

application/json

Schema of the response body

{
    "additionalProperties": true,
    "type": "object",
    "title": "Response Get Timezone System Timezone Get"
}

---

Schemas

AbsoluteMoveRequest

Name	Type	Description
position_increments		Absolute position in increments
position_ul		Absolute position in microliters
top_speed_ul_per_s		Optional top plunger speed in µL/s to apply before the move. When omitted, the firmware's previously-set speed is used.

AtomicCallRequest

Name	Type	Description
params		Atomic parameters keyed by the names declared in the manifest.

AtomicManifest

Name	Type	Description
authored_by	string
belongs_to_routines	Array<string>
blocking
description	string
device_kind	string
emits_metrics	Array<string>	Advisory list of metric names this atomic is expected to emit. Not populated by any atomic today and not enforced or cross-checked against the telemetry layer -- agent-read-only metadata, not a live emission guarantee.
estimated_fluid_volume_ul
estimated_wear	string	Advisory relative wear estimate. Not derived from any measurement and not read by the runtime -- agent-read-only metadata for planning, not a calibrated cost model.
expected_duration_ms
failure_modes	Array<FailureMode>
hazards	Array<Hazard>
idempotent	boolean
interrupted_state	string
kind	string
last_calibrated
mutates	Array<string>
name	string
params	Array<ParamSpec>
postconditions	Array<Postcondition>
preconditions	Array<Precondition>
requires_human_confirmation	boolean
requires_state
reverse_atomic		Advisory pointer to the atomic that would undo this one. Not populated by any atomic today and not enforced or invoked by the runtime -- agent-read-only metadata, not a guarantee a reverse operation exists or is registered.
reversible	boolean
side_effects	Array<string>
summary	string
tier	string
typical_predecessors	Array<string>
typical_successors	Array<string>
validated_on_hardware	Array<string>
version	string

CreateEventRequest

Name	Type	Description
action	string	Action type (e.g. 'feed', 'wash')
color	string
duration_min	number
notes	string
parameters
sample_id	string	Target sample ID
series_id
start_time	string	Scheduled start (ISO 8601)

CurrentLimitRequest

Name	Type	Description
current_limit_ma	integer	Current limit in mA (Tic 36v4 max: 4000)

DeviceRef

Name	Type	Description
id	string
kind	string

DoseRequest

Name	Type	Description
block	boolean	Wait for motion to complete before returning
direction	FlowDirection	Flow direction
volume_ml	number	Volume to pump in mL

ExecuteRoutineRequest

Name	Type	Description
params		Routine parameters keyed by the names declared in the manifest.

FailureMode

Name	Type	Description
error_class	string
recommended_recovery	Array<RecoveryStep>
when	string

FlowDirection

Type: string

ForeachBlock-Input

Name	Type	Description
as_var	string	Loop variable name. Body placeholders ``{}`` are replaced with the current element on each iteration.
list_param	string	Placeholder name (without braces) for the list parameter, e.g. 'samples' resolves to the value of bound_params['samples'].
steps	Array<RoutineStep-Input>	Step body executed once per list element.

ForeachBlock-Output

Name	Type	Description
as_var	string	Loop variable name. Body placeholders ``{}`` are replaced with the current element on each iteration.
list_param	string	Placeholder name (without braces) for the list parameter, e.g. 'samples' resolves to the value of bound_params['samples'].
steps	Array<RoutineStep-Output>	Step body executed once per list element.

habitat__models__centris__CommandResponse

Name	Type	Description
addr	integer
data
error_code	integer
error_message	string
message	string
success	boolean

habitat__models__centris__InitDirection

Type: string

habitat__models__centris__InitRequest

Name	Type	Description
direction	habitat__models__centris__InitDirection
init_gap_increments		Optional one-shot post-init plunger gap in increments. If provided, ``set_init_gap`` is called BEFORE the Z command on this initialization only. ``None`` means use the previously-configured gap (firmware default ~1600 if never set). DANGER: see ``POST /pumps/{addr}/init-gap`` for hazard details. This path requires ``gap_increments >= 100`` (the safety floor) — there is no override field on this endpoint. Use the dedicated ``/init-gap`` endpoint with ``override_safety_floor=true`` if you must persist a sub-floor value before initialization.
input_port	integer	Distribution-valve input port for homing. Use ``0`` (or omit) for auto-selection from the pump YAML ``port_map``: first waste role, else first port not listed in the map, else port 1. JSON may use the field name ``init_port`` as an alias.
output_port	integer	Init output port (0=default)
speed	integer	Init speed code

habitat__models__peristaltic__CommandResponse

Name	Type	Description
error
message	string
pump_name	string
success	boolean

habitat__models__smartvalve__CommandResponse

Name	Type	Description
addr	integer
data
error_code	integer
error_message	string
message	string
success	boolean

habitat__models__smartvalve__InitDirection

Type: string

habitat__models__smartvalve__InitRequest

Name	Type	Description
direction	habitat__models__smartvalve__InitDirection
input_port	integer	Init input port (0=default)
output_port	integer	Init output port (0=default)
speed	integer	Init speed code

Hazard

Name	Type	Description
agent_guidance	string
condition	string
id	string
severity	string

HTTPValidationError

Name	Type	Description
detail	Array<ValidationError>

Job

Name	Type	Description
cancel_requested	boolean
created_at	string(date-time)
created_by
error
finished_at
id	string
idempotency_key
params
parent_id
progress
request_id	string
result
started_at
status	JobStatus
targets	Array<DeviceRef>
type	string

JobProgress

Name	Type	Description
current_step	string
note
step_index
total_steps

JobStatus

Type: string

JobSubmissionBody

Name	Type	Description
params		Runnable-specific request body
targets		Optional list of device references the job acts on. If omitted, the runnable receives an empty target list.
type	string	Registered runnable name (e.g. 'actions.wash')

LoopBlock-Input

Name	Type	Description
count		Iteration count. Integer literal or ``{}`` resolved against the routine scope at run time.
steps	Array<RoutineStep-Input>	Step body executed once per iteration.

LoopBlock-Output

Name	Type	Description
count		Iteration count. Integer literal or ``{}`` resolved against the routine scope at run time.
steps	Array<RoutineStep-Output>	Step body executed once per iteration.

MoveRequest

Name	Type	Description
block	boolean	Wait for motion to complete before returning
relative	boolean	If True, move relative to current position. If False, absolute.
steps	integer	Number of microsteps (positive = forward, negative = reverse)

ParallelBlock-Input

Name	Type	Description
steps	Array<RoutineStep-Input>	Steps executed concurrently.

ParallelBlock-Output

Name	Type	Description
steps	Array<RoutineStep-Output>	Steps executed concurrently.

ParamSpec

Name	Type	Description
default
name	string
range
required	boolean
semantic_role	string
type	string
unit

PeristalticStatus

Name	Type	Description
current_limit_ma
current_position	integer
current_velocity	integer
energized	boolean
errors	string
flow_rate_ul_min	number
max_speed
name	string
operation_state	string
planning_mode	string
ready	boolean
serial_number
step_mode	integer
target_position	integer
vin_voltage

PlungerMoveRequest

Name	Type	Description
increments		Position in increments
volume_ul		Volume in microliters

Postcondition

Name	Type	Description
description	string
state

Precondition

Name	Type	Description
check_id	string
description	string
on_fail_atomic

PrimeRequest

Name	Type	Description
seconds	number	Duration to run in seconds (max 5 minutes)
velocity	integer	Velocity in microsteps per 10,000 seconds

ProblemDetails

Name	Type	Description
detail
instance
request_id
status	integer	HTTP status code
title	string	Short human-readable summary
type	string	Problem type URI

ProtocolDefaults

Name	Type	Description
chip_id
pump_name
sample_id
speed_code
timeout_s

ProtocolManifest

Name	Type	Description
author	string
color
composes_atomics	Array<string>
composes_routines	Array<string>
created_at
defaults	ProtocolDefaults
description	string
device_kinds	Array<string>
device_name
emits_metrics	Array<string>
estimated_duration_ms
estimated_wear	string
failure_modes	Array<FailureMode>
file_path
hazards	Array<Hazard>
icon
last_calibrated
library	string
name	string
params	Array<ParamSpec>
postconditions	Array<Postcondition>
preconditions	Array<Precondition>
requires_human_confirmation	boolean
requires_state
schedule_items	Array<ProtocolScheduleItem>
scope	string
side_effects	Array<string>
status	string
summary	string
tags	Array<string>
tier	string
updated_at
validated_on_hardware	Array<string>
version	string

ProtocolPlan

Name	Type	Description
anchor_time	string
bound_params
ended_at
protocol_name	string
protocol_version	string
run_id	string
started_at	string(date-time)
status	string
step_results	Array<ScheduleSubmission>
submissions	Array<ScheduleSubmission>

ProtocolScheduleItem

Name	Type	Description
atomic
item_id	string
label	string
params
routine
sample_id
schedule	ScheduleSpec

PumpStatus

Name	Type	Description
addr	integer
cutoff_speed_inc_per_s	integer
error_code	integer
error_message	string
firmware
initialized	boolean
name	string
operating_time_min
plunger_position_increments	integer
plunger_position_ul
ready	boolean
start_speed_inc_per_s	integer
syringe_volume_ul	integer
temperature_f
top_speed_inc_per_s	number
valve_position	integer
valve_type	string
voltage

QueryResponse

Name	Type	Description
addr	integer
parsed_value
raw_value	string
register		Register identifier

RecoveryStep

Name	Type	Description
atomic_name	string
delay_ms_between_attempts	integer
expected_postcondition
max_attempts	integer
params
rationale	string
verify_with

RoutineManifest-Input

Name	Type	Description
authored_by	string
blocking	boolean
chip_aware	boolean
composes	Array<string>
created_at
description	string
device_kinds	Array<string>
device_name
emits_metrics	Array<string>
estimated_fluid_volume_ul
estimated_wear	string
expected_duration_ms
failure_modes	Array<FailureMode>
file_path
hazards	Array<Hazard>
idempotent	boolean
interrupted_state	string
last_calibrated
library	string
mutates	Array<string>
name	string
params	Array<ParamSpec>
postconditions	Array<Postcondition>
preconditions	Array<Precondition>
requires_human_confirmation	boolean
requires_state
reversible	boolean
side_effects	Array<string>
steps	Array<RoutineStep-Input>
summary	string
tier	string
typical_predecessors	Array<string>
typical_successors	Array<string>
updated_at
validated_on_hardware	Array<string>
version	string

RoutineManifest-Output

Name	Type	Description
authored_by	string
blocking	boolean
chip_aware	boolean
composes	Array<string>
created_at
description	string
device_kinds	Array<string>
device_name
emits_metrics	Array<string>
estimated_fluid_volume_ul
estimated_wear	string
expected_duration_ms
failure_modes	Array<FailureMode>
file_path
hazards	Array<Hazard>
idempotent	boolean
interrupted_state	string
last_calibrated
library	string
mutates	Array<string>
name	string
params	Array<ParamSpec>
postconditions	Array<Postcondition>
preconditions	Array<Precondition>
requires_human_confirmation	boolean
requires_state
reversible	boolean
side_effects	Array<string>
steps	Array<RoutineStep-Output>
summary	string
tier	string
typical_predecessors	Array<string>
typical_successors	Array<string>
updated_at
validated_on_hardware	Array<string>
version	string

RoutineStep-Input

Name	Type	Description
atomic
delay_after_ms	integer
foreach
label	string
loop
max_retries	integer
on_error	string
parallel
params
routine

RoutineStep-Output

Name	Type	Description
atomic
delay_after_ms	integer
foreach
label	string
loop
max_retries	integer
on_error	string
parallel
params
routine

RoutineValidationReport

Name	Type	Description
is_valid	boolean
issues	Array<ValidationIssue>
manifest

RunProtocolRequest

Name	Type	Description
bound_params		Bindings for the protocol's declared params.

ScheduleSpec

Name	Type	Description
duration_min
event_duration_min
interval_min
kind	string
offset_min

ScheduleSubmission

Name	Type	Description
atomic
duration_ms	integer
error
event_id	string
fire_at	string
job_id
label	string
params
routine
status	string
step_id	string
step_index	integer
target_kind	string
target_name	string

SensorListEntry

Name	Type	Description
connected	boolean
driver_mode	string
id	string
label	string

SensorListResponse

Name	Type	Description
sensors	Array<SensorListEntry>

SensorReading

Name	Type	Description
co2_pct
humidity_pct
sample_count	integer
sample_rate_hz	number
temperature_c
timestamp
warming_up	boolean

SensorStatus

Name	Type	Description
connected	boolean
csv_path
driver_mode	string
id	string
label	string
last_reading_at
malformed_frame_count	integer
port
sample_count	integer
sample_rate_hz	number
warming_up	boolean

SpeedConfigRequest

Name	Type	Description
max_accel		Maximum acceleration in microsteps/s per 100 s
max_decel		Maximum deceleration in microsteps/s per 100 s
max_speed		Maximum speed in microsteps per 10,000 seconds
starting_speed		Starting speed in microsteps per 10,000 seconds

SpeedRequest

Name	Type	Description
cutoff_speed_inc_per_s		Cutoff speed in inc/s
slope_down		Ramp-down slope code
slope_up		Ramp-up slope code
speed_code		Predefined speed code (0-50)
start_speed_inc_per_s		Start speed in inc/s
top_speed_inc_per_s		Top speed in increments/second
top_speed_ul_per_s		Top speed in microliters/second

SpinRequest

Name	Type	Description
velocity	integer	Velocity in microsteps per 10,000 seconds (negative = reverse)

StepMode

Type: integer

StepModeRequest

Name	Type	Description
step_mode	StepMode	Microstepping divisor

StopRequest

Name	Type	Description
hold	boolean	If True, hold position (energized). If False, de-energize (freewheel).

TestRunRoutineRequest

Name	Type	Description
params		Routine parameters. Merged on top of the routine's manifest defaults before the executor walks the steps.

ValidateProtocolRequest

Name	Type	Description
yaml_text	string	Raw YAML text of the protocol manifest to validate.

ValidateRoutineRequest

Name	Type	Description
yaml_text	string	Raw YAML text of the routine manifest to validate.

ValidationError

Name	Type	Description
ctx
input
loc	Array<>
msg	string
type	string

ValidationIssue

Name	Type	Description
code	string
location	string
message	string
severity	string
suggested_fix

ValidationReport

Name	Type	Description
is_valid	boolean
issues	Array<ValidationIssue>
manifest

ValveMoveRequest

Name	Type	Description
direction	string	Rotation direction: 'cw' (I command) or 'ccw' (O command)
port	integer	Target port number

ValveStatus

Name	Type	Description
addr	integer
error_code	integer
error_message	string
firmware
initialized	boolean
name	string
operating_time_min
ready	boolean
temperature_f
valve_position	integer
valve_type	string
voltage