Skip to content

Devices

Every operation is a standard JSON-over-HTTP request. The full endpoint reference is below.

Endpoint reference

Habitat API — devices 0.1.0

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

devices

GET /devices/{kind}

List Kind Instances

Description

List the live instances of a device kind.

Returns 404 when kind is not a registered device kind. When the kind is registered but has no live instances (config has zero pumps of that kind, or the lifespan has not finished wiring drivers), the response is an empty list — not a 404.

Input parameters

Parameter In Type Default Nullable Description
kind path string No

Responses

[
    {}
]
⚠️ 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 
{
    "type": "array",
    "items": {
        "type": "object",
        "additionalProperties": true
    },
    "title": "Response List Kind Instances Devices  Kind  Get"
}


{
    "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 /devices/{kind}/{id}/telemetry/stream

Get Telemetry Stream

Description

Stream the device's telemetry events as Server-Sent Events.

Subscribes to the per-device channel devices:{kind}:{id}. Last-Event-ID is honored for replay; missing header is treated as "" (full buffer replay) so subscribers connecting after a burst of telemetry still see the recent history before going live. The shared SSE plumbing emits a periodic keep-alive comment every 15 seconds to defeat proxy idle timeouts.

Returns 404 when kind is not a registered device kind or when the kind has no telemetry_source_factory (i.e. emits no telemetry).

Input parameters

Parameter In Type Default Nullable Description
id path string No
kind path string No

Responses

Schema of the response body 



{
    "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"
}

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.

ActivityCategory

Type: string

ActivityItem

Name Type Description
category ActivityCategory
detail
finished_at
id string
kind string
label string
scheduled_for
source string
started_at
status string

ActivitySnapshot

Name Type Description
generated_at string(date-time)
last
next
now Array<ActivityItem>

AtomicCallRequest

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

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). Stored as aware UTC: a naive timestamp is interpreted as host-local time and converted; the response echoes the canonical +00:00 string.

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

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. Persisting a sub-floor value requires human confirmation via the HITL-gated atomics/job path (``POST /atomics/centris.initialization.set_init_gap`` async + ``POST /jobs/{id}/confirm``); do that first, then initialize without ``init_gap_increments``.
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_ul_per_s Initialization speed as a volumetric rate in µL/s. None = firmware default homing speed. The driver snaps the value to the nearest firmware-supported discrete rate internally.

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 Valve homing speed setting (firmware units, 4-25)

Hazard

Name Type Description
agent_guidance string
condition string
id string
severity string

HealthzResponse

Name Type Description
status string Always 'ok' when the ASGI app is reachable.

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

JobProvenance

Name Type Description
approved_by
proposed_by
source

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')

KindCapability

Name Type Description
category string Device category: 'actuator', 'sensor', or 'hybrid'.
instance_count integer Number of live instances of this kind.
instances Array<> Live per-instance entries (shape depends on the kind).
name string Device kind name, e.g. 'centris'.

KindInstanceSummary

Name Type Description
category string Device category: 'actuator', 'sensor', or 'hybrid'.
instance_count integer Number of live instances of this kind.

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)

NtpStatus

Name Type Description
issues Array<string> Reasons the clock isn't trustworthy; empty when synced.
leap_status chrony leap status ('Normal' when synced); null if unavailable.
offset_ms Last clock offset in milliseconds; null if unavailable.
stratum NTP stratum; null if unavailable.

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
choices
default
description
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
timeout_s
top_speed_ul_per_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_ul_per_s number
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_ul_per_s number
syringe_volume_ul integer
temperature_f
top_speed_ul_per_s number
valve_position integer
valve_type string
voltage

QueryResponse

Name Type Description
addr integer
parsed_value
raw_value string
register Register identifier

ReadyzResponse

Name Type Description
drivers_initialized boolean True once all drivers have connected and are ready for commands.
status string 'ready' when drivers are initialized, else 'not_ready'.

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

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_ul_per_s Ramp cutoff speed in microliters/second
slope_down Ramp-down slope code
slope_up Ramp-up slope code
start_speed_ul_per_s Ramp start speed in microliters/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).

SystemCapabilities

Name Type Description
global_actions Array<string> Global actions (reserved; empty today).
global_services Array<string> Global services (reserved; empty today).
kinds Array<KindCapability> Per-kind capability entries.

SystemInfo

Name Type Description
action_log_dir ABSOLUTE directory on this host where `habitat.action` records are being written — the input the OCS rig-runner reads for the fluidics ledger. Absolute because the consumer is a DIFFERENT PROCESS: a relative path would be resolved against its working directory, not habitat's, silently naming a directory that does not exist. Null means no action handler is installed (this device writes no action records).
device_name string Unique physical unit identifier, e.g. 'MistyForest'.
hostname string OS hostname of the device.
product_line string Product-line string, e.g. 'Habitat'.
started_at string UTC ISO-8601 timestamp when the process started.
uptime_s number Seconds since the process started.
version string Application semantic version.

SystemStatus

Name Type Description
active_jobs integer Count of jobs in the RUNNING state.
device_name string Unique physical unit identifier.
drivers_initialized boolean True once all drivers have connected and are ready for commands.
emergency_stop boolean True if an emergency stop is currently active.
kinds Device-kind name → list of per-kind summary entries.
queued_jobs integer Count of jobs in the QUEUED state.
scheduled_events_pending integer Count of pending scheduled events.

TestRunRoutineRequest

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

TimezoneResponse

Name Type Description
timezone string Display-timezone label — 'UTC', 'local', an IANA name like 'America/Los_Angeles', or a fixed offset like '+06:00'.

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