POST /runs#

Queue a new optimization run. Returns immediately with a run id; poll GET /runs/{id} or supply a webhook_url to be pushed updates.

Request body

pipeline string | object required

A published pipeline definition, or a URL/ID pointing to one. Tuned read-only — PromptPotter never edits it.

dataset array | string required

Labelled input/output pairs, or a URL to JSONL of the same shape. Candidates are scored against these.

model string optional

Provider/model string for generation and critique. Defaults to the workspace model.

rounds integer optional

Max generate → score → critique rounds. Default 8.

population integer optional

Candidates L1 proposes each round. Default 12.

layers string[] optional

Enabled escalation layers. Default ["l1","l2","l3"] — L1 generates, L2 reframes, L3 replans.

webhook_url string optional

If set, round and run events are POSTed here as they happen (see Webhooks).

Example

curl -X POST https://app.promptpotter.dev/api/v1/runs \
  -H "Authorization: Bearer $PROMPTPOTTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": "pl_entity_norm",
    "dataset": "https://example.com/labelled.jsonl",
    "model": "anthropic/claude-haiku-4-5",
    "rounds": 12
  }'

Response 202 Accepted

{
  "id": "run_8fK2a",
  "status": "queued",
  "created_at": "2026-05-29T18:40:00Z"
}