When the agent needs an answer

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.

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

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

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 webhook;
the demo has an input_request:

"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

From your code

POST /demos/{id}/input-requests/{request_id}/answer with {"value": "..."}. Works for every kind.

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.

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.

Get started

Build

Before the demo: questions about the task

While recording: logins and codes

Answer it

From your code

From a person

​Before the demo: questions about the task

​While recording: logins and codes

​Answer it

From your code

From a person

Before the demo: questions about the task

While recording: logins and codes

Answer it