Answer the agent

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

When the managed agent hits a mapping it genuinely can’t settle on its own — the data, your templates, and the source all leave it ambiguous — the run pauses at blocked instead of guessing. The poll response then carries plain-language questions for you to render in your own product, and this endpoint is how you send the answer back. Nothing changes while a run waits here. The agent is suspended; your answer is what resumes it — the run flips back to running.

Authentication

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

What you get to render

A blocked poll response looks like this:

{
  "status": "blocked",
  "blocked_reason": "question",
  "questions": [
    {
      "id": "q1",
      "question": "Some Status values aren't one of the allowed options (Open, Closed, Pending). How should I handle them?",
      "options": [
        { "id": "a", "label": "Map them all to 'Open'" },
        { "id": "b", "label": "Drop those rows" }
      ],
      "allowCustom": true
    }
  ]
}

Each question is self-describing — you can render it in your UI without knowing anything about Vern’s internals.

string

Stable identifier you echo back in your answer.

question

string

The question, in plain language. Show it as the field label.

context

string

Optional extra detail about why the agent is asking. May be absent.

options

object[]

Suggested answers, each { id, label }. Render them as choices (radio buttons, a select, buttons). May be empty for an open-ended question.

allowCustom

boolean

When true, let the customer type a free-text answer instead of picking an option.

Answering

Send answers as either the structured form — one { id, value } per question — or a free-form string when you’d rather just tell the agent what to do. Both resume the run.

answers

object[] | string

required

Structured: one { id, value } per question you’re answering, where id matches the question and value is the chosen option’s label or free text. Free-form: a plain string the agent reads as your reply.

{
  "answers": [
    { "id": "q1", "value": "Treat CANCELLED as inactive" }
  ]
}

{
  "answers": "Use the company domain for any missing Email, don't drop the row."
}

The agent applies your answer and resumes. If it can now finish, the run reaches awaiting_approval (for a generate/update) or completed; if another mapping is still ambiguous, it blocks again with a fresh question — keep polling and answering until it’s terminal.

Answering only applies to a blocked run. To steer a migration outside of a block — to correct a mapping after reviewing the preview — start an update or clarify run instead.

This endpoint is for question blocks (blocked_reason: "question") only. A run blocked for credentials (blocked_reason: "credentials") rejects a message with 409 — so secrets never land in the agent thread. Send those through Submit credentials instead.

Your reply is echoed back on later poll responses as answers, so a UI can show what was submitted.

Response

200 OK

{
  "run_id": "d4c3b2a1-9f8e-47d6-b5a4-c3d2e1f0a9b8",
  "status": "running"
}

Resume polling the run until it reaches a terminal status.

Errors

Status	Meaning
`400`	`answers` missing or empty.
`401`	API key missing or invalid.
`404`	No such run, or the migration isn’t in your account.
`409`	The run isn’t `blocked` (already resumed, or never paused), the run is blocked for credentials (use Submit credentials), or the agent has no active question to answer yet — retry shortly.
`429`	Rate limit hit — back off and retry.
`500`	Server error.

Example

curl -X POST \
  https://app.vern.so/api/v1/migrations/c0a8012e-.../runs/d4c3b2a1-.../messages \
  -H "x-api-key: $VERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "answers": [{ "id": "q1", "value": "Map them all to '\''Open'\''" }] }'

Poll a run — track the resumed run.
Submit credentials — resume a credential block instead.
Get the preview — review the result.

Overview

Get started

API reference

Reference

Authentication

What you get to render

Answering

Response

Errors

Example

Next

​Authentication

​What you get to render

​Answering

​Response

​Errors

​Example

​Next

Authentication

What you get to render

Answering

Response

Errors

Example

Next