Routines
Every operation is a standard JSON-over-HTTP request. The full endpoint reference is below; try requests live from Try it.
Namespace: h.routines — 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 routine manifests
h.routines.list_routines()
# List user routines
h.routines.api_list_user_routines()
# Create user routine
h.routines.api_create_user_routine(request=RoutineManifest-Input(...))
# Delete user routine
h.routines.api_delete_user_routine("name")
# Get one user routine
h.routines.api_get_user_routine("name")
# Update user routine
h.routines.api_update_user_routine("name", request=RoutineManifest-Input(...))
# Validate a user-authored routine YAML against the live registries
h.routines.validate_routine_endpoint(request=ValidateRoutineRequest(...))
# Get one routine manifest
h.routines.get_routine("name")
# Execute a routine
h.routines.execute_routine("name", request=ExecuteRoutineRequest(...))
# Dry-execute a routine through mock drivers (no hardware I/O)
h.routines.test_run_routine("name", request=TestRunRoutineRequest(...))
Endpoint reference
Habitat API — routines 0.1.0
REST API for the Habitat tissue-culture automation platform by Open Culture Science. All endpoints accept and return JSON.
routines
POST /routines/{name}/test-run
Dry-execute a routine through mock drivers (no hardware I/O)
Description
Runs the named routine end-to-end through :class:~habitat.routines.executor.RoutineExecutor against throwaway mock drivers built from the live device config. The operator's port_map, syringe volumes, valve types, and chip mappings are honoured exactly — only the serial I/O is short-circuited. Returns the :class:RoutineRun with the step-by-step trace (statuses, target atomic names, durations, structured errors). Always returns 200 unless the routine name is unknown (400) or the routine raises an abort-on-error step (the RoutineStepFailed surfaces as 400 with the canonical AgentActionableError payload).
Use this between validate and save so an agent can confirm a draft routine actually executes against the live device wiring before persisting it through POST /routines/user.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
name |
path | string | No |
Request body
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Schema of the request body
{
"properties": {
"params": {
"additionalProperties": true,
"type": "object",
"title": "Params",
"description": "Routine parameters. Merged on top of the routine's manifest defaults before the executor walks the steps."
}
},
"additionalProperties": false,
"type": "object",
"title": "TestRunRoutineRequest",
"description": "Wire body for ``POST /routines/{name}/test-run``.\n\nSame shape as :class:`ExecuteRoutineRequest` — the test-run goes\nthrough the same executor with the same param resolution, just\nagainst mock drivers built from the live device config."
}
Responses
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
POST /routines/validate
Validate a user-authored routine YAML against the live registries
Description
Parse the supplied YAML, recursively walk each step (including foreach / loop / parallel bodies), and check that every atomic name resolves in the atomic registry and that step params satisfy the target manifest's ParamSpec contract (required keys, declared ranges, declared placeholders). Always returns 200; the report's is_valid flag carries the verdict, and issues lists structured problems with location pointers and suggested fixes. The endpoint never writes to disk, never modifies the routine registry, and never executes against hardware.
Request body
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Schema of the request body
{
"properties": {
"yaml_text": {
"type": "string",
"title": "Yaml Text",
"description": "Raw YAML text of the routine manifest to validate."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"yaml_text"
],
"title": "ValidateRoutineRequest",
"description": "Wire body for ``POST /routines/validate``.\n\nThe agent-authoring skill drafts a YAML routine and posts it here\nto confirm syntax, atomic-target resolution, param shape, and\nplaceholder resolution before persisting through ``POST\n/routines/user``. Routine-target references resolve lazily at\nexecute time (same contract as the library loader) so an unknown\nroutine name is not flagged here — only unknown atomics."
}
Responses
{
"is_valid": true,
"manifest": null,
"issues": [
{
"severity": "error",
"code": "string",
"location": "string",
"message": "string",
"suggested_fix": null
}
]
}
Schema of the response body
{
"properties": {
"is_valid": {
"type": "boolean",
"title": "Is Valid"
},
"manifest": {
"anyOf": [
{
"$ref": "#/components/schemas/RoutineManifest-Output"
},
{
"type": "null"
}
]
},
"issues": {
"items": {
"$ref": "#/components/schemas/ValidationIssue"
},
"type": "array",
"title": "Issues"
}
},
"type": "object",
"required": [
"is_valid"
],
"title": "RoutineValidationReport",
"description": "Result of validating one user-authored routine.\n\nMirrors :class:`ValidationReport` but carries a\n:class:`RoutineManifest` instead of a :class:`ProtocolManifest`."
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
GET /routines/user
List user routines
Description
Return all user-authored routines for the current device, sorted by creation time ascending. OCS library routines are NOT included — use GET /routines for the merged view.
Responses
[
{
"name": "string",
"version": "string",
"tier": "string",
"summary": "string",
"description": "string",
"composes": [
"string"
],
"device_kinds": [
"centris"
],
"chip_aware": true,
"requires_state": {},
"mutates": [
"string"
],
"side_effects": [
"fluid_displacement"
],
"params": [
{
"name": "string",
"type": "string",
"unit": null,
"range": null,
"default": null,
"required": true,
"semantic_role": "string"
}
],
"blocking": true,
"idempotent": true,
"reversible": true,
"expected_duration_ms": null,
"steps": [
{
"atomic": null,
"routine": null,
"foreach": null,
"loop": null,
"parallel": null,
"params": {},
"delay_after_ms": 0,
"label": "string",
"on_error": "abort",
"max_retries": 0
}
],
"library": "official",
"hazards": [
{
"id": "string",
"severity": "low",
"condition": "string",
"agent_guidance": "string"
}
],
"preconditions": [
{
"check_id": "string",
"description": "string",
"on_fail_atomic": null
}
],
"postconditions": [
{
"description": "string",
"state": {}
}
],
"failure_modes": [
{
"error_class": "string",
"when": "string",
"recommended_recovery": [
{
"atomic_name": "string",
"params": {},
"rationale": "string",
"expected_postcondition": null,
"verify_with": null,
"max_attempts": 0,
"delay_ms_between_attempts": 0
}
]
}
],
"interrupted_state": "string",
"typical_predecessors": [
"string"
],
"typical_successors": [
"string"
],
"estimated_wear": "low",
"estimated_fluid_volume_ul": null,
"authored_by": "string",
"validated_on_hardware": [
"string"
],
"last_calibrated": null,
"emits_metrics": [
"string"
],
"requires_human_confirmation": true,
"file_path": null,
"device_name": null,
"created_at": null,
"updated_at": null
}
]
POST /routines/user
Create user routine
Description
Persist a new user-authored routine manifest and hot-register it into the live RoutineRegistry. Body is the full RoutineManifest. Refuses to shadow an OCS library routine of the same name (409). Atomic references are validated against the live registry; unknown atomics return 400 with a structured AgentActionableError.
Request body
{
"name": "string",
"version": "string",
"tier": "string",
"summary": "string",
"description": "string",
"composes": [
"string"
],
"device_kinds": [
"centris"
],
"chip_aware": true,
"requires_state": {},
"mutates": [
"string"
],
"side_effects": [
"fluid_displacement"
],
"params": [
{
"name": "string",
"type": "string",
"unit": null,
"range": null,
"default": null,
"required": true,
"semantic_role": "string"
}
],
"blocking": true,
"idempotent": true,
"reversible": true,
"expected_duration_ms": null,
"steps": [
{
"atomic": null,
"routine": null,
"foreach": null,
"loop": null,
"parallel": null,
"params": {},
"delay_after_ms": 0,
"label": "string",
"on_error": "abort",
"max_retries": 0
}
],
"library": "official",
"hazards": [
{
"id": "string",
"severity": "low",
"condition": "string",
"agent_guidance": "string"
}
],
"preconditions": [
{
"check_id": "string",
"description": "string",
"on_fail_atomic": null
}
],
"postconditions": [
{
"description": "string",
"state": {}
}
],
"failure_modes": [
{
"error_class": "string",
"when": "string",
"recommended_recovery": [
{
"atomic_name": "string",
"params": {},
"rationale": "string",
"expected_postcondition": null,
"verify_with": null,
"max_attempts": 0,
"delay_ms_between_attempts": 0
}
]
}
],
"interrupted_state": "string",
"typical_predecessors": [
"string"
],
"typical_successors": [
"string"
],
"estimated_wear": "low",
"estimated_fluid_volume_ul": null,
"authored_by": "string",
"validated_on_hardware": [
"string"
],
"last_calibrated": null,
"emits_metrics": [
"string"
],
"requires_human_confirmation": true,
"file_path": null,
"device_name": null,
"created_at": null,
"updated_at": null
}
Schema of the request body
{
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"version": {
"type": "string",
"title": "Version",
"default": "1.0.0"
},
"tier": {
"type": "string",
"const": "routine",
"title": "Tier",
"default": "routine"
},
"summary": {
"type": "string",
"title": "Summary"
},
"description": {
"type": "string",
"title": "Description"
},
"composes": {
"items": {
"type": "string"
},
"type": "array",
"title": "Composes"
},
"device_kinds": {
"items": {
"type": "string",
"enum": [
"centris",
"smartvalve",
"peristaltic"
]
},
"type": "array",
"title": "Device Kinds"
},
"chip_aware": {
"type": "boolean",
"title": "Chip Aware",
"default": true
},
"requires_state": {
"additionalProperties": true,
"type": "object",
"title": "Requires State"
},
"mutates": {
"items": {
"type": "string"
},
"type": "array",
"title": "Mutates"
},
"side_effects": {
"items": {
"type": "string",
"enum": [
"fluid_displacement",
"audit_event",
"safety_check",
"telemetry"
]
},
"type": "array",
"title": "Side Effects"
},
"params": {
"items": {
"$ref": "#/components/schemas/ParamSpec"
},
"type": "array",
"title": "Params"
},
"blocking": {
"type": "boolean",
"title": "Blocking",
"default": true
},
"idempotent": {
"type": "boolean",
"title": "Idempotent",
"default": false
},
"reversible": {
"type": "boolean",
"title": "Reversible",
"default": false
},
"expected_duration_ms": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"title": "Expected Duration Ms",
"default": 0
},
"steps": {
"items": {
"$ref": "#/components/schemas/RoutineStep-Input"
},
"type": "array",
"title": "Steps"
},
"library": {
"type": "string",
"enum": [
"official",
"user"
],
"title": "Library",
"default": "official"
},
"hazards": {
"items": {
"$ref": "#/components/schemas/Hazard"
},
"type": "array",
"title": "Hazards"
},
"preconditions": {
"items": {
"$ref": "#/components/schemas/Precondition"
},
"type": "array",
"title": "Preconditions"
},
"postconditions": {
"items": {
"$ref": "#/components/schemas/Postcondition"
},
"type": "array",
"title": "Postconditions"
},
"failure_modes": {
"items": {
"$ref": "#/components/schemas/FailureMode"
},
"type": "array",
"title": "Failure Modes"
},
"interrupted_state": {
"type": "string",
"title": "Interrupted State",
"default": ""
},
"typical_predecessors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Typical Predecessors"
},
"typical_successors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Typical Successors"
},
"estimated_wear": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"title": "Estimated Wear",
"default": "low"
},
"estimated_fluid_volume_ul": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Estimated Fluid Volume Ul"
},
"authored_by": {
"type": "string",
"title": "Authored By",
"default": "core"
},
"validated_on_hardware": {
"items": {
"type": "string"
},
"type": "array",
"title": "Validated On Hardware"
},
"last_calibrated": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Calibrated"
},
"emits_metrics": {
"items": {
"type": "string"
},
"type": "array",
"title": "Emits Metrics"
},
"requires_human_confirmation": {
"type": "boolean",
"title": "Requires Human Confirmation",
"default": false
},
"file_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File Path"
},
"device_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device Name"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"name",
"summary",
"description",
"device_kinds"
],
"title": "RoutineManifest",
"description": "Machine-readable contract for one routine.\n\nYAML routines populate the ``steps`` block; Python routines leave\nit empty and rely on the registered callable."
}
Responses
{
"name": "string",
"version": "string",
"tier": "string",
"summary": "string",
"description": "string",
"composes": [
"string"
],
"device_kinds": [
"centris"
],
"chip_aware": true,
"requires_state": {},
"mutates": [
"string"
],
"side_effects": [
"fluid_displacement"
],
"params": [
{
"name": "string",
"type": "string",
"unit": null,
"range": null,
"default": null,
"required": true,
"semantic_role": "string"
}
],
"blocking": true,
"idempotent": true,
"reversible": true,
"expected_duration_ms": null,
"steps": [
{
"atomic": null,
"routine": null,
"foreach": null,
"loop": null,
"parallel": null,
"params": {},
"delay_after_ms": 0,
"label": "string",
"on_error": "abort",
"max_retries": 0
}
],
"library": "official",
"hazards": [
{
"id": "string",
"severity": "low",
"condition": "string",
"agent_guidance": "string"
}
],
"preconditions": [
{
"check_id": "string",
"description": "string",
"on_fail_atomic": null
}
],
"postconditions": [
{
"description": "string",
"state": {}
}
],
"failure_modes": [
{
"error_class": "string",
"when": "string",
"recommended_recovery": [
{
"atomic_name": "string",
"params": {},
"rationale": "string",
"expected_postcondition": null,
"verify_with": null,
"max_attempts": 0,
"delay_ms_between_attempts": 0
}
]
}
],
"interrupted_state": "string",
"typical_predecessors": [
"string"
],
"typical_successors": [
"string"
],
"estimated_wear": "low",
"estimated_fluid_volume_ul": null,
"authored_by": "string",
"validated_on_hardware": [
"string"
],
"last_calibrated": null,
"emits_metrics": [
"string"
],
"requires_human_confirmation": true,
"file_path": null,
"device_name": null,
"created_at": null,
"updated_at": null
}
Schema of the response body
{
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"version": {
"type": "string",
"title": "Version",
"default": "1.0.0"
},
"tier": {
"type": "string",
"const": "routine",
"title": "Tier",
"default": "routine"
},
"summary": {
"type": "string",
"title": "Summary"
},
"description": {
"type": "string",
"title": "Description"
},
"composes": {
"items": {
"type": "string"
},
"type": "array",
"title": "Composes"
},
"device_kinds": {
"items": {
"type": "string",
"enum": [
"centris",
"smartvalve",
"peristaltic"
]
},
"type": "array",
"title": "Device Kinds"
},
"chip_aware": {
"type": "boolean",
"title": "Chip Aware",
"default": true
},
"requires_state": {
"additionalProperties": true,
"type": "object",
"title": "Requires State"
},
"mutates": {
"items": {
"type": "string"
},
"type": "array",
"title": "Mutates"
},
"side_effects": {
"items": {
"type": "string",
"enum": [
"fluid_displacement",
"audit_event",
"safety_check",
"telemetry"
]
},
"type": "array",
"title": "Side Effects"
},
"params": {
"items": {
"$ref": "#/components/schemas/ParamSpec"
},
"type": "array",
"title": "Params"
},
"blocking": {
"type": "boolean",
"title": "Blocking",
"default": true
},
"idempotent": {
"type": "boolean",
"title": "Idempotent",
"default": false
},
"reversible": {
"type": "boolean",
"title": "Reversible",
"default": false
},
"expected_duration_ms": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"title": "Expected Duration Ms",
"default": 0
},
"steps": {
"items": {
"$ref": "#/components/schemas/RoutineStep-Output"
},
"type": "array",
"title": "Steps"
},
"library": {
"type": "string",
"enum": [
"official",
"user"
],
"title": "Library",
"default": "official"
},
"hazards": {
"items": {
"$ref": "#/components/schemas/Hazard"
},
"type": "array",
"title": "Hazards"
},
"preconditions": {
"items": {
"$ref": "#/components/schemas/Precondition"
},
"type": "array",
"title": "Preconditions"
},
"postconditions": {
"items": {
"$ref": "#/components/schemas/Postcondition"
},
"type": "array",
"title": "Postconditions"
},
"failure_modes": {
"items": {
"$ref": "#/components/schemas/FailureMode"
},
"type": "array",
"title": "Failure Modes"
},
"interrupted_state": {
"type": "string",
"title": "Interrupted State",
"default": ""
},
"typical_predecessors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Typical Predecessors"
},
"typical_successors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Typical Successors"
},
"estimated_wear": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"title": "Estimated Wear",
"default": "low"
},
"estimated_fluid_volume_ul": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Estimated Fluid Volume Ul"
},
"authored_by": {
"type": "string",
"title": "Authored By",
"default": "core"
},
"validated_on_hardware": {
"items": {
"type": "string"
},
"type": "array",
"title": "Validated On Hardware"
},
"last_calibrated": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Calibrated"
},
"emits_metrics": {
"items": {
"type": "string"
},
"type": "array",
"title": "Emits Metrics"
},
"requires_human_confirmation": {
"type": "boolean",
"title": "Requires Human Confirmation",
"default": false
},
"file_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File Path"
},
"device_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device Name"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"name",
"summary",
"description",
"device_kinds"
],
"title": "RoutineManifest",
"description": "Machine-readable contract for one routine.\n\nYAML routines populate the ``steps`` block; Python routines leave\nit empty and rely on the registered callable."
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
GET /routines/user/{name}
Get one user routine
Description
Return a single user-authored routine by display name (or slug). Returns 404 if no row matches. OCS library routines are reachable via GET /routines/{name} instead.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
name |
path | string | No |
Responses
{
"name": "string",
"version": "string",
"tier": "string",
"summary": "string",
"description": "string",
"composes": [
"string"
],
"device_kinds": [
"centris"
],
"chip_aware": true,
"requires_state": {},
"mutates": [
"string"
],
"side_effects": [
"fluid_displacement"
],
"params": [
{
"name": "string",
"type": "string",
"unit": null,
"range": null,
"default": null,
"required": true,
"semantic_role": "string"
}
],
"blocking": true,
"idempotent": true,
"reversible": true,
"expected_duration_ms": null,
"steps": [
{
"atomic": null,
"routine": null,
"foreach": null,
"loop": null,
"parallel": null,
"params": {},
"delay_after_ms": 0,
"label": "string",
"on_error": "abort",
"max_retries": 0
}
],
"library": "official",
"hazards": [
{
"id": "string",
"severity": "low",
"condition": "string",
"agent_guidance": "string"
}
],
"preconditions": [
{
"check_id": "string",
"description": "string",
"on_fail_atomic": null
}
],
"postconditions": [
{
"description": "string",
"state": {}
}
],
"failure_modes": [
{
"error_class": "string",
"when": "string",
"recommended_recovery": [
{
"atomic_name": "string",
"params": {},
"rationale": "string",
"expected_postcondition": null,
"verify_with": null,
"max_attempts": 0,
"delay_ms_between_attempts": 0
}
]
}
],
"interrupted_state": "string",
"typical_predecessors": [
"string"
],
"typical_successors": [
"string"
],
"estimated_wear": "low",
"estimated_fluid_volume_ul": null,
"authored_by": "string",
"validated_on_hardware": [
"string"
],
"last_calibrated": null,
"emits_metrics": [
"string"
],
"requires_human_confirmation": true,
"file_path": null,
"device_name": null,
"created_at": null,
"updated_at": null
}
Schema of the response body
{
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"version": {
"type": "string",
"title": "Version",
"default": "1.0.0"
},
"tier": {
"type": "string",
"const": "routine",
"title": "Tier",
"default": "routine"
},
"summary": {
"type": "string",
"title": "Summary"
},
"description": {
"type": "string",
"title": "Description"
},
"composes": {
"items": {
"type": "string"
},
"type": "array",
"title": "Composes"
},
"device_kinds": {
"items": {
"type": "string",
"enum": [
"centris",
"smartvalve",
"peristaltic"
]
},
"type": "array",
"title": "Device Kinds"
},
"chip_aware": {
"type": "boolean",
"title": "Chip Aware",
"default": true
},
"requires_state": {
"additionalProperties": true,
"type": "object",
"title": "Requires State"
},
"mutates": {
"items": {
"type": "string"
},
"type": "array",
"title": "Mutates"
},
"side_effects": {
"items": {
"type": "string",
"enum": [
"fluid_displacement",
"audit_event",
"safety_check",
"telemetry"
]
},
"type": "array",
"title": "Side Effects"
},
"params": {
"items": {
"$ref": "#/components/schemas/ParamSpec"
},
"type": "array",
"title": "Params"
},
"blocking": {
"type": "boolean",
"title": "Blocking",
"default": true
},
"idempotent": {
"type": "boolean",
"title": "Idempotent",
"default": false
},
"reversible": {
"type": "boolean",
"title": "Reversible",
"default": false
},
"expected_duration_ms": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"title": "Expected Duration Ms",
"default": 0
},
"steps": {
"items": {
"$ref": "#/components/schemas/RoutineStep-Output"
},
"type": "array",
"title": "Steps"
},
"library": {
"type": "string",
"enum": [
"official",
"user"
],
"title": "Library",
"default": "official"
},
"hazards": {
"items": {
"$ref": "#/components/schemas/Hazard"
},
"type": "array",
"title": "Hazards"
},
"preconditions": {
"items": {
"$ref": "#/components/schemas/Precondition"
},
"type": "array",
"title": "Preconditions"
},
"postconditions": {
"items": {
"$ref": "#/components/schemas/Postcondition"
},
"type": "array",
"title": "Postconditions"
},
"failure_modes": {
"items": {
"$ref": "#/components/schemas/FailureMode"
},
"type": "array",
"title": "Failure Modes"
},
"interrupted_state": {
"type": "string",
"title": "Interrupted State",
"default": ""
},
"typical_predecessors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Typical Predecessors"
},
"typical_successors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Typical Successors"
},
"estimated_wear": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"title": "Estimated Wear",
"default": "low"
},
"estimated_fluid_volume_ul": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Estimated Fluid Volume Ul"
},
"authored_by": {
"type": "string",
"title": "Authored By",
"default": "core"
},
"validated_on_hardware": {
"items": {
"type": "string"
},
"type": "array",
"title": "Validated On Hardware"
},
"last_calibrated": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Calibrated"
},
"emits_metrics": {
"items": {
"type": "string"
},
"type": "array",
"title": "Emits Metrics"
},
"requires_human_confirmation": {
"type": "boolean",
"title": "Requires Human Confirmation",
"default": false
},
"file_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File Path"
},
"device_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device Name"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"name",
"summary",
"description",
"device_kinds"
],
"title": "RoutineManifest",
"description": "Machine-readable contract for one routine.\n\nYAML routines populate the ``steps`` block; Python routines leave\nit empty and rely on the registered callable."
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
PUT /routines/user/{name}
Update user routine
Description
Replace the user routine identified by slug or display name with the supplied manifest. The new manifest's name may rename the routine (the old row is removed when the slug changes). Hot-registers the new manifest into the live RoutineRegistry on success.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
name |
path | string | No |
Request body
{
"name": "string",
"version": "string",
"tier": "string",
"summary": "string",
"description": "string",
"composes": [
"string"
],
"device_kinds": [
"centris"
],
"chip_aware": true,
"requires_state": {},
"mutates": [
"string"
],
"side_effects": [
"fluid_displacement"
],
"params": [
{
"name": "string",
"type": "string",
"unit": null,
"range": null,
"default": null,
"required": true,
"semantic_role": "string"
}
],
"blocking": true,
"idempotent": true,
"reversible": true,
"expected_duration_ms": null,
"steps": [
{
"atomic": null,
"routine": null,
"foreach": null,
"loop": null,
"parallel": null,
"params": {},
"delay_after_ms": 0,
"label": "string",
"on_error": "abort",
"max_retries": 0
}
],
"library": "official",
"hazards": [
{
"id": "string",
"severity": "low",
"condition": "string",
"agent_guidance": "string"
}
],
"preconditions": [
{
"check_id": "string",
"description": "string",
"on_fail_atomic": null
}
],
"postconditions": [
{
"description": "string",
"state": {}
}
],
"failure_modes": [
{
"error_class": "string",
"when": "string",
"recommended_recovery": [
{
"atomic_name": "string",
"params": {},
"rationale": "string",
"expected_postcondition": null,
"verify_with": null,
"max_attempts": 0,
"delay_ms_between_attempts": 0
}
]
}
],
"interrupted_state": "string",
"typical_predecessors": [
"string"
],
"typical_successors": [
"string"
],
"estimated_wear": "low",
"estimated_fluid_volume_ul": null,
"authored_by": "string",
"validated_on_hardware": [
"string"
],
"last_calibrated": null,
"emits_metrics": [
"string"
],
"requires_human_confirmation": true,
"file_path": null,
"device_name": null,
"created_at": null,
"updated_at": null
}
Schema of the request body
{
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"version": {
"type": "string",
"title": "Version",
"default": "1.0.0"
},
"tier": {
"type": "string",
"const": "routine",
"title": "Tier",
"default": "routine"
},
"summary": {
"type": "string",
"title": "Summary"
},
"description": {
"type": "string",
"title": "Description"
},
"composes": {
"items": {
"type": "string"
},
"type": "array",
"title": "Composes"
},
"device_kinds": {
"items": {
"type": "string",
"enum": [
"centris",
"smartvalve",
"peristaltic"
]
},
"type": "array",
"title": "Device Kinds"
},
"chip_aware": {
"type": "boolean",
"title": "Chip Aware",
"default": true
},
"requires_state": {
"additionalProperties": true,
"type": "object",
"title": "Requires State"
},
"mutates": {
"items": {
"type": "string"
},
"type": "array",
"title": "Mutates"
},
"side_effects": {
"items": {
"type": "string",
"enum": [
"fluid_displacement",
"audit_event",
"safety_check",
"telemetry"
]
},
"type": "array",
"title": "Side Effects"
},
"params": {
"items": {
"$ref": "#/components/schemas/ParamSpec"
},
"type": "array",
"title": "Params"
},
"blocking": {
"type": "boolean",
"title": "Blocking",
"default": true
},
"idempotent": {
"type": "boolean",
"title": "Idempotent",
"default": false
},
"reversible": {
"type": "boolean",
"title": "Reversible",
"default": false
},
"expected_duration_ms": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"title": "Expected Duration Ms",
"default": 0
},
"steps": {
"items": {
"$ref": "#/components/schemas/RoutineStep-Input"
},
"type": "array",
"title": "Steps"
},
"library": {
"type": "string",
"enum": [
"official",
"user"
],
"title": "Library",
"default": "official"
},
"hazards": {
"items": {
"$ref": "#/components/schemas/Hazard"
},
"type": "array",
"title": "Hazards"
},
"preconditions": {
"items": {
"$ref": "#/components/schemas/Precondition"
},
"type": "array",
"title": "Preconditions"
},
"postconditions": {
"items": {
"$ref": "#/components/schemas/Postcondition"
},
"type": "array",
"title": "Postconditions"
},
"failure_modes": {
"items": {
"$ref": "#/components/schemas/FailureMode"
},
"type": "array",
"title": "Failure Modes"
},
"interrupted_state": {
"type": "string",
"title": "Interrupted State",
"default": ""
},
"typical_predecessors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Typical Predecessors"
},
"typical_successors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Typical Successors"
},
"estimated_wear": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"title": "Estimated Wear",
"default": "low"
},
"estimated_fluid_volume_ul": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Estimated Fluid Volume Ul"
},
"authored_by": {
"type": "string",
"title": "Authored By",
"default": "core"
},
"validated_on_hardware": {
"items": {
"type": "string"
},
"type": "array",
"title": "Validated On Hardware"
},
"last_calibrated": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Calibrated"
},
"emits_metrics": {
"items": {
"type": "string"
},
"type": "array",
"title": "Emits Metrics"
},
"requires_human_confirmation": {
"type": "boolean",
"title": "Requires Human Confirmation",
"default": false
},
"file_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File Path"
},
"device_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device Name"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"name",
"summary",
"description",
"device_kinds"
],
"title": "RoutineManifest",
"description": "Machine-readable contract for one routine.\n\nYAML routines populate the ``steps`` block; Python routines leave\nit empty and rely on the registered callable."
}
Responses
{
"name": "string",
"version": "string",
"tier": "string",
"summary": "string",
"description": "string",
"composes": [
"string"
],
"device_kinds": [
"centris"
],
"chip_aware": true,
"requires_state": {},
"mutates": [
"string"
],
"side_effects": [
"fluid_displacement"
],
"params": [
{
"name": "string",
"type": "string",
"unit": null,
"range": null,
"default": null,
"required": true,
"semantic_role": "string"
}
],
"blocking": true,
"idempotent": true,
"reversible": true,
"expected_duration_ms": null,
"steps": [
{
"atomic": null,
"routine": null,
"foreach": null,
"loop": null,
"parallel": null,
"params": {},
"delay_after_ms": 0,
"label": "string",
"on_error": "abort",
"max_retries": 0
}
],
"library": "official",
"hazards": [
{
"id": "string",
"severity": "low",
"condition": "string",
"agent_guidance": "string"
}
],
"preconditions": [
{
"check_id": "string",
"description": "string",
"on_fail_atomic": null
}
],
"postconditions": [
{
"description": "string",
"state": {}
}
],
"failure_modes": [
{
"error_class": "string",
"when": "string",
"recommended_recovery": [
{
"atomic_name": "string",
"params": {},
"rationale": "string",
"expected_postcondition": null,
"verify_with": null,
"max_attempts": 0,
"delay_ms_between_attempts": 0
}
]
}
],
"interrupted_state": "string",
"typical_predecessors": [
"string"
],
"typical_successors": [
"string"
],
"estimated_wear": "low",
"estimated_fluid_volume_ul": null,
"authored_by": "string",
"validated_on_hardware": [
"string"
],
"last_calibrated": null,
"emits_metrics": [
"string"
],
"requires_human_confirmation": true,
"file_path": null,
"device_name": null,
"created_at": null,
"updated_at": null
}
Schema of the response body
{
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"version": {
"type": "string",
"title": "Version",
"default": "1.0.0"
},
"tier": {
"type": "string",
"const": "routine",
"title": "Tier",
"default": "routine"
},
"summary": {
"type": "string",
"title": "Summary"
},
"description": {
"type": "string",
"title": "Description"
},
"composes": {
"items": {
"type": "string"
},
"type": "array",
"title": "Composes"
},
"device_kinds": {
"items": {
"type": "string",
"enum": [
"centris",
"smartvalve",
"peristaltic"
]
},
"type": "array",
"title": "Device Kinds"
},
"chip_aware": {
"type": "boolean",
"title": "Chip Aware",
"default": true
},
"requires_state": {
"additionalProperties": true,
"type": "object",
"title": "Requires State"
},
"mutates": {
"items": {
"type": "string"
},
"type": "array",
"title": "Mutates"
},
"side_effects": {
"items": {
"type": "string",
"enum": [
"fluid_displacement",
"audit_event",
"safety_check",
"telemetry"
]
},
"type": "array",
"title": "Side Effects"
},
"params": {
"items": {
"$ref": "#/components/schemas/ParamSpec"
},
"type": "array",
"title": "Params"
},
"blocking": {
"type": "boolean",
"title": "Blocking",
"default": true
},
"idempotent": {
"type": "boolean",
"title": "Idempotent",
"default": false
},
"reversible": {
"type": "boolean",
"title": "Reversible",
"default": false
},
"expected_duration_ms": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"title": "Expected Duration Ms",
"default": 0
},
"steps": {
"items": {
"$ref": "#/components/schemas/RoutineStep-Output"
},
"type": "array",
"title": "Steps"
},
"library": {
"type": "string",
"enum": [
"official",
"user"
],
"title": "Library",
"default": "official"
},
"hazards": {
"items": {
"$ref": "#/components/schemas/Hazard"
},
"type": "array",
"title": "Hazards"
},
"preconditions": {
"items": {
"$ref": "#/components/schemas/Precondition"
},
"type": "array",
"title": "Preconditions"
},
"postconditions": {
"items": {
"$ref": "#/components/schemas/Postcondition"
},
"type": "array",
"title": "Postconditions"
},
"failure_modes": {
"items": {
"$ref": "#/components/schemas/FailureMode"
},
"type": "array",
"title": "Failure Modes"
},
"interrupted_state": {
"type": "string",
"title": "Interrupted State",
"default": ""
},
"typical_predecessors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Typical Predecessors"
},
"typical_successors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Typical Successors"
},
"estimated_wear": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"title": "Estimated Wear",
"default": "low"
},
"estimated_fluid_volume_ul": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Estimated Fluid Volume Ul"
},
"authored_by": {
"type": "string",
"title": "Authored By",
"default": "core"
},
"validated_on_hardware": {
"items": {
"type": "string"
},
"type": "array",
"title": "Validated On Hardware"
},
"last_calibrated": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Calibrated"
},
"emits_metrics": {
"items": {
"type": "string"
},
"type": "array",
"title": "Emits Metrics"
},
"requires_human_confirmation": {
"type": "boolean",
"title": "Requires Human Confirmation",
"default": false
},
"file_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File Path"
},
"device_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device Name"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"name",
"summary",
"description",
"device_kinds"
],
"title": "RoutineManifest",
"description": "Machine-readable contract for one routine.\n\nYAML routines populate the ``steps`` block; Python routines leave\nit empty and rely on the registered callable."
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
DELETE /routines/user/{name}
Delete user routine
Description
Remove a user routine by slug or display name. Returns 204 on success, 404 when nothing matches. Also drops the routine from the live RoutineRegistry so subsequent execute calls return UnknownRoutine.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
name |
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.
GET /routines
List routine manifests
Description
Return every routine in the registry with its full manifest. Filter by device_kind (matches any of the manifest's device_kinds) or substring (case-insensitive).
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
device_kind |
query | No | Filter to routines that touch a single device_kind (centris, smartvalve, peristaltic). | ||
q |
query | No | Substring filter (matches name, summary, description; case-insensitive). |
Responses
[
{
"name": "string",
"version": "string",
"tier": "string",
"summary": "string",
"description": "string",
"composes": [
"string"
],
"device_kinds": [
"centris"
],
"chip_aware": true,
"requires_state": {},
"mutates": [
"string"
],
"side_effects": [
"fluid_displacement"
],
"params": [
{
"name": "string",
"type": "string",
"unit": null,
"range": null,
"default": null,
"required": true,
"semantic_role": "string"
}
],
"blocking": true,
"idempotent": true,
"reversible": true,
"expected_duration_ms": null,
"steps": [
{
"atomic": null,
"routine": null,
"foreach": null,
"loop": null,
"parallel": null,
"params": {},
"delay_after_ms": 0,
"label": "string",
"on_error": "abort",
"max_retries": 0
}
],
"library": "official",
"hazards": [
{
"id": "string",
"severity": "low",
"condition": "string",
"agent_guidance": "string"
}
],
"preconditions": [
{
"check_id": "string",
"description": "string",
"on_fail_atomic": null
}
],
"postconditions": [
{
"description": "string",
"state": {}
}
],
"failure_modes": [
{
"error_class": "string",
"when": "string",
"recommended_recovery": [
{
"atomic_name": "string",
"params": {},
"rationale": "string",
"expected_postcondition": null,
"verify_with": null,
"max_attempts": 0,
"delay_ms_between_attempts": 0
}
]
}
],
"interrupted_state": "string",
"typical_predecessors": [
"string"
],
"typical_successors": [
"string"
],
"estimated_wear": "low",
"estimated_fluid_volume_ul": null,
"authored_by": "string",
"validated_on_hardware": [
"string"
],
"last_calibrated": null,
"emits_metrics": [
"string"
],
"requires_human_confirmation": true,
"file_path": null,
"device_name": null,
"created_at": null,
"updated_at": null
}
]
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
GET /routines/{name}
Get one routine manifest
Description
Return the manifest for the named routine. Unknown names return a structured AgentActionableError with HTTP 400.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
name |
path | string | No |
Responses
{
"name": "string",
"version": "string",
"tier": "string",
"summary": "string",
"description": "string",
"composes": [
"string"
],
"device_kinds": [
"centris"
],
"chip_aware": true,
"requires_state": {},
"mutates": [
"string"
],
"side_effects": [
"fluid_displacement"
],
"params": [
{
"name": "string",
"type": "string",
"unit": null,
"range": null,
"default": null,
"required": true,
"semantic_role": "string"
}
],
"blocking": true,
"idempotent": true,
"reversible": true,
"expected_duration_ms": null,
"steps": [
{
"atomic": null,
"routine": null,
"foreach": null,
"loop": null,
"parallel": null,
"params": {},
"delay_after_ms": 0,
"label": "string",
"on_error": "abort",
"max_retries": 0
}
],
"library": "official",
"hazards": [
{
"id": "string",
"severity": "low",
"condition": "string",
"agent_guidance": "string"
}
],
"preconditions": [
{
"check_id": "string",
"description": "string",
"on_fail_atomic": null
}
],
"postconditions": [
{
"description": "string",
"state": {}
}
],
"failure_modes": [
{
"error_class": "string",
"when": "string",
"recommended_recovery": [
{
"atomic_name": "string",
"params": {},
"rationale": "string",
"expected_postcondition": null,
"verify_with": null,
"max_attempts": 0,
"delay_ms_between_attempts": 0
}
]
}
],
"interrupted_state": "string",
"typical_predecessors": [
"string"
],
"typical_successors": [
"string"
],
"estimated_wear": "low",
"estimated_fluid_volume_ul": null,
"authored_by": "string",
"validated_on_hardware": [
"string"
],
"last_calibrated": null,
"emits_metrics": [
"string"
],
"requires_human_confirmation": true,
"file_path": null,
"device_name": null,
"created_at": null,
"updated_at": null
}
Schema of the response body
{
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"version": {
"type": "string",
"title": "Version",
"default": "1.0.0"
},
"tier": {
"type": "string",
"const": "routine",
"title": "Tier",
"default": "routine"
},
"summary": {
"type": "string",
"title": "Summary"
},
"description": {
"type": "string",
"title": "Description"
},
"composes": {
"items": {
"type": "string"
},
"type": "array",
"title": "Composes"
},
"device_kinds": {
"items": {
"type": "string",
"enum": [
"centris",
"smartvalve",
"peristaltic"
]
},
"type": "array",
"title": "Device Kinds"
},
"chip_aware": {
"type": "boolean",
"title": "Chip Aware",
"default": true
},
"requires_state": {
"additionalProperties": true,
"type": "object",
"title": "Requires State"
},
"mutates": {
"items": {
"type": "string"
},
"type": "array",
"title": "Mutates"
},
"side_effects": {
"items": {
"type": "string",
"enum": [
"fluid_displacement",
"audit_event",
"safety_check",
"telemetry"
]
},
"type": "array",
"title": "Side Effects"
},
"params": {
"items": {
"$ref": "#/components/schemas/ParamSpec"
},
"type": "array",
"title": "Params"
},
"blocking": {
"type": "boolean",
"title": "Blocking",
"default": true
},
"idempotent": {
"type": "boolean",
"title": "Idempotent",
"default": false
},
"reversible": {
"type": "boolean",
"title": "Reversible",
"default": false
},
"expected_duration_ms": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"title": "Expected Duration Ms",
"default": 0
},
"steps": {
"items": {
"$ref": "#/components/schemas/RoutineStep-Output"
},
"type": "array",
"title": "Steps"
},
"library": {
"type": "string",
"enum": [
"official",
"user"
],
"title": "Library",
"default": "official"
},
"hazards": {
"items": {
"$ref": "#/components/schemas/Hazard"
},
"type": "array",
"title": "Hazards"
},
"preconditions": {
"items": {
"$ref": "#/components/schemas/Precondition"
},
"type": "array",
"title": "Preconditions"
},
"postconditions": {
"items": {
"$ref": "#/components/schemas/Postcondition"
},
"type": "array",
"title": "Postconditions"
},
"failure_modes": {
"items": {
"$ref": "#/components/schemas/FailureMode"
},
"type": "array",
"title": "Failure Modes"
},
"interrupted_state": {
"type": "string",
"title": "Interrupted State",
"default": ""
},
"typical_predecessors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Typical Predecessors"
},
"typical_successors": {
"items": {
"type": "string"
},
"type": "array",
"title": "Typical Successors"
},
"estimated_wear": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"title": "Estimated Wear",
"default": "low"
},
"estimated_fluid_volume_ul": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Estimated Fluid Volume Ul"
},
"authored_by": {
"type": "string",
"title": "Authored By",
"default": "core"
},
"validated_on_hardware": {
"items": {
"type": "string"
},
"type": "array",
"title": "Validated On Hardware"
},
"last_calibrated": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Calibrated"
},
"emits_metrics": {
"items": {
"type": "string"
},
"type": "array",
"title": "Emits Metrics"
},
"requires_human_confirmation": {
"type": "boolean",
"title": "Requires Human Confirmation",
"default": false
},
"file_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File Path"
},
"device_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device Name"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"name",
"summary",
"description",
"device_kinds"
],
"title": "RoutineManifest",
"description": "Machine-readable contract for one routine.\n\nYAML routines populate the ``steps`` block; Python routines leave\nit empty and rely on the registered callable."
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
POST /routines/{name}
Execute a routine
Description
Submit a Job for the named routine. Body: {params: {...}}. The default behaviour blocks until the job reaches a terminal state and returns the result inline; sending Prefer: respond-async returns 202 Accepted with Location: /jobs/{id} and runs the routine in the background. Unknown names and invalid params return 400 with a structured AgentActionableError payload.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
Idempotency-Key |
header | No | |||
name |
path | string | No | ||
prefer |
header | No |
Request body
{
"params": {
"chip_id": "chip_A",
"source_role": "media",
"fill_volume_ul": 100.0,
"drain_volume_ul": 100.0,
"air_backpad_ul": 200.0,
"dry_pause_ms": 1000,
"chip_speed_code": 26,
"offchip_speed_code": 17,
"cycles": 1
}
}
{
"params": {
"sources": [
"reagent",
"media"
],
"buffer_role": "water",
"volume_ul": 200.0,
"buffer_rinse_cycles": 2
}
}
{
"params": {
"chip_id": "chip_A",
"source_role": "media",
"volume_ul": 100.0,
"speed_code": 26,
"air_backpad": true,
"air_volume_ul": 50.0
}
}
{
"params": {
"target_ports": [
5,
6
],
"sterilization_role": "sterilization",
"sterilization_volume_ul": 2000.0,
"floss_cycles": 10,
"wash_source_role": "water",
"wash_volume_ul": 2000.0,
"wash_cycles": 3,
"cycles": 1
}
}
Schema of the request body
{
"properties": {
"params": {
"additionalProperties": true,
"type": "object",
"title": "Params",
"description": "Routine parameters keyed by the names declared in the manifest."
}
},
"additionalProperties": false,
"type": "object",
"title": "ExecuteRoutineRequest",
"description": "Wire body for ``POST /routines/{name}`` and the corresponding job.\n\nThe ``params`` dict is forwarded to the routine's registered request\nclass on the job-runner side; bad params raise ``ValidationError`` ->\n422 there."
}
Responses
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
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 ``{ |
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 ``{ |
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 ``{ |
|
steps |
Array<RoutineStep-Input> | Step body executed once per iteration. |
LoopBlock-Output
| Name | Type | Description |
|---|---|---|
count |
Iteration count. Integer literal or ``{ |
|
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 |