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

# Compare Protocols Endpoint

> Compare two UCPs and report the differences that change what a cycler does.

Cosmetic respellings are not differences: regenerated names, number
formatting, redundant nesting, an explicit goto where fall-through was
implicit, and a dropped trailing ``End`` all leave behaviour unchanged.
What is reported is what reaches the cell -- loop counts, setpoints,
terminations, gotos, safety bounds, and block-cumulative durations.

Pair it with ``/protocols/convert`` to check a round trip: convert a UCP to
a vendor format, parse the result back with ``/protocols/parse``, and
compare the two UCPs. A difference there is a conversion that lost
something.



## OpenAPI

````yaml https://api.ionworks.com/openapi.json post /protocols/compare
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.ionworks.com
    description: Production
security: []
paths:
  /protocols/compare:
    post:
      tags:
        - protocols
      summary: Compare Protocols Endpoint
      description: >-
        Compare two UCPs and report the differences that change what a cycler
        does.


        Cosmetic respellings are not differences: regenerated names, number

        formatting, redundant nesting, an explicit goto where fall-through was

        implicit, and a dropped trailing ``End`` all leave behaviour unchanged.

        What is reported is what reaches the cell -- loop counts, setpoints,

        terminations, gotos, safety bounds, and block-cumulative durations.


        Pair it with ``/protocols/convert`` to check a round trip: convert a UCP
        to

        a vendor format, parse the result back with ``/protocols/parse``, and

        compare the two UCPs. A difference there is a conversion that lost

        something.
      operationId: compare_protocols_endpoint_protocols_compare_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompareProtocolsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompareProtocolsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CompareProtocolsRequest:
      properties:
        left:
          anyOf:
            - additionalProperties: true
              type: object
            - type: string
          title: Left
          description: First UCP, as a dict or YAML string.
        right:
          anyOf:
            - additionalProperties: true
              type: object
            - type: string
          title: Right
          description: Second UCP, as a dict or YAML string.
      type: object
      required:
        - left
        - right
      title: CompareProtocolsRequest
      description: Request body for comparing two UCPs for semantic equality.
    CompareProtocolsResponse:
      properties:
        equal:
          type: boolean
          title: Equal
          description: >-
            True when the protocols would make a cycler do the same thing.
            Differences that no tolerance explains make this False rather than
            being ignored.
        differences:
          items:
            $ref: '#/components/schemas/ProtocolDifference'
          type: array
          title: Differences
          description: Every difference found, earliest first. Empty when equal.
      type: object
      required:
        - equal
      title: CompareProtocolsResponse
      description: Result of comparing two protocols.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ProtocolDifference:
      properties:
        location:
          type: string
          title: Location
          description: Where the difference is, e.g. 'Discharge [#2]'.
        kind:
          type: string
          title: Kind
          description: >-
            Machine-readable category, e.g. 'loop_repeat', 'end_condition',
            'setpoint', 'goto_target', 'step_count', 'safety_limits',
            'cumulative_block_end'.
        severity:
          type: string
          title: Severity
          description: >-
            'behavioural' changes what the cycler does; 'expected' is a
            re-encoding a target format forces; 'unknown' is a real difference
            no tolerance explains.
        detail:
          type: string
          title: Detail
          description: >-
            What changed, in cycler terms, e.g. 'control setpoint changed:
            Discharge at 1.0 (C-rate) -> Discharge at 2.0 (C-rate)'.
        reason:
          type: string
          title: Reason
          description: >-
            Why it matters -- the consequence on hardware, so a caller can judge
            severity without reading the protocols.
          default: ''
        left:
          title: Left
          description: Value on the left protocol.
        right:
          title: Right
          description: Value on the right protocol.
      type: object
      required:
        - location
        - kind
        - severity
        - detail
      title: ProtocolDifference
      description: One semantic difference between the two protocols.
    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

````