Generate Protocol Endpoint

curl --request POST \
  --url https://api.ionworks.com/protocols/generate \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "current_protocol": "<string>",
  "clarifications": [
    {
      "question": "<string>",
      "answer": "<string>"
    }
  ],
  "cell_specification_id": "<string>",
  "skip_existing": false,
  "allow_inputs": false
}
'

import requests

url = "https://api.ionworks.com/protocols/generate"

payload = {
    "prompt": "<string>",
    "current_protocol": "<string>",
    "clarifications": [
        {
            "question": "<string>",
            "answer": "<string>"
        }
    ],
    "cell_specification_id": "<string>",
    "skip_existing": False,
    "allow_inputs": False
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    current_protocol: '<string>',
    clarifications: [{question: '<string>', answer: '<string>'}],
    cell_specification_id: '<string>',
    skip_existing: false,
    allow_inputs: false
  })
};

fetch('https://api.ionworks.com/protocols/generate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ionworks.com/protocols/generate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'current_protocol' => '<string>',
    'clarifications' => [
        [
                'question' => '<string>',
                'answer' => '<string>'
        ]
    ],
    'cell_specification_id' => '<string>',
    'skip_existing' => false,
    'allow_inputs' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ionworks.com/protocols/generate"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"current_protocol\": \"<string>\",\n  \"clarifications\": [\n    {\n      \"question\": \"<string>\",\n      \"answer\": \"<string>\"\n    }\n  ],\n  \"cell_specification_id\": \"<string>\",\n  \"skip_existing\": false,\n  \"allow_inputs\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.ionworks.com/protocols/generate")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"current_protocol\": \"<string>\",\n  \"clarifications\": [\n    {\n      \"question\": \"<string>\",\n      \"answer\": \"<string>\"\n    }\n  ],\n  \"cell_specification_id\": \"<string>\",\n  \"skip_existing\": false,\n  \"allow_inputs\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.ionworks.com/protocols/generate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"current_protocol\": \"<string>\",\n  \"clarifications\": [\n    {\n      \"question\": \"<string>\",\n      \"answer\": \"<string>\"\n    }\n  ],\n  \"cell_specification_id\": \"<string>\",\n  \"skip_existing\": false,\n  \"allow_inputs\": false\n}"

response = http.request(request)
puts response.read_body

{
  "protocol_yaml": "",
  "name": "",
  "explanation": "",
  "assumptions": [
    "<string>"
  ],
  "questions": [
    {
      "question": "<string>",
      "why": "",
      "options": [
        "<string>"
      ]
    }
  ],
  "matches": {
    "template_ids": [
      "<string>"
    ],
    "note": ""
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

protocols

Generate Protocol Endpoint

Generate a UCP protocol from a natural-language description.

When the description leaves a value undecided that would change what runs on the channel, the response carries questions and no protocol. Answer them and call again with the full clarifications history.

Any protocol that is returned has already passed the same validation as POST /protocols/validate and contains no unresolved input["..."] references, so it can be saved as an experiment template directly.

Parameters

body : GenerateProtocolRequest The natural-language prompt, any answers already given, and an optional existing protocol to edit rather than replace.

Returns

GenerateProtocolResponse Either the generated YAML with a suggested name, an explanation, and the assumptions made — or the questions needed to write it.

Raises

ExternalServiceError If the model could not produce a valid protocol.

Generate Protocol Endpoint

curl --request POST \
  --url https://api.ionworks.com/protocols/generate \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "current_protocol": "<string>",
  "clarifications": [
    {
      "question": "<string>",
      "answer": "<string>"
    }
  ],
  "cell_specification_id": "<string>",
  "skip_existing": false,
  "allow_inputs": false
}
'

import requests

url = "https://api.ionworks.com/protocols/generate"

payload = {
    "prompt": "<string>",
    "current_protocol": "<string>",
    "clarifications": [
        {
            "question": "<string>",
            "answer": "<string>"
        }
    ],
    "cell_specification_id": "<string>",
    "skip_existing": False,
    "allow_inputs": False
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    current_protocol: '<string>',
    clarifications: [{question: '<string>', answer: '<string>'}],
    cell_specification_id: '<string>',
    skip_existing: false,
    allow_inputs: false
  })
};

fetch('https://api.ionworks.com/protocols/generate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ionworks.com/protocols/generate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'current_protocol' => '<string>',
    'clarifications' => [
        [
                'question' => '<string>',
                'answer' => '<string>'
        ]
    ],
    'cell_specification_id' => '<string>',
    'skip_existing' => false,
    'allow_inputs' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ionworks.com/protocols/generate"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"current_protocol\": \"<string>\",\n  \"clarifications\": [\n    {\n      \"question\": \"<string>\",\n      \"answer\": \"<string>\"\n    }\n  ],\n  \"cell_specification_id\": \"<string>\",\n  \"skip_existing\": false,\n  \"allow_inputs\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.ionworks.com/protocols/generate")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"current_protocol\": \"<string>\",\n  \"clarifications\": [\n    {\n      \"question\": \"<string>\",\n      \"answer\": \"<string>\"\n    }\n  ],\n  \"cell_specification_id\": \"<string>\",\n  \"skip_existing\": false,\n  \"allow_inputs\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.ionworks.com/protocols/generate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"current_protocol\": \"<string>\",\n  \"clarifications\": [\n    {\n      \"question\": \"<string>\",\n      \"answer\": \"<string>\"\n    }\n  ],\n  \"cell_specification_id\": \"<string>\",\n  \"skip_existing\": false,\n  \"allow_inputs\": false\n}"

response = http.request(request)
puts response.read_body

{
  "protocol_yaml": "",
  "name": "",
  "explanation": "",
  "assumptions": [
    "<string>"
  ],
  "questions": [
    {
      "question": "<string>",
      "why": "",
      "options": [
        "<string>"
      ]
    }
  ],
  "matches": {
    "template_ids": [
      "<string>"
    ],
    "note": ""
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Body

application/json

Request body for generating a protocol from natural language.

prompt

string

required

Plain-English description of the test to run, e.g. '1C/1C cycling for 200 cycles between 4.2 V and 2.5 V with 10-minute rests'.

Required string length: 1 - 4000

current_protocol

string | null

Optional existing protocol as UCP YAML. When supplied the prompt is treated as an edit to it rather than a fresh protocol.

Maximum string length: 100000

clarifications

ClarificationAnswer · object[]

Answers to questions a previous call returned, oldest first. Send the full history each time — the exchange is stateless.

Maximum array length: 20

Show child attributes

cell_specification_id

string | null

Cell the test will run on. Its voltage limits, capacity and rate limits are given to the generator as facts, so it stops guessing (or asking) about them.

skip_existing

boolean

default:false

Skip the saved-protocol search and write a new protocol. Set when the user rejects the suggested matches.

allow_inputs

boolean

default:false

Allow the protocol to carry input["..."] references for values supplied per run, and offer parametric saved protocols as matches. Leave false where every value has to be pinned before the protocol can run, as it does for a scheduled test.

Response

Successful Response

A protocol, the questions needed to write one, or an existing match.

Exactly one branch is populated. Callers should check questions and matches before reading protocol_yaml — both leave it empty.

protocol_yaml

string

default:""

name

string

default:""

explanation

string

default:""

assumptions

string[]

questions

ClarifyingQuestionResponse · object[]

Show child attributes

matches

ExistingProtocolMatchResponse · object | null

A saved protocol that already does what was asked for.

Show child attributes

API Reference

Cell Specifications

Cell Instances

Cell Measurements

Programs

Sites

Cyclers

Channels

Thermal chambers

Simulations

parameterized_models

discovery

Pipeline

simple_pipeline

protocols

users

jobs

optimization

optimizations

Organizations

project-webhooks

studies

Lab

Planned Measurements

Health check

Generate Protocol Endpoint

Parameters

Returns

Raises

Body

Response