Start a run

Start one managed-agent run. generate authors the recipe and stops at a preview; update edits it per message; clarify asks a read-only question; execute runs the approved preview for real. generate opens a preview run and update/clarify/execute resume that same run, so the run_id stays stable from preview through execution (a resuming call returns status: "running"). Only one run runs at a time per migration (409 with the active run_id otherwise).

POST /migrations/{migration_id}/runs

cURL

generate

curl --request POST \
  --url https://app.vern.so/api/v1/migrations/{migration_id}/runs \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "kind": "generate"
}
'

201

{
  "run_id": "d4c3b2a1-9f8e-47d6-b5a4-c3d2e1f0a9b8",
  "status": "queued",
  "poll_url": "https://app.vern.so/api/v1/migrations/c0a8012e-.../runs/d4c3b2a1-9f8e-47d6-b5a4-c3d2e1f0a9b8"
}

Authorizations

x-api-key · string · header · required

Your Vern API key. Create one at Settings → API keys.

Path Parameters

migration_id · string<uuid> · required

The migration ID returned by Create a migration.

Body

application/json

kind · enum<string> · required

Available options: generate, update, clarify, execute

message · string

Required for update and clarify — your instruction or question in plain language.

extract_via_api · boolean

generate only. Controls live API extraction from a connected source: true extracts via the connection (alongside any files), false forces file-only, omitted extracts via API only when no files were uploaded and a connection exists.

instructions · string | null

generate only. Optional guidance for this migration (at most 200 characters), e.g. "Only import active customers". The agent follows it but it cannot override Vern's rules, a locked template or the Memory setting. Kept for every later leg of the run and returned on the run as instructions. Longer than 200 characters returns 400 with code instructions_too_long.

Maximum string length: 200

Response

201

application/json

The run was accepted. A generate is queued; a resuming update/clarify/execute is running. Poll poll_url.

run_id · string<uuid>

status · string

Example:

"queued"

poll_url · string<uri>