---
title: "Convert Protocol Endpoint"
method: POST
path: "/protocols/convert"
tags: ["protocols"]
---

# Convert Protocol Endpoint

`POST /protocols/convert`

Convert a UCP to a vendor-native protocol file.

The primary artifact is returned as base64-encoded bytes alongside a
suggested filename and media type. Some targets (currently Maccor with
drive cycles) emit additional asset files in ``assets``.

## Request body

- ConvertProtocolRequest — Request body for converting a UCP to a vendor-native protocol file.
  - `protocol` union, required — UCP as a dict or YAML string.
    - object
    - string
  - `target` 'maccor' | 'arbin' | 'arbin_sdx' | 'neware' | 'biologic_bttest' | 'novonix', required — Vendor target: 'maccor', 'arbin', 'neware', 'biologic_bttest', or 'novonix'.
  - `drive_cycles` object, nullable — Optional mapping of drive cycle name → samples. Required when the protocol references DriveCycle steps.
  - `filename_stem` string — Stem for the returned primary filename (no extension).
  - `nominal_capacity_ah` number, nullable — Rated cell capacity in A.h, from the cell specification. Required for 'neware' when the protocol uses C-rate steps or cutoffs: Neware sets current in absolute mA and has no C-rate mode, so the rate cannot be resolved without it. Ignored by other targets, which express C-rate natively.
  - `verify` boolean — Round-trip the emitted file back through its parser and refuse the conversion (400) if the protocol no longer means the same thing. A writer that drops a loop count, a goto, or a safety bound emits a valid file that simulates identically, so the loss would otherwise only show up on hardware. A re-encoding the target format forces — a C-rate resolved to absolute amps on a format with no C-rate type — is allowed. Off by default: the checker still reports two benign round-trip artifacts of Maccor/Arbin/Neware (explicit fall-through gotos and an appended terminal step) as differences, so enabling it by default would refuse most valid conversions to those targets.

## Response `200`

Successful Response

- ConvertProtocolResponse
  - `target` string, required
  - `primary` ConvertedFile, required
    - `filename` string, required
    - `content_base64` string, required
    - `media_type` string, required
  - `assets` ConvertedFile[]
    - `filename` string, required
    - `content_base64` string, required
    - `media_type` string, required
  - `warnings` string[]

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