Skip to content

Environmental

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

Namespace: h.environmental — 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:
    # List Sensors
    h.environmental.list_sensors()
    # Get Status
    h.environmental.get_status("sensor_id")
    # Download Csv
    h.environmental.download_csv("sensor_id")
    # Read Latest
    h.environmental.read_latest("sensor_id")
    # Get Sample Rate
    h.environmental.get_sample_rate("sensor_id")

Endpoint reference

Habitat API — environmental 0.1.0

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

environmental

GET /devices/environmental

List Sensors

Description

List configured environmental sensors with connection state.

Responses

{
    "sensors": [
        {
            "id": "string",
            "label": "string",
            "connected": true,
            "driver_mode": "string"
        }
    ]
}
⚠️ 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": {
        "sensors": {
            "items": {
                "$ref": "#/components/schemas/SensorListEntry"
            },
            "type": "array",
            "title": "Sensors"
        }
    },
    "type": "object",
    "required": [
        "sensors"
    ],
    "title": "SensorListResponse"
}

GET /devices/environmental/{sensor_id}

Get Status

Description

Per-sensor status: connection, rate, last reading, CSV path, driver mode.

Input parameters

Parameter In Type Default Nullable Description
sensor_id path string No

Responses

{
    "id": "string",
    "label": "string",
    "connected": true,
    "driver_mode": "string",
    "port": null,
    "sample_rate_hz": 10.12,
    "sample_count": 0,
    "warming_up": true,
    "last_reading_at": null,
    "csv_path": null,
    "malformed_frame_count": 0
}
⚠️ 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": {
        "id": {
            "type": "string",
            "title": "Id"
        },
        "label": {
            "type": "string",
            "title": "Label"
        },
        "connected": {
            "type": "boolean",
            "title": "Connected"
        },
        "driver_mode": {
            "type": "string",
            "title": "Driver Mode"
        },
        "port": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Port"
        },
        "sample_rate_hz": {
            "type": "number",
            "title": "Sample Rate Hz"
        },
        "sample_count": {
            "type": "integer",
            "title": "Sample Count"
        },
        "warming_up": {
            "type": "boolean",
            "title": "Warming Up"
        },
        "last_reading_at": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Last Reading At"
        },
        "csv_path": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Csv Path"
        },
        "malformed_frame_count": {
            "type": "integer",
            "title": "Malformed Frame Count"
        }
    },
    "type": "object",
    "required": [
        "id",
        "label",
        "connected",
        "driver_mode",
        "port",
        "sample_rate_hz",
        "sample_count",
        "warming_up",
        "last_reading_at",
        "csv_path",
        "malformed_frame_count"
    ],
    "title": "SensorStatus"
}


{
    "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/environmental/{sensor_id}/read

Read Latest

Description

Latest smoothed reading (CO2, temperature, humidity).

Input parameters

Parameter In Type Default Nullable Description
sensor_id path string No

Responses

{
    "co2_pct": null,
    "temperature_c": null,
    "humidity_pct": null,
    "sample_rate_hz": 10.12,
    "sample_count": 0,
    "timestamp": null,
    "warming_up": true
}
⚠️ 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": {
        "co2_pct": {
            "anyOf": [
                {
                    "type": "number"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Co2 Pct"
        },
        "temperature_c": {
            "anyOf": [
                {
                    "type": "number"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Temperature C"
        },
        "humidity_pct": {
            "anyOf": [
                {
                    "type": "number"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Humidity Pct"
        },
        "sample_rate_hz": {
            "type": "number",
            "title": "Sample Rate Hz"
        },
        "sample_count": {
            "type": "integer",
            "title": "Sample Count"
        },
        "timestamp": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Timestamp"
        },
        "warming_up": {
            "type": "boolean",
            "title": "Warming Up"
        }
    },
    "type": "object",
    "required": [
        "co2_pct",
        "temperature_c",
        "humidity_pct",
        "sample_rate_hz",
        "sample_count",
        "timestamp",
        "warming_up"
    ],
    "title": "SensorReading"
}


{
    "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/environmental/{sensor_id}/sample_rate

Get Sample Rate

Description

Return the configured emission rate in Hz.

Input parameters

Parameter In Type Default Nullable Description
sensor_id path string No

Responses

Schema of the response body 
{
    "type": "object",
    "additionalProperties": {
        "type": "number"
    },
    "title": "Response Get Sample Rate Devices Environmental  Sensor Id  Sample Rate 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/environmental/{sensor_id}/csv

Download Csv

Description

Download today's CSV (or ?date=YYYY-MM-DD for a historical day).

Input parameters

Parameter In Type Default Nullable Description
date query No
sensor_id 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.

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