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

# When the agent needs an answer

> Questions before a demo starts, and logins or codes the agent asks for while it records.

The agent can need something from you at two points: before the demo starts, when your task is unclear, and while it records, when it reaches a sign-in page or a verification code.

## Before the demo: questions about the task

`POST /demos/check` and `POST /demos` read your task first. If something is unclear, you get the questions instead of a demo:

* `/demos/check` answers `200` with `status: "needs_answers"`.
* `/demos` answers `422` with the error code `needs_answers`, and the same result in `error.details`.

```json theme={null}
{
  "status": "needs_answers",
  "check_id": "Jq3x9VfT2bLm8RkQ0aZy1w",
  "questions": [
    {
      "id": "q1",
      "question": "Which event type should the demo book?",
      "required": true,
      "kind": "choice",
      "choices": [
        { "id": "a", "text": "A 15-minute intro call" },
        { "id": "b", "text": "A 30-minute meeting" }
      ]
    }
  ]
}
```

Send the same request again with the `check_id` and your `answers`. A `check_id` is valid for 1 hour.

```json theme={null}
{
  "url": "https://cal.com",
  "task": "Show how to book a meeting from a public booking page",
  "check_id": "Jq3x9VfT2bLm8RkQ0aZy1w",
  "answers": [{ "question_id": "q1", "choice_id": "b" }]
}
```

> [!TIP]
>
> Send `site_login: { "username", "password" }` with the request if the demo needs one. It's encrypted on arrival, used only by the agent, never logged and never returned. A login question can also be answered with the choice `later`: the agent then asks for the login when it reaches the sign-in page.

## While recording: logins and codes

If the agent reaches a sign-in page without a login, or the site sends a verification code, the demo pauses:

* `status` becomes `input_required`;
* you get a [`demo.input_required`](https://developers.demosmith.ai/webhooks#events) webhook;
* the demo has an `input_request`:

```json theme={null}
"input_request": {
  "id": "0c1d6c2b-6f0a-4b7e-9d3a-2b8e5f7a1c90",
  "kind": "verification_code",
  "question": "Enter the 6-digit code sent to the account's email",
  "suggestions": [],
  "expires_at": "2026-11-07T12:05:00Z",
  "answer_url": "https://app.demosmith.ai/demos/5b9e3c7a-2f41-4c8e-9a51-7d0b6e2f1c34?answer=0c1d6c2b-6f0a-4b7e-9d3a-2b8e5f7a1c90"
}
```

| `kind` | The agent is asking for |
| - | - |
| `login` | A username or password for the site |
| `verification_code` | A one-time code |
| `question` | Something else it needs to continue |
| `confirmation` | A yes or no before an action |

Each request asks for one value. For a login, the agent may ask for the username and then the password, one after the other.

### Answer it

> [card] From your code
>
> `POST /demos/{id}/input-requests/{request_id}/answer` with `{"value": "..."}`. Works for every kind.

> [card] From a person
>
> Send someone the `answer_url`. It opens the demo in the app with the question ready to answer.

Answers are single use. A request that isn't answered by `expires_at` expires: the agent carries on without the answer if it can, and otherwise the demo fails with a message saying what was missing.

> [!WARNING]
>
> AI assistants never accept logins or codes. Over MCP, the assistant gives the person the `answer_url` instead, so a password never goes through a chat.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.