Protocols

Protocol library listing, user-protocol CRUD, and execution control.

RESTPython

All endpoints are under the /protocols/ prefix.

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

Namespace: h.protocols — 9 endpoints.

from openculture import HabitatClient

with HabitatClient("http://mistyforest.local:8000") as h:
    # List available protocols
    protocols = h.protocols.list_protocols()

    # Inspect one protocol's manifest
    manifest = h.protocols.get_protocol("drug_study_7day")

    # Run (schedule) a protocol — returns the generated event plan
    plan = h.protocols.run_protocol(
        "drug_study_7day", request=RunProtocolRequest(...)
    )

    # A running protocol fires as scheduled events/jobs — inspect or
    # cancel those via h.schedule and h.jobs.

All request and response shapes are in openculture.client.habitat.models.

Endpoint reference

Habitat API — protocols 0.1.0

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

---

protocols

---

GET /protocols/library

List all protocols (legacy alias)

Description

Return all protocols: OCS library + user-created for this device.

Responses

200 OK

application/json

[
    {}
]

⚠️ 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

{
    "items": {
        "additionalProperties": true,
        "type": "object"
    },
    "type": "array",
    "title": "Response Api List Library Protocols Library Get"
}

---

GET /protocols/library/{name}

Get protocol by name (legacy alias)

Description

Return the full protocol definition for the given name.

Searches both OCS and user protocols (case-insensitive).

Input parameters

Parameter	In	Type	Default	Nullable	Description
name	path	string		No

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

{
    "type": "object",
    "additionalProperties": true,
    "title": "Response Api Get Library Protocol Protocols Library  Name  Get"
}

application/json

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

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

Schema of the response body

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

---

POST /protocols/user

Create user protocol

Description

Create a new user protocol definition.

Request body

application/json

{
    "name": "string",
    "version": "string",
    "tier": "string",
    "summary": "string",
    "description": "string",
    "author": "string",
    "library": "official",
    "tags": [
        "string"
    ],
    "device_kinds": [
        "centris"
    ],
    "composes_routines": [
        "string"
    ],
    "composes_atomics": [
        "string"
    ],
    "defaults": {
        "speed_code": null,
        "pump_name": null,
        "chip_id": null,
        "sample_id": null,
        "timeout_s": null
    },
    "params": [
        {
            "name": "string",
            "type": "string",
            "unit": null,
            "range": null,
            "default": null,
            "required": true,
            "semantic_role": "string"
        }
    ],
    "schedule_items": [
        {
            "atomic": null,
            "routine": null,
            "params": {},
            "schedule": {
                "kind": "once",
                "offset_min": null,
                "interval_min": null,
                "duration_min": null,
                "event_duration_min": null
            },
            "label": "string",
            "sample_id": null,
            "item_id": "string"
        }
    ],
    "requires_state": {},
    "estimated_duration_ms": null,
    "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
                }
            ]
        }
    ],
    "requires_human_confirmation": true,
    "emits_metrics": [
        "string"
    ],
    "hazards": [
        {
            "id": "string",
            "severity": "low",
            "condition": "string",
            "agent_guidance": "string"
        }
    ],
    "preconditions": [
        {
            "check_id": "string",
            "description": "string",
            "on_fail_atomic": null
        }
    ],
    "postconditions": [
        {
            "description": "string",
            "state": {}
        }
    ],
    "side_effects": [
        "fluid_displacement"
    ],
    "estimated_wear": "low",
    "validated_on_hardware": [
        "string"
    ],
    "last_calibrated": null,
    "file_path": null,
    "scope": "ocs",
    "status": "production",
    "color": null,
    "icon": 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.

Schema of the request body

{
    "properties": {
        "name": {
            "type": "string",
            "title": "Name"
        },
        "version": {
            "type": "string",
            "title": "Version",
            "default": "1.0.0"
        },
        "tier": {
            "type": "string",
            "const": "protocol",
            "title": "Tier",
            "default": "protocol"
        },
        "summary": {
            "type": "string",
            "title": "Summary",
            "default": ""
        },
        "description": {
            "type": "string",
            "title": "Description",
            "default": ""
        },
        "author": {
            "type": "string",
            "title": "Author",
            "default": "Open Culture Science"
        },
        "library": {
            "type": "string",
            "enum": [
                "official",
                "user"
            ],
            "title": "Library",
            "default": "official"
        },
        "tags": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Tags"
        },
        "device_kinds": {
            "items": {
                "type": "string",
                "enum": [
                    "centris",
                    "smartvalve",
                    "peristaltic"
                ]
            },
            "type": "array",
            "title": "Device Kinds"
        },
        "composes_routines": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Composes Routines"
        },
        "composes_atomics": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Composes Atomics"
        },
        "defaults": {
            "$ref": "#/components/schemas/ProtocolDefaults"
        },
        "params": {
            "items": {
                "$ref": "#/components/schemas/ParamSpec"
            },
            "type": "array",
            "title": "Params"
        },
        "schedule_items": {
            "items": {
                "$ref": "#/components/schemas/ProtocolScheduleItem"
            },
            "type": "array",
            "title": "Schedule Items"
        },
        "requires_state": {
            "additionalProperties": true,
            "type": "object",
            "title": "Requires State"
        },
        "estimated_duration_ms": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "integer"
                }
            ],
            "title": "Estimated Duration Ms",
            "default": 0
        },
        "failure_modes": {
            "items": {
                "$ref": "#/components/schemas/FailureMode"
            },
            "type": "array",
            "title": "Failure Modes"
        },
        "requires_human_confirmation": {
            "type": "boolean",
            "title": "Requires Human Confirmation",
            "default": false
        },
        "emits_metrics": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Emits Metrics"
        },
        "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"
        },
        "side_effects": {
            "items": {
                "type": "string",
                "enum": [
                    "fluid_displacement",
                    "audit_event",
                    "safety_check",
                    "telemetry"
                ]
            },
            "type": "array",
            "title": "Side Effects"
        },
        "estimated_wear": {
            "type": "string",
            "enum": [
                "low",
                "medium",
                "high"
            ],
            "title": "Estimated Wear",
            "default": "low"
        },
        "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"
        },
        "file_path": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "File Path"
        },
        "scope": {
            "type": "string",
            "enum": [
                "ocs",
                "user"
            ],
            "title": "Scope",
            "default": "ocs"
        },
        "status": {
            "type": "string",
            "enum": [
                "production",
                "development"
            ],
            "title": "Status",
            "default": "production"
        },
        "color": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Color"
        },
        "icon": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Icon"
        },
        "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"
    ],
    "title": "ProtocolManifest",
    "description": "Machine-readable contract for one protocol.\n\nProtocols are *pure schedulers*: ``materialize_protocol`` walks the\n``schedule_items`` list and emits one or more\n:class:`habitat.models.protocol.ProtocolEvent` records per item.\nThe events are handed to :class:`ScheduleEngine`, which fires them\nat their absolute timestamps."
}

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

{
    "additionalProperties": true,
    "type": "object",
    "title": "Response Api Create User Protocol Protocols User Post"
}

application/json

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

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

Schema of the response body

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

---

PUT /protocols/user/{name}

Update user protocol

Description

Update an existing user protocol by slug name.

Input parameters

Parameter	In	Type	Default	Nullable	Description
name	path	string		No

Request body

application/json

{
    "name": "string",
    "version": "string",
    "tier": "string",
    "summary": "string",
    "description": "string",
    "author": "string",
    "library": "official",
    "tags": [
        "string"
    ],
    "device_kinds": [
        "centris"
    ],
    "composes_routines": [
        "string"
    ],
    "composes_atomics": [
        "string"
    ],
    "defaults": {
        "speed_code": null,
        "pump_name": null,
        "chip_id": null,
        "sample_id": null,
        "timeout_s": null
    },
    "params": [
        {
            "name": "string",
            "type": "string",
            "unit": null,
            "range": null,
            "default": null,
            "required": true,
            "semantic_role": "string"
        }
    ],
    "schedule_items": [
        {
            "atomic": null,
            "routine": null,
            "params": {},
            "schedule": {
                "kind": "once",
                "offset_min": null,
                "interval_min": null,
                "duration_min": null,
                "event_duration_min": null
            },
            "label": "string",
            "sample_id": null,
            "item_id": "string"
        }
    ],
    "requires_state": {},
    "estimated_duration_ms": null,
    "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
                }
            ]
        }
    ],
    "requires_human_confirmation": true,
    "emits_metrics": [
        "string"
    ],
    "hazards": [
        {
            "id": "string",
            "severity": "low",
            "condition": "string",
            "agent_guidance": "string"
        }
    ],
    "preconditions": [
        {
            "check_id": "string",
            "description": "string",
            "on_fail_atomic": null
        }
    ],
    "postconditions": [
        {
            "description": "string",
            "state": {}
        }
    ],
    "side_effects": [
        "fluid_displacement"
    ],
    "estimated_wear": "low",
    "validated_on_hardware": [
        "string"
    ],
    "last_calibrated": null,
    "file_path": null,
    "scope": "ocs",
    "status": "production",
    "color": null,
    "icon": 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.

Schema of the request body

{
    "properties": {
        "name": {
            "type": "string",
            "title": "Name"
        },
        "version": {
            "type": "string",
            "title": "Version",
            "default": "1.0.0"
        },
        "tier": {
            "type": "string",
            "const": "protocol",
            "title": "Tier",
            "default": "protocol"
        },
        "summary": {
            "type": "string",
            "title": "Summary",
            "default": ""
        },
        "description": {
            "type": "string",
            "title": "Description",
            "default": ""
        },
        "author": {
            "type": "string",
            "title": "Author",
            "default": "Open Culture Science"
        },
        "library": {
            "type": "string",
            "enum": [
                "official",
                "user"
            ],
            "title": "Library",
            "default": "official"
        },
        "tags": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Tags"
        },
        "device_kinds": {
            "items": {
                "type": "string",
                "enum": [
                    "centris",
                    "smartvalve",
                    "peristaltic"
                ]
            },
            "type": "array",
            "title": "Device Kinds"
        },
        "composes_routines": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Composes Routines"
        },
        "composes_atomics": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Composes Atomics"
        },
        "defaults": {
            "$ref": "#/components/schemas/ProtocolDefaults"
        },
        "params": {
            "items": {
                "$ref": "#/components/schemas/ParamSpec"
            },
            "type": "array",
            "title": "Params"
        },
        "schedule_items": {
            "items": {
                "$ref": "#/components/schemas/ProtocolScheduleItem"
            },
            "type": "array",
            "title": "Schedule Items"
        },
        "requires_state": {
            "additionalProperties": true,
            "type": "object",
            "title": "Requires State"
        },
        "estimated_duration_ms": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "integer"
                }
            ],
            "title": "Estimated Duration Ms",
            "default": 0
        },
        "failure_modes": {
            "items": {
                "$ref": "#/components/schemas/FailureMode"
            },
            "type": "array",
            "title": "Failure Modes"
        },
        "requires_human_confirmation": {
            "type": "boolean",
            "title": "Requires Human Confirmation",
            "default": false
        },
        "emits_metrics": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Emits Metrics"
        },
        "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"
        },
        "side_effects": {
            "items": {
                "type": "string",
                "enum": [
                    "fluid_displacement",
                    "audit_event",
                    "safety_check",
                    "telemetry"
                ]
            },
            "type": "array",
            "title": "Side Effects"
        },
        "estimated_wear": {
            "type": "string",
            "enum": [
                "low",
                "medium",
                "high"
            ],
            "title": "Estimated Wear",
            "default": "low"
        },
        "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"
        },
        "file_path": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "File Path"
        },
        "scope": {
            "type": "string",
            "enum": [
                "ocs",
                "user"
            ],
            "title": "Scope",
            "default": "ocs"
        },
        "status": {
            "type": "string",
            "enum": [
                "production",
                "development"
            ],
            "title": "Status",
            "default": "production"
        },
        "color": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Color"
        },
        "icon": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Icon"
        },
        "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"
    ],
    "title": "ProtocolManifest",
    "description": "Machine-readable contract for one protocol.\n\nProtocols are *pure schedulers*: ``materialize_protocol`` walks the\n``schedule_items`` list and emits one or more\n:class:`habitat.models.protocol.ProtocolEvent` records per item.\nThe events are handed to :class:`ScheduleEngine`, which fires them\nat their absolute timestamps."
}

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

{
    "type": "object",
    "additionalProperties": true,
    "title": "Response Api Update User Protocol Protocols User  Name  Put"
}

application/json

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

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

Schema of the response body

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

---

DELETE /protocols/user/{name}

Delete user protocol

Description

Delete a user protocol by slug name.

Input parameters

Parameter	In	Type	Default	Nullable	Description
name	path	string		No

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

application/json

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

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

Schema of the response body

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

---

GET /protocols

List protocol manifests

Description

Return every protocol in the registry. The registry is refreshed from disk on each call so newly saved user protocols appear immediately.

Input parameters

Parameter	In	Type	Default	Nullable	Description
device_kind	query			No	Filter to protocols touching a single device_kind.
q	query			No	Substring filter (matches name, summary, description, tags; case-insensitive).

Responses

200 OK422 Unprocessable Entity

application/json

[
    {}
]

⚠️ 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 Protocols Protocols Get"
}

application/json

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

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

Schema of the response body

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

---

GET /protocols/{name}

Get one protocol manifest

Description

Return the manifest for the named protocol. Unknown names return a structured AgentActionableError with HTTP 400.

Input parameters

Parameter	In	Type	Default	Nullable	Description
name	path	string		No

Responses

200 OK422 Unprocessable Entity

application/json

Schema of the response body

{
    "type": "object",
    "additionalProperties": true,
    "title": "Response Get Protocol Protocols  Name  Get"
}

application/json

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

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

Schema of the response body

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

---

POST /protocols/{name}/run

Schedule a protocol's events

Description

Materialise the named protocol into a stream of ProtocolEvents and submit each to ScheduleEngine. Protocols themselves never invoke fluidic hardware — the engine fires the registered events at their absolute fire times and the Jobs pipeline takes over from there. The response is a ProtocolPlan record carrying one ScheduleSubmission entry per event registered.

Input parameters

Parameter	In	Type	Default	Nullable	Description
name	path	string		No

Request body

application/json

{
    "bound_params": {
        "chip_id": "chip_A"
    }
}

{
    "bound_params": {
        "chip_id": "chip_A",
        "working_volume_ul": 50.0,
        "aspirate_factor": 1.5,
        "pre_recording_pad_min": 25.0,
        "post_drug_min": 15.0,
        "wash_count": 6,
        "post_wash_min": 20.0
    }
}

{
    "bound_params": {
        "sample_id": "sample_001",
        "chip_id": "chip_A",
        "drug_source_role": "reagent",
        "drug_volume_ul": 50.0,
        "feed_volume_ul": 500.0
    }
}

Schema of the request body

{
    "properties": {
        "bound_params": {
            "additionalProperties": true,
            "type": "object",
            "title": "Bound Params",
            "description": "Bindings for the protocol's declared params."
        }
    },
    "additionalProperties": false,
    "type": "object",
    "title": "RunProtocolRequest",
    "description": "Wire body for ``POST /protocols/{name}/run``.\n\n``bound_params`` is the user-supplied dict applied on top of\n``ProtocolManifest.defaults`` and resolved into each step's params at\nexecute time."
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "protocol_name": "string",
    "protocol_version": "string",
    "run_id": "string",
    "started_at": "2022-04-13T15:42:05.901Z",
    "ended_at": null,
    "anchor_time": "string",
    "bound_params": {},
    "submissions": [
        {
            "step_id": "string",
            "step_index": 0,
            "label": "string",
            "status": "string",
            "routine": null,
            "atomic": null,
            "params": null,
            "duration_ms": 0,
            "job_id": null,
            "error": null,
            "event_id": "string",
            "fire_at": "string",
            "target_kind": "string",
            "target_name": "string"
        }
    ],
    "step_results": null,
    "status": "scheduling"
}

⚠️ 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": {
        "protocol_name": {
            "type": "string",
            "title": "Protocol Name"
        },
        "protocol_version": {
            "type": "string",
            "title": "Protocol Version",
            "default": "1.0.0"
        },
        "run_id": {
            "type": "string",
            "title": "Run Id"
        },
        "started_at": {
            "type": "string",
            "format": "date-time",
            "title": "Started At"
        },
        "ended_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Ended At"
        },
        "anchor_time": {
            "type": "string",
            "title": "Anchor Time",
            "default": ""
        },
        "bound_params": {
            "additionalProperties": true,
            "type": "object",
            "title": "Bound Params"
        },
        "submissions": {
            "items": {
                "$ref": "#/components/schemas/ScheduleSubmission"
            },
            "type": "array",
            "title": "Submissions"
        },
        "step_results": {
            "items": {
                "$ref": "#/components/schemas/ScheduleSubmission"
            },
            "type": "array",
            "title": "Step Results"
        },
        "status": {
            "type": "string",
            "enum": [
                "scheduling",
                "scheduled",
                "partial",
                "failed",
                "cancelled",
                "running",
                "succeeded"
            ],
            "title": "Status",
            "default": "scheduling"
        }
    },
    "type": "object",
    "required": [
        "protocol_name"
    ],
    "title": "ProtocolPlan",
    "description": "Record of one protocol being materialised into the engine.\n\nA plan is *not* a run — fluidic execution happens asynchronously as\n:class:`ScheduleEngine` fires the registered events. The plan\ncaptures the bound parameters that were used and the per-event\nsubmission outcomes."
}

application/json

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

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

Schema of the response body

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

---

POST /protocols/validate

Validate a user-authored protocol YAML against the live registries

Description

Parse the supplied YAML, walk each step, and check that every routine / atomic name resolves in its 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.

Request body

application/json

{
    "yaml_text": "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 request body

{
    "properties": {
        "yaml_text": {
            "type": "string",
            "title": "Yaml Text",
            "description": "Raw YAML text of the protocol manifest to validate."
        }
    },
    "additionalProperties": false,
    "type": "object",
    "required": [
        "yaml_text"
    ],
    "title": "ValidateProtocolRequest",
    "description": "Wire body for ``POST /protocols/validate``.\n\nThe agent-authoring skill drafts a YAML protocol from a natural-language\nuser request and posts it here to confirm registry membership, param\nshape, and placeholder resolution before saving."
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "is_valid": true,
    "manifest": null,
    "issues": [
        {
            "severity": "error",
            "code": "string",
            "location": "string",
            "message": "string",
            "suggested_fix": null
        }
    ]
}

⚠️ 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": {
        "is_valid": {
            "type": "boolean",
            "title": "Is Valid"
        },
        "manifest": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/ProtocolManifest"
                },
                {
                    "type": "null"
                }
            ]
        },
        "issues": {
            "items": {
                "$ref": "#/components/schemas/ValidationIssue"
            },
            "type": "array",
            "title": "Issues"
        }
    },
    "type": "object",
    "required": [
        "is_valid"
    ],
    "title": "ValidationReport",
    "description": "Result of validating one user-authored protocol."
}

application/json

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

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

Schema of the response body

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

---

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