Answer the agent

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:

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

Answer it

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" }'

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())

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.

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 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, where it can ask you for the secret safely.

Use saved secrets

In the Lusor app, 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.
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.
Name the secrets the run may use when you create the session:

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

Get started

Agents & sessions

Phones

Billing and limits

Answer the agent

Find the question

Answer it

Errors

Passwords and codes

Use saved secrets

​Find the question

​Answer it

​Errors

​Passwords and codes

​Use saved secrets

Find the question

Answer it

Errors

Passwords and codes

Use saved secrets