> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vern.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Answer the agent

> Render the agent's clarifying questions in your own UI and answer them — or send a free-form correction — to resume a blocked run.

```http theme={null}
POST https://app.vern.so/api/v1/migrations/{migration_id}/runs/{run_id}/messages
```

When the [managed agent](/migration-api/concepts#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`](/migration-api/concepts#runs) instead of guessing. The
[poll response](/migration-api/poll-a-run) 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](/migration-api/authentication).

## What you get to render

A `blocked` poll response looks like this:

```json theme={null}
{
  "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.

<ParamField path="id" type="string">
  Stable identifier you echo back in your answer.
</ParamField>

<ParamField path="question" type="string">
  The question, in plain language. Show it as the field label.
</ParamField>

<ParamField path="context" type="string">
  Optional extra detail about why the agent is asking. May be absent.
</ParamField>

<ParamField path="options" type="object[]">
  Suggested answers, each `{ id, label }`. Render them as choices (radio buttons,
  a select, buttons). May be empty for an open-ended question.
</ParamField>

<ParamField path="allowCustom" type="boolean">
  When `true`, let the customer type a free-text answer instead of picking an
  option.
</ParamField>

## 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.

<ParamField body="answers" type="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.
</ParamField>

```json theme={null}
{
  "answers": [
    { "id": "q1", "value": "Treat CANCELLED as inactive" }
  ]
}
```

```json theme={null}
{
  "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](/migration-api/poll-a-run) and answering until it's terminal.

<Note>
  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](/migration-api/start-a-run) instead.
</Note>

<Warning>
  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](/migration-api/submit-credentials) instead.
</Warning>

Your reply is echoed back on later [poll responses](/migration-api/poll-a-run) as
`answers`, so a UI can show what was submitted.

## Response

`200 OK`

```json theme={null}
{
  "run_id": "d4c3b2a1-9f8e-47d6-b5a4-c3d2e1f0a9b8",
  "status": "running"
}
```

Resume [polling](/migration-api/poll-a-run) 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](/migration-api/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

```bash theme={null}
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'\''" }] }'
```

## Next

* [Poll a run](/migration-api/poll-a-run) — track the resumed run.
* [Submit credentials](/migration-api/submit-credentials) — resume a credential block instead.
* [Get the preview](/migration-api/get-the-preview) — review the result.