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

# Answer the agent

> Reply when the agent pauses to ask you a question.

Sometimes the agent needs something from you to carry on, such as a choice between two options. It asks a question and the session pauses with status `awaiting_human`. You answer through the API and the agent picks up where it left off.

## Find the question

When the agent asks, the session's events include a `hitl_requested` event:

```json theme={null}
{
  "id": "…",
  "type": "hitl_requested",
  "timestamp": "2026-11-02T12:01:30.000Z",
  "data": {
    "correlation_id": "3b2f6c1e-…",
    "question": "There are two accounts on this phone. Which one should I use?",
    "options": ["Personal", "Work"]
  }
}
```

| Field | Meaning |
| - | - |
| `data.correlation_id` | Identifies the question. You send it back with your answer. |
| `data.question` | What the agent is asking. |
| `data.options` | Suggested answers, when the agent offered some. You can still answer with other text. |

Read events with `GET /v1/sessions/{id}/events`. See [Follow a session](https://docs.lusor.ai/agents/follow-a-session.md).

## Answer it

```bash cURL theme={null}
curl https://api.lusor.ai/v1/sessions/<session id>/hitl \
  -H "X-Api-Key: $LUSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "correlation_id": "3b2f6c1e-…", "response": "Work" }'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.lusor.ai/v1/sessions/<session id>/hitl",
    headers={"X-Api-Key": os.environ["LUSOR_API_KEY"]},
    json={"correlation_id": "3b2f6c1e-…", "response": "Work"},
)
print(r.status_code, r.json())
```

```javascript Node.js theme={null}
const res = await fetch("https://api.lusor.ai/v1/sessions/<session id>/hitl", {
  method: "POST",
  headers: { "X-Api-Key": process.env.LUSOR_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ correlation_id: "3b2f6c1e-…", response: "Work" }),
});
console.log(res.status, await res.json());
```

The call returns `202` and the agent continues with your text as its reply. If the phone is busy with another session, the response has `continuation.queued: true` and the agent continues when the phone is free.

Sending the same answer again is safe: the response has `idempotent: true` and nothing changes. A question can be answered until the session ends or the agent moves on to a newer question.

### Errors

| Status | `error` | Meaning |
| - | - | - |
| `400` | `bad_request` | `correlation_id` or `response` is missing. |
| `403` | `secure_ask_dashboard_only` | The question asks for a password or code. See below. |
| `404` | `not_found` | The session, or a question with this `correlation_id` in it, does not exist. |
| `409` | `conflict` | The question was already answered with different text. The first answer stands. |
| `410` | `stale_hitl_request` | The session has ended, or a newer question replaced this one. |
| `402` | `credits_exhausted`, `billing_required` | The agent cannot continue for billing reasons. See [Credits and minutes](https://docs.lusor.ai/billing/credits-and-minutes.md). |

## Passwords and codes

Some questions ask for a secret: a password, or a sign-in code. In the event, `data.kind` is `credential` or `2fa`. Lusor never accepts secret values through the API, so these are handled differently:

* **Sessions you start with an API key** use the secrets saved in your workspace's **Vault** in the Lusor app, by name. See [Use saved secrets](#use-saved-secrets) below. They never pause for a secret: when the agent needs one it was not given, the session ends at once with status `failed` and `error` set to `secret_required:<name>`, where `<name>` says what was needed, for example `gmail_password`.
* **Sessions started in the Lusor app** pause and wait. Only the Lusor app can answer them. An answer sent with an API key returns `403` with `error: "secure_ask_dashboard_only"`, nothing is stored, and the session stays paused.

To finish a task that needs a secret, save it in the Vault and name it in `secrets`, sign in to the app on the phone yourself first, or give the task to the agent from the [Lusor app](https://app.lusor.ai), where it can ask you for the secret safely.

### Use saved secrets

1. In the [Lusor app](https://app.lusor.ai), open **Vault** and save the login, for example an item titled "Gmail" with the fields `username` and `password`. Secrets are added, changed and deleted only in the app, never with an API key.
2. List the names with your API key: `GET /v1/workspaces/{workspaceId}/vault`. Each item has a `slug` and `fields`. A secret's name is `<slug>.<field>`, for example `gmail.password`. Values are never returned.
3. Name the secrets the run may use when you create the session:

```json theme={null}
{
  "prompt": "Sign in to Gmail and read the newest email's subject",
  "secrets": ["gmail.username", "gmail.password"]
}
```

The agent types them on the phone without the model ever seeing the values. With `secrets`, the run can use only the secrets you named: `[]` allows none. Without `secrets`, it can use every secret saved in the workspace.

A name that is not saved returns `422` with `error: "unknown_secret"` and the names in `missing`, and no session is created. Reusing an `Idempotency-Key` with a different `secrets` list returns `409` `idempotency_conflict`.


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