Skip to main content
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 from the uploaded files and stop at a preview. Requires at least one uploaded file.
  • 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.
The recipe and preview state are copied 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.

​
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 ──┘──┘
  1. generate once, after uploading files.
  2. 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.
  3. execute when you’re happy. The report tells you what landed.

​
Errors

StatusMeaning
400kind missing or invalid; generate with no files uploaded; update/clarify with no message.
401API key missing or invalid.
404No migration with that {migration_id} in your account.
409A 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.
429Rate limit hit — back off and retry.
500Server 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" }'

​
Next