--- title: "Parse Protocol To Template" method: POST path: "/protocols/parse-to-template" tags: ["protocols"] --- # Parse Protocol To Template `POST /protocols/parse-to-template` Parse a raw protocol string and create (or find) a canonical experiment template. This is the first step of a two-step protocol submission flow. Call this to resolve a ``template_id``, then pass that ID to ``POST /simulations/with-template/batch`` to run simulations. Parameters ---------- body : ParseToTemplateRequest Protocol text, name, optional drive cycle files, and experiment parameters. Returns ------- ParseToTemplateResponse The UUID of the resolved (created or existing) experiment template. ## Request body - ParseToTemplateRequest — Request body for parsing a raw protocol and creating an experiment template. - `protocol_experiment` ProtocolExperimentConfig, required — Experiment configuration using protocol string or Protocol object. - `protocol` union, required — Protocol content as string or Protocol object - string - Protocol — Complete protocol definition. - `header` object, nullable — Original cycler header metadata. - `safety_limits` SafetyLimits — Safety limits for the protocol. Each limit may be specified as a bare number (legacy form) or as a :class:`SafetyLimit` object with its own ``goto``. Bare numbers use the top-level ``goto`` as their fallback target. The schema accepts both forms on input so previously-saved protocols continue to validate unchanged; on output every limit is the structured ``SafetyLimit`` form. - `voltage_min` SafetyLimit — A single safety bound with an optional dedicated goto step. Each bound carries its own ``goto`` so that different fault conditions can route to different recovery / pause steps (e.g. "max capacity exceeded" vs "operating voltage exceeded"). When ``goto`` is None the limit falls back to ``SafetyLimits.goto``; when both are None the test ends. - `value` number, required — Limit value (units depend on the field). - `goto` string, nullable — Step to jump to when this specific limit triggers (e.g. 'Step_13'). If None, falls back to ``SafetyLimits.goto``; if that is also None, the test ends. - `delay` number, nullable — Time in seconds the limit must be continuously violated before the safety triggers. Used as a debounce to avoid spurious trips at step start (e.g. Maccor ``VOLT>=4.5&STIME>3`` encodes a 3 s delay). ``None`` means the safety triggers immediately. - `voltage_max` SafetyLimit — A single safety bound with an optional dedicated goto step. Each bound carries its own ``goto`` so that different fault conditions can route to different recovery / pause steps (e.g. "max capacity exceeded" vs "operating voltage exceeded"). When ``goto`` is None the limit falls back to ``SafetyLimits.goto``; when both are None the test ends. - `value` number, required — Limit value (units depend on the field). - `goto` string, nullable — Step to jump to when this specific limit triggers (e.g. 'Step_13'). If None, falls back to ``SafetyLimits.goto``; if that is also None, the test ends. - `delay` number, nullable — Time in seconds the limit must be continuously violated before the safety triggers. Used as a debounce to avoid spurious trips at step start (e.g. Maccor ``VOLT>=4.5&STIME>3`` encodes a 3 s delay). ``None`` means the safety triggers immediately. - `temperature_min` SafetyLimit — A single safety bound with an optional dedicated goto step. Each bound carries its own ``goto`` so that different fault conditions can route to different recovery / pause steps (e.g. "max capacity exceeded" vs "operating voltage exceeded"). When ``goto`` is None the limit falls back to ``SafetyLimits.goto``; when both are None the test ends. - `value` number, required — Limit value (units depend on the field). - `goto` string, nullable — Step to jump to when this specific limit triggers (e.g. 'Step_13'). If None, falls back to ``SafetyLimits.goto``; if that is also None, the test ends. - `delay` number, nullable — Time in seconds the limit must be continuously violated before the safety triggers. Used as a debounce to avoid spurious trips at step start (e.g. Maccor ``VOLT>=4.5&STIME>3`` encodes a 3 s delay). ``None`` means the safety triggers immediately. - `temperature_max` SafetyLimit — A single safety bound with an optional dedicated goto step. Each bound carries its own ``goto`` so that different fault conditions can route to different recovery / pause steps (e.g. "max capacity exceeded" vs "operating voltage exceeded"). When ``goto`` is None the limit falls back to ``SafetyLimits.goto``; when both are None the test ends. - `value` number, required — Limit value (units depend on the field). - `goto` string, nullable — Step to jump to when this specific limit triggers (e.g. 'Step_13'). If None, falls back to ``SafetyLimits.goto``; if that is also None, the test ends. - `delay` number, nullable — Time in seconds the limit must be continuously violated before the safety triggers. Used as a debounce to avoid spurious trips at step start (e.g. Maccor ``VOLT>=4.5&STIME>3`` encodes a 3 s delay). ``None`` means the safety triggers immediately. - `charge_current_max` SafetyLimit — A single safety bound with an optional dedicated goto step. Each bound carries its own ``goto`` so that different fault conditions can route to different recovery / pause steps (e.g. "max capacity exceeded" vs "operating voltage exceeded"). When ``goto`` is None the limit falls back to ``SafetyLimits.goto``; when both are None the test ends. - `value` number, required — Limit value (units depend on the field). - `goto` string, nullable — Step to jump to when this specific limit triggers (e.g. 'Step_13'). If None, falls back to ``SafetyLimits.goto``; if that is also None, the test ends. - `delay` number, nullable — Time in seconds the limit must be continuously violated before the safety triggers. Used as a debounce to avoid spurious trips at step start (e.g. Maccor ``VOLT>=4.5&STIME>3`` encodes a 3 s delay). ``None`` means the safety triggers immediately. - `discharge_current_max` SafetyLimit — A single safety bound with an optional dedicated goto step. Each bound carries its own ``goto`` so that different fault conditions can route to different recovery / pause steps (e.g. "max capacity exceeded" vs "operating voltage exceeded"). When ``goto`` is None the limit falls back to ``SafetyLimits.goto``; when both are None the test ends. - `value` number, required — Limit value (units depend on the field). - `goto` string, nullable — Step to jump to when this specific limit triggers (e.g. 'Step_13'). If None, falls back to ``SafetyLimits.goto``; if that is also None, the test ends. - `delay` number, nullable — Time in seconds the limit must be continuously violated before the safety triggers. Used as a debounce to avoid spurious trips at step start (e.g. Maccor ``VOLT>=4.5&STIME>3`` encodes a 3 s delay). ``None`` means the safety triggers immediately. - `goto` string, nullable — Default step to jump to when a limit without its own ``goto`` triggers (e.g. 'Step_13'). If None and the triggering limit also has no ``goto``, the test ends. - `steps` union[], required — List of steps or step blocks - union - StandardStep — A step that represents a standard step. - … - RestStep — A step that represents a rest period. - … - AmbientTemperatureStep — A step that sets the ambient temperature. - … - ControlStep — A step for control logic that does not run a simulation. - … - AuxiliaryStep — A special step to increment the cycle number counter. - … - EISStep — An EIS (Electrochemical Impedance Spectroscopy) step. - … - SubroutineStep — A step that calls a reusable subroutine. - … - DriveCycleStep — A placeholder step for drive cycles parsed from cycler protocols. DriveCycleStep is a parsing artifact that gets converted to a StandardStep with Direction.DRIVE before simulation. The `name` field references the drive cycle data key passed to `simulate_protocol()`. This step type should not reach the simulation - it's converted during protocol loading in `create_experiment_from_protocol()`. - … - StepBlock — A named block of steps that can be repeated. - … - `global` GlobalConfig — Global configuration settings for the protocol. - `initial_temperature` string — Global initial temperature for the experiment [°C], defaults to 25°C - `initial_state_type` 'soc_percentage' | 'voltage' — Whether to initialize using SOC percentage or voltage - `initial_state_value` string — Global initial SOC [%] or voltage [V] - `resolution` ResolutionConfig — Resolution for saving data. - `time` string, nullable — Interval at which to save data (in seconds). Defaults to the adaptive time stepping if not specified. Supports input expressions like 'input["C-rate"]' or math like '10 / input["C-rate"]'. - `voltage` string, nullable — Interval at which to save data (in volts). Ignored if not specified. Supports input expressions like 'input["Upper voltage cut-off [V]"]' or math like 'input["Upper voltage cut-off [V]"]' / 1000. - `current` string, nullable — Interval at which to save data (in amps). Ignored if not specified. Supports input expressions like 'input["C-rate"]' or math like '10 / input["C-rate"]'. - `name` string, required — Required protocol name for template naming - `additional_content_files` object, nullable — Additional content files for protocol parsing - `parameters_schema` object, nullable — JSON Schema for input parameters detected in the protocol - `experiment_parameters` object - `project_id` string, nullable ## Response `200` Successful Response - ParseToTemplateResponse — Response from the parse-to-template endpoint. - `template_id` string, required ## Other responses - `422` — Validation Error --- [API](https://skmtc.dev/ionworks/apis/fastapi.md) · [All operations](https://skmtc.dev/ionworks/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ionworks/fastapi/revisions/7337a3cbdaf2/schema)