Start a run

POST https://app.vern.so/api/v1/migrations/{migration_id}/runs

Starts one managed-agent run. A run does a single phase of work and returns a run_id you poll to a terminal state. Only one run runs at a time per migration — starting a second while one is in flight returns 409. {migration_id} is the id from creating a migration.

Authentication

Requires an x-api-key header. See Authentication.

Request body

kind

string

required

Which phase to run:

generate — author the mapping recipe and stop at a preview. Needs a data source: at least one uploaded file, a connected live source, or both.
update — edit the current recipe per message, producing a new preview that replaces the current one. Requires an existing preview.
clarify — ask a read-only question about the current preview. Returns an answer in the run thread and changes nothing. Requires an existing preview.
execute — run the approved preview’s recipe as the real import. Requires a ready preview.

message

string

Required for update and clarify — your instruction or question in plain language (e.g. "Use the company domain for any missing Email, don't drop the row."). Ignored for generate and execute.

extract_via_api

boolean

generate only. Explicitly controls live API extraction from a connected source:

true — extract via the connection (alongside any uploaded files).
false — file-only; never extract via API, even with no files.
omitted — the default: extract via API only when no files were uploaded and a connection exists.

Ignored for update, clarify, and execute. Must be a boolean.

The recipe and preview state are carried server-side between phases — you never send recipe, preview, or build IDs. execute runs the recipe behind the current preview; update/clarify act on it.

generate opens a preview run; update, clarify, and execute resume that same run, so the run_id stays stable from preview all the way through the real import. A resuming call comes back with status: "running" rather than queued.

Response

201 Created

{
  "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"
}

Poll poll_url until the run is terminal for its phase:

generate / update → awaiting_approval (a preview is ready), or blocked if the agent has a question.
clarify → completed (read the answer from the thread).
execute → completed with a report, or failed.

See Poll a run for every status shape, and Get the preview to read what generate/update produced.

The typical loop

generate ──▶ awaiting_approval ──▶ execute ──▶ completed
                  │  ▲
        update /  │  │ new preview
        clarify ──┘──┘

generate once, after uploading files.
Review the preview. Refine with update (changes the recipe) or ask via clarify (read-only) as many times as you need — each update yields a fresh preview.
execute when you’re happy. The report tells you what landed.

Errors

Status	Meaning
`400`	`kind` missing or invalid; `generate` with no files and no connected source; `extract_via_api` not a boolean; `update`/`clarify` with no `message`.
`401`	API key missing or invalid.
`404`	No migration with that `{migration_id}` in your account.
`409`	A run is already in progress (the body includes the active `run_id`); the migration has no target templates; `update`/`clarify`/`execute` with no current preview to act on; the approved preview is no longer resumable (generate a fresh one).
`429`	Rate limit hit — back off and retry.
`500`	Server error.

A 409 from an in-flight run is how you recover a run you lost track of — the response carries its run_id:

{ "error": "A run is already in progress for this migration.", "run_id": "d4c3b2a1-..." }

Examples

# 1 · generate a preview
curl -X POST https://app.vern.so/api/v1/migrations/c0a8012e-.../runs \
  -H "x-api-key: $VERN_API_KEY" -H "Content-Type: application/json" \
  -d '{ "kind": "generate" }'

# 2 · refine it
curl -X POST https://app.vern.so/api/v1/migrations/c0a8012e-.../runs \
  -H "x-api-key: $VERN_API_KEY" -H "Content-Type: application/json" \
  -d '{ "kind": "update", "message": "Trim whitespace from every phone number." }'

# 3 · ask a read-only question
curl -X POST https://app.vern.so/api/v1/migrations/c0a8012e-.../runs \
  -H "x-api-key: $VERN_API_KEY" -H "Content-Type: application/json" \
  -d '{ "kind": "clarify", "message": "Which column did you map Email from?" }'

# 4 · execute for real
curl -X POST https://app.vern.so/api/v1/migrations/c0a8012e-.../runs \
  -H "x-api-key: $VERN_API_KEY" -H "Content-Type: application/json" \
  -d '{ "kind": "execute" }'

Poll a run — track the run, read the report, cancel it.
Get the preview — read the generated output.
Answer the agent — resume a blocked run.
Connect a live source — extract via API with extract_via_api.

Overview

Get started

API reference

Reference

Authentication

Request body

Response

The typical loop

Errors

Examples

Next

​Authentication

​Request body

​Response

​The typical loop

​Errors

​Examples

​Next

Authentication

Request body

Response

The typical loop

Errors

Examples

Next