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

# Convert Protocol Endpoint

`POST /protocols/convert`

## Request

- Base URL: `https://api.ionworks.com`
- URL: `https://api.ionworks.com/protocols/convert`
- Auth: none declared

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 or entered by the user. Required for 'neware' and 'biologic_bttest' when the protocol uses C-rate steps or cutoffs: both export them as absolute currents, 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/ionworks-api.md) - [All operations](https://skmtc.dev/ionworks/apis/ionworks-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ionworks/apis/ionworks-api/revisions/abebbbc5f60a?raw)