Commands

Every write is a command. There is one route, a closed set of kinds, and the command line sends the same ones.

Under /api/v1
Method	Path	What it does
POST	`/commands/{kind}`	The closed-set command surface: every wired kind validates against its declared schema, then dispatches.

Request

POST http://127.0.0.1:8001/api/v1/commands/{kind}
Content-Type: application/json
Idempotency-Key: <a key you choose>
Expected-Version: <optional>

{"kind": "<the same kind as the path>", "payload": { … }}

Idempotency-Key is required: without it the answer is a 400 with idempotency_key_missing. The kind in the body must equal the kind in the path.

Response 202 Accepted

{"command_id": "…"}

The command is accepted, not finished. Read the result through the read routes or the event stream. Five kinds answer with their own typed body instead; they are marked below.

Command kinds

The closed set
Kind	CLI verb	Answers
`mint-campaign`	`new`	202
`start-run`	`resume`	202
`fork-cycle`	`resume`	202
`step-cycle`		202
`pause-cycle`	`pause`	202
`skip-searchpoint`		202
`set-sample-lookahead`		202
`origin-gate-decision`	`origin-gate`	202
`verify-candidate`	`verify`	202
`grade-bench`	`bench`	202
`change-run-limits`	`set-limits`	202
`set-concurrent-cycles`		202
`cancel-queued-run`	`cancel-queued`	202
`delete-cycle`		202
`cleanup-empty-cycles`		202
`archive-campaign`	`archive`	202
`unarchive-campaign`	`unarchive`	202
`delete-campaign`	`delete`	202
`set-campaign-label`	`rename`	202
`register-backend`	`new`	202
`start-checkin`	`new`	its own body
`edit-draft-campaign`	`new`	its own body
`resolve-origin`	`new`	its own body
`replace-dataset`		its own body
`compact-archive`		its own body

start-checkin answers with campaign_id, cycle_id and job_id. Most other payloads are a campaign (campaign_id) or a cycle (campaign_id, cycle_id, optional descend) plus the fields of the kind.

mint-campaign payload

dataset_name string required: The dataset to run on.
limits object optional: halt_at_accuracy, ceiling {usd, tokens}, step_rounds.
backend_url string optional: Defaults to http://127.0.0.1:8000.
backend_id string optional: Defaults to local.
task_text string optional
optimization object optional
campaign_config object optional
arm optional
diag optional

start-run payload

campaign_id string required
cycle_id string required
limits object optional: As on mint-campaign.
mode object optional: from_round, no_divergence_check, fork_on_divergence, diag.

The full schema of every kind is in the generated reference, at /docs on a running install.