> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Parse Protocol 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.



## OpenAPI

````yaml https://api.ionworks.com/openapi.json post /protocols/parse-to-template
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.ionworks.com
    description: Production
security: []
paths:
  /protocols/parse-to-template:
    post:
      tags:
        - protocols
      summary: Parse Protocol To Template
      description: >-
        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.
      operationId: parse_protocol_to_template_protocols_parse_to_template_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParseToTemplateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParseToTemplateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ParseToTemplateRequest:
      properties:
        protocol_experiment:
          $ref: '#/components/schemas/ProtocolExperimentConfig'
        experiment_parameters:
          additionalProperties: true
          type: object
          title: Experiment Parameters
      type: object
      required:
        - protocol_experiment
      title: ParseToTemplateRequest
      description: >-
        Request body for parsing a raw protocol and creating an experiment
        template.
    ParseToTemplateResponse:
      properties:
        template_id:
          type: string
          title: Template Id
      type: object
      required:
        - template_id
      title: ParseToTemplateResponse
      description: Response from the parse-to-template endpoint.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ProtocolExperimentConfig:
      properties:
        protocol:
          anyOf:
            - type: string
            - $ref: '#/components/schemas/Protocol'
          title: Protocol
          description: Protocol content as string or Protocol object
        name:
          type: string
          title: Name
          description: Required protocol name for template naming
        additional_content_files:
          anyOf:
            - additionalProperties:
                type: string
                contentMediaType: application/octet-stream
              type: object
            - type: 'null'
          title: Additional Content Files
          description: Additional content files for protocol parsing
        parameters_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Parameters Schema
          description: JSON Schema for input parameters detected in the protocol
      type: object
      required:
        - protocol
        - name
      title: ProtocolExperimentConfig
      description: Experiment configuration using protocol string or Protocol object.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    Protocol:
      properties:
        header:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Header
          description: Original cycler header metadata.
        safety_limits:
          anyOf:
            - $ref: '#/components/schemas/SafetyLimits'
            - type: 'null'
        steps:
          items:
            anyOf:
              - $ref: '#/components/schemas/StandardStep'
              - $ref: '#/components/schemas/RestStep'
              - $ref: '#/components/schemas/AmbientTemperatureStep'
              - $ref: '#/components/schemas/ControlStep'
              - $ref: '#/components/schemas/AuxiliaryStep'
              - $ref: '#/components/schemas/EISStep'
              - $ref: '#/components/schemas/SubroutineStep'
              - $ref: '#/components/schemas/DriveCycleStep'
              - $ref: '#/components/schemas/StepBlock'
          type: array
          title: Steps
          description: List of steps or step blocks
        global:
          $ref: '#/components/schemas/GlobalConfig'
          description: Global settings for the protocol
      additionalProperties: false
      type: object
      required:
        - steps
      title: Protocol
      description: Complete protocol definition.
    SafetyLimits:
      properties:
        voltage_min:
          anyOf:
            - $ref: '#/components/schemas/SafetyLimit'
            - type: 'null'
          description: Minimum voltage limit [V]
        voltage_max:
          anyOf:
            - $ref: '#/components/schemas/SafetyLimit'
            - type: 'null'
          description: Maximum voltage limit [V]
        temperature_min:
          anyOf:
            - $ref: '#/components/schemas/SafetyLimit'
            - type: 'null'
          description: Minimum temperature limit [°C]
        temperature_max:
          anyOf:
            - $ref: '#/components/schemas/SafetyLimit'
            - type: 'null'
          description: Maximum temperature limit [°C]
        charge_current_max:
          anyOf:
            - $ref: '#/components/schemas/SafetyLimit'
            - type: 'null'
          description: Maximum charge current limit [A]
        discharge_current_max:
          anyOf:
            - $ref: '#/components/schemas/SafetyLimit'
            - type: 'null'
          description: Maximum discharge current limit [A]
        goto:
          anyOf:
            - type: string
            - type: 'null'
          title: Goto
          description: >-
            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.
      additionalProperties: false
      type: object
      title: SafetyLimits
      description: |-
        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.
    StandardStep:
      properties:
        kind:
          type: string
          const: standard
          title: Kind
          description: The type of this step
          default: standard
        direction:
          anyOf:
            - type: string
              enum:
                - Charge
                - Discharge
                - Drive
            - type: string
          title: Direction
          description: The direction of this step
        mode:
          $ref: '#/components/schemas/Mode'
          description: The mode of this step
        value:
          type: string
          title: Value
          description: The value of this step
        ends:
          items:
            anyOf:
              - $ref: '#/components/schemas/CustomEnd'
              - $ref: '#/components/schemas/DurationEnd'
              - $ref: '#/components/schemas/CapacityEnd'
              - $ref: '#/components/schemas/LoopNumberEnd'
              - $ref: '#/components/schemas/VariableEnd'
              - $ref: '#/components/schemas/AndEnd'
              - $ref: '#/components/schemas/OrEnd'
          type: array
          title: Ends
          description: List of duration or end conditions
        set_variable:
          items:
            $ref: '#/components/schemas/SetVariable'
          type: array
          title: Set Variable
          description: Variables to set based on this step
        note:
          type: string
          title: Note
          description: An optional note for the step.
          default: ''
        resolution:
          anyOf:
            - $ref: '#/components/schemas/ResolutionConfig'
            - type: 'null'
          description: Resolution for saving data for this step.
      additionalProperties: false
      type: object
      required:
        - direction
        - mode
        - value
      title: StandardStep
      description: A step that represents a standard step.
    RestStep:
      properties:
        kind:
          type: string
          const: rest
          title: Kind
          description: The type of this step
          default: rest
        ends:
          items:
            anyOf:
              - $ref: '#/components/schemas/CustomEnd'
              - $ref: '#/components/schemas/DurationEnd'
              - $ref: '#/components/schemas/CapacityEnd'
              - $ref: '#/components/schemas/LoopNumberEnd'
              - $ref: '#/components/schemas/VariableEnd'
              - $ref: '#/components/schemas/AndEnd'
              - $ref: '#/components/schemas/OrEnd'
          type: array
          title: Ends
          description: List of duration or end conditions
        set_variable:
          items:
            $ref: '#/components/schemas/SetVariable'
          type: array
          title: Set Variable
          description: Variables to set based on this step
        note:
          type: string
          title: Note
          description: An optional note for the step.
          default: ''
        resolution:
          anyOf:
            - $ref: '#/components/schemas/ResolutionConfig'
            - type: 'null'
          description: Resolution for saving data for this step.
      additionalProperties: false
      type: object
      title: RestStep
      description: A step that represents a rest period.
    AmbientTemperatureStep:
      properties:
        kind:
          type: string
          const: ambient_temperature
          title: Kind
          description: The type of this step
          default: ambient_temperature
        temperature_setpoint:
          type: number
          exclusiveMinimum: -273.15
          title: Temperature Setpoint
          description: Ambient temperature setpoint for this step [°C].
        temperature_ramp_rate:
          type: number
          title: Temperature Ramp Rate
          description: Ambient temperature ramp rate [°C/min].
          default: 2
        note:
          type: string
          title: Note
          description: An optional note for the step.
          default: ''
        resolution:
          $ref: '#/components/schemas/ResolutionConfig'
          description: Resolution for saving data for this step.
      additionalProperties: false
      type: object
      required:
        - temperature_setpoint
      title: AmbientTemperatureStep
      description: A step that sets the ambient temperature.
    ControlStep:
      properties:
        kind:
          type: string
          const: control
          title: Kind
          description: The type of this step
          default: control
        set_variable:
          items:
            $ref: '#/components/schemas/SetVariable'
          type: array
          title: Set Variable
          description: Variables to set based on this step
        note:
          type: string
          title: Note
          description: An optional note for the step.
          default: ''
        goto:
          anyOf:
            - type: string
            - type: 'null'
          title: Goto
          description: Optional goto target step name after executing this control step.
      additionalProperties: false
      type: object
      title: ControlStep
      description: A step for control logic that does not run a simulation.
    AuxiliaryStep:
      properties:
        kind:
          type: string
          enum:
            - increment_cycle_number
            - end
            - pause
            - end_loop
          title: Kind
          description: The type of this step
        note:
          type: string
          title: Note
          description: An optional note for the step.
          default: ''
      additionalProperties: false
      type: object
      required:
        - kind
      title: AuxiliaryStep
      description: A special step to increment the cycle number counter.
    EISStep:
      properties:
        kind:
          type: string
          const: eis
          title: Kind
          description: The type of this step
          default: eis
        lower_frequency:
          type: string
          title: Lower Frequency
          description: Lower frequency [Hz]
        upper_frequency:
          type: string
          title: Upper Frequency
          description: Upper frequency [Hz]
        note:
          type: string
          title: Note
          description: An optional note for the step.
          default: ''
      additionalProperties: false
      type: object
      required:
        - lower_frequency
        - upper_frequency
      title: EISStep
      description: An EIS (Electrochemical Impedance Spectroscopy) step.
    SubroutineStep:
      properties:
        kind:
          type: string
          const: subroutine
          title: Kind
          description: The type of this step
          default: subroutine
        name:
          type: string
          title: Name
          description: Name of the subroutine to call
      additionalProperties: false
      type: object
      required:
        - name
      title: SubroutineStep
      description: A step that calls a reusable subroutine.
    DriveCycleStep:
      properties:
        kind:
          type: string
          const: drive_cycle
          title: Kind
          description: The type of this step
          default: drive_cycle
        name:
          type: string
          title: Name
          description: Name/key of the drive cycle data
        mode:
          type: string
          enum:
            - Current
            - Power
          title: Mode
          description: >-
            Control mode the drive-cycle values are interpreted as. ``Current``
            (default) treats the second data column as current in amps;
            ``Power`` treats it as power in watts.
          default: Current
        note:
          type: string
          title: Note
          description: An optional note for the step.
          default: ''
        duration:
          anyOf:
            - type: number
            - type: 'null'
          title: Duration
          description: Maximum duration in seconds (drive cycle may end earlier)
        ends:
          items:
            anyOf:
              - $ref: '#/components/schemas/CustomEnd'
              - $ref: '#/components/schemas/DurationEnd'
              - $ref: '#/components/schemas/CapacityEnd'
              - $ref: '#/components/schemas/LoopNumberEnd'
              - $ref: '#/components/schemas/VariableEnd'
              - $ref: '#/components/schemas/AndEnd'
              - $ref: '#/components/schemas/OrEnd'
          type: array
          title: Ends
          description: End conditions that can terminate the drive cycle early
        set_variable:
          items:
            $ref: '#/components/schemas/SetVariable'
          type: array
          title: Set Variable
          description: Variables to set based on this step
        resolution:
          anyOf:
            - $ref: '#/components/schemas/ResolutionConfig'
            - type: 'null'
          description: Resolution for saving data for this step.
      additionalProperties: false
      type: object
      required:
        - name
      title: DriveCycleStep
      description: |-
        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:
      properties:
        kind:
          type: string
          const: step_block
          title: Kind
          description: The type of this item
          default: step_block
        name:
          type: string
          title: Name
          description: Name of the block
        steps:
          items:
            anyOf:
              - $ref: '#/components/schemas/StandardStep'
              - $ref: '#/components/schemas/RestStep'
              - $ref: '#/components/schemas/AmbientTemperatureStep'
              - $ref: '#/components/schemas/ControlStep'
              - $ref: '#/components/schemas/AuxiliaryStep'
              - $ref: '#/components/schemas/EISStep'
              - $ref: '#/components/schemas/SubroutineStep'
              - $ref: '#/components/schemas/DriveCycleStep'
              - $ref: '#/components/schemas/StepBlock'
          type: array
          title: Steps
          description: List of steps or nested blocks
        repeat:
          anyOf:
            - type: integer
            - type: string
          title: Repeat
          description: Number of times to repeat the block
          default: 1
        ends:
          items:
            anyOf:
              - $ref: '#/components/schemas/CustomEnd'
              - $ref: '#/components/schemas/DurationEnd'
              - $ref: '#/components/schemas/CapacityEnd'
              - $ref: '#/components/schemas/LoopNumberEnd'
              - $ref: '#/components/schemas/VariableEnd'
              - $ref: '#/components/schemas/AndEnd'
              - $ref: '#/components/schemas/OrEnd'
          type: array
          title: Ends
          description: >-
            A list of termination conditions that apply to all steps within the
            block. These are inherited by all child steps.
        set_variable:
          items:
            $ref: '#/components/schemas/SetVariable'
          type: array
          title: Set Variable
          description: Variables to set at the end of each block repetition.
      additionalProperties: false
      type: object
      required:
        - name
        - steps
      title: StepBlock
      description: A named block of steps that can be repeated.
    GlobalConfig:
      properties:
        initial_temperature:
          type: string
          title: Initial Temperature
          description: Global initial temperature for the experiment [°C], defaults to 25°C
          default: '25'
        initial_state_type:
          type: string
          enum:
            - soc_percentage
            - voltage
          title: Initial State Type
          description: Whether to initialize using SOC percentage or voltage
          default: soc_percentage
        initial_state_value:
          type: string
          title: Initial State Value
          description: Global initial SOC [%] or voltage [V]
          default: '100'
        resolution:
          $ref: '#/components/schemas/ResolutionConfig'
      additionalProperties: false
      type: object
      title: GlobalConfig
      description: Global configuration settings for the protocol.
    SafetyLimit:
      properties:
        value:
          type: number
          title: Value
          description: Limit value (units depend on the field).
        goto:
          anyOf:
            - type: string
            - type: 'null'
          title: Goto
          description: >-
            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:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Delay
          description: >-
            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.
      additionalProperties: false
      type: object
      required:
        - value
      title: SafetyLimit
      description: >-
        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.
    Mode:
      type: string
      enum:
        - Current
        - C-rate
        - Power
        - Voltage
      title: Mode
      description: Control mode for the step.
    CustomEnd:
      properties:
        type:
          type: string
          enum:
            - Voltage
            - Current
            - C-rate
            - Temperature
            - AnodePotential
            - CathodePotential
          title: Type
          description: Type of end condition
        operator:
          type: string
          enum:
            - <
            - '>'
            - <=
            - '>='
          title: Operator
          description: Operator for the condition, e.g. '>', '<', '>=', or '<='
        value:
          type: string
          title: Value
          description: Value of the end condition
        derivative:
          type: integer
          enum:
            - 0
            - 1
          title: Derivative
          description: >-
            Which time derivative to use for the end condition: 0 for the value
            itself, 1 for the first derivative.
          default: 0
        goto:
          anyOf:
            - type: string
            - type: 'null'
          title: Goto
          description: Step to transition to after end is reached
      additionalProperties: false
      type: object
      required:
        - type
        - operator
        - value
      title: CustomEnd
      description: End condition for a step.
    DurationEnd:
      properties:
        type:
          type: string
          const: Duration
          title: Type
          description: Type of end condition
          default: Duration
        value:
          type: string
          title: Value
          description: Duration value
        goto:
          anyOf:
            - type: string
            - type: 'null'
          title: Goto
          description: Step to transition to after end is reached
      additionalProperties: false
      type: object
      required:
        - value
      title: DurationEnd
      description: A duration end condition.
    CapacityEnd:
      properties:
        type:
          type: string
          const: Capacity
          title: Type
          description: Type of end condition
          default: Capacity
        value:
          type: string
          title: Value
          description: Capacity value
        goto:
          anyOf:
            - type: string
            - type: 'null'
          title: Goto
          description: Step to transition to after end is reached
      additionalProperties: false
      type: object
      required:
        - value
      title: CapacityEnd
      description: A capacity end condition.
    LoopNumberEnd:
      properties:
        type:
          type: string
          const: LoopNumber
          title: Type
          description: Type of end condition
          default: LoopNumber
        operator:
          type: string
          enum:
            - '>'
            - '>='
          title: Operator
          description: Operator for the condition (>, >=)
        value:
          type: integer
          title: Value
          description: Loop number value
        goto:
          anyOf:
            - type: string
            - type: 'null'
          title: Goto
          description: Step to transition to after end is reached
      additionalProperties: false
      type: object
      required:
        - operator
        - value
      title: LoopNumberEnd
      description: A loop number end condition.
    VariableEnd:
      properties:
        type:
          type: string
          const: Variable
          title: Type
          description: Type of end condition
          default: Variable
        expression:
          type: string
          title: Expression
          description: >-
            Boolean expression using protocol variables, e.g., 'var1 > var2' or
            'cycle_count >= 10'
        goto:
          anyOf:
            - type: string
            - type: 'null'
          title: Goto
          description: Step to transition to if condition is true at start
      additionalProperties: false
      type: object
      required:
        - expression
      title: VariableEnd
      description: >-
        A condition based on protocol variables, evaluated at step start.


        This end condition is evaluated once when the step begins, using the
        current

        values of protocol variables. If the expression evaluates to True, the
        step

        is skipped immediately. If False, this condition is ignored for the
        step.
    AndEnd:
      properties:
        type:
          type: string
          const: And
          title: Type
          description: Type of end condition
          default: And
        conditions:
          items:
            anyOf:
              - $ref: '#/components/schemas/CustomEnd'
              - $ref: '#/components/schemas/DurationEnd'
              - $ref: '#/components/schemas/CapacityEnd'
              - $ref: '#/components/schemas/LoopNumberEnd'
              - $ref: '#/components/schemas/VariableEnd'
              - $ref: '#/components/schemas/AndEnd'
              - $ref: '#/components/schemas/OrEnd'
          type: array
          minItems: 2
          title: Conditions
          description: List of child conditions (all must be true simultaneously)
        goto:
          anyOf:
            - type: string
            - type: 'null'
          title: Goto
          description: Step to transition to when all conditions are met
      additionalProperties: false
      type: object
      required:
        - conditions
      title: AndEnd
      description: >-
        Compound end condition where all child conditions must be true
        simultaneously.


        For state conditions (Voltage, Current, etc.), this creates a combined
        PyBaMM

        event that fires only when all conditions are met at the same instant.

        For variable conditions, they are evaluated at step start.
    OrEnd:
      properties:
        type:
          type: string
          const: Or
          title: Type
          description: Type of end condition
          default: Or
        conditions:
          items:
            anyOf:
              - $ref: '#/components/schemas/CustomEnd'
              - $ref: '#/components/schemas/DurationEnd'
              - $ref: '#/components/schemas/CapacityEnd'
              - $ref: '#/components/schemas/LoopNumberEnd'
              - $ref: '#/components/schemas/VariableEnd'
              - $ref: '#/components/schemas/AndEnd'
              - $ref: '#/components/schemas/OrEnd'
          type: array
          minItems: 2
          title: Conditions
          description: List of child conditions (any being true fires the event)
        goto:
          anyOf:
            - type: string
            - type: 'null'
          title: Goto
          description: Step to transition to when any condition is met
      additionalProperties: false
      type: object
      required:
        - conditions
      title: OrEnd
      description: >-
        Compound end condition where any child condition being true fires the
        event.


        The first child condition to become true will trigger the end. For
        variable

        conditions that are true at step start, the step is skipped immediately.
    SetVariable:
      properties:
        name:
          type: string
          title: Name
          description: Name of the variable being set
        eval:
          type: string
          title: Eval
          description: Expression to evaluate for the variable
        note:
          type: string
          title: Note
          description: Optional note describing the variable
          default: ''
      additionalProperties: false
      type: object
      required:
        - name
        - eval
      title: SetVariable
      description: Variable to set based on an expression.
    ResolutionConfig:
      properties:
        time:
          anyOf:
            - type: string
            - type: 'null'
          title: Time
          description: >-
            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:
          anyOf:
            - type: string
            - type: 'null'
          title: Voltage
          description: >-
            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:
          anyOf:
            - type: string
            - type: 'null'
          title: Current
          description: >-
            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"]'.
      additionalProperties: false
      type: object
      title: ResolutionConfig
      description: Resolution for saving data.

````