> ## 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's question (request_human) > When the agent asks a question, the run pauses: the session's status becomes `awaiting_human` and its events include a `hitl_requested` event whose `data.correlation_id` identifies the question (`data.question`, and `data.options` when the agent offered answer labels). Post the answer here; the run resumes with your text as the reply. A question stays answerable until the session ends or a newer message supersedes it. Only plain questions can be answered here. A request for a secret (a `hitl_requested` event whose `data.kind` is `credential` or `2fa`) is answered only in the Lusor dashboard: any reply to it made with an API key returns `403` `secure_ask_dashboard_only` and stores nothing. A run created with an API key never reaches that state: when the agent asks for a secret, the run ends as `failed` with `error` `secret_required:` (see `SessionV2.error`) instead of pausing, so there is nothing to answer. Save the secret in the workspace, then retry the run naming it in `secrets`. Retrying with the same text is idempotent (`idempotent: true`). A different answer to a question that was already answered returns `409`; the first answer stands. Workspace scope: `workspaceId` in the body, otherwise the workspace bound to the API key. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/sessions/{id}/hitl openapi: 3.1.0 info: title: Lusor API version: 0.1.0 description: | Run AI agents on real phones, or drive a phone directly with deterministic actions. ## Authentication Every `/v1/*` endpoint except `GET /v1/health` requires an API key. Create one in the Lusor dashboard under **Settings → API Keys**. A key is shown once and is bound to one workspace. Revoking it there stops it working immediately. Send it in either header: - `X-Api-Key: ` - `Authorization: Bearer ` Because a key is bound to its workspace, `workspaceId` query and body parameters are optional for API-key callers. A request that names a different workspace returns an opaque `404`. ## Runs Use `POST /v1/agents/{id}/turns` to start or continue an agent run. Read the run under `/v1/sessions/{id}`; poll `GET /v1/sessions/{id}/status` or `GET /v1/sessions/{id}/events` for progress. ## Errors Errors are JSON: `{ "error": "", "message": "" }`. A request that fails validation returns `400` in one of two shapes, depending on the endpoint: `{ "error": "validation_error", "details": { ... } }` (direct phone control actions, for example), or `{ "error": "bad_request", "message": "" }` (agent endpoints, for example). Branch on `error`. contact: name: Lusor url: https://lusor.ai license: name: Proprietary url: https://lusor.ai/terms servers: - url: https://api.lusor.ai description: Production security: - ApiKey: [] - BearerAuth: [] tags: - name: Agents description: Persistent agents, the phone each one uses, and their turns (runs). - name: Secrets description: | Secrets saved in a workspace (passwords, sign-in details). A run uses them by name through `secrets`; values never travel in a request. - name: Sessions description: | Run records: list, inspect, stop, and read events and artifacts. Start a run with `POST /v1/agents/{id}/turns`, or without an agent through `POST /v1/workspaces/{workspaceId}/devices/{deviceId}/sessions`. - name: LiveView description: | View-only WebRTC live view of a session's phone: signaling, ICE servers, and stream control. API keys get live view only on the customer's own phone, not on a Lusor Phone. - name: Devices description: | The phones in your workspace, and reads of their current screen and UI tree. - name: DeviceVerbs description: | Direct phone control: deterministic actions (tap, swipe, type, key, clear, back, home, recent, screenshot, apps/start, apps/stop) and chains of them. On a Lusor Phone, API-key calls meter phone minutes. - name: Shell description: | Restricted shell escape hatch. Commands are checked against a denylist and audit-logged. No command output is returned. - name: Datasets description: Lists a run produced, saved as reusable Datasets. - name: Skills description: Reusable automation skills (Markdown documents). - name: PhoneNumbers description: | Workspace phone numbers and their stored SMS messages. Read-only for API keys. - name: Emails description: | Workspace Agent Mail addresses and stored inbound mail. Read-only: there is no compose, reply, or send endpoint, and message bodies are returned as raw plain text without HTML execution, remote asset fetches, or code extraction. - name: Workspaces description: The workspace an API key is bound to. - name: Catalog description: The catalog of apps that can be installed on a Lusor Phone. - name: Health description: Service health check. paths: /v1/sessions/{id}/hitl: post: tags: - Sessions summary: Answer the agent's question (request_human) description: | When the agent asks a question, the run pauses: the session's status becomes `awaiting_human` and its events include a `hitl_requested` event whose `data.correlation_id` identifies the question (`data.question`, and `data.options` when the agent offered answer labels). Post the answer here; the run resumes with your text as the reply. A question stays answerable until the session ends or a newer message supersedes it. Only plain questions can be answered here. A request for a secret (a `hitl_requested` event whose `data.kind` is `credential` or `2fa`) is answered only in the Lusor dashboard: any reply to it made with an API key returns `403` `secure_ask_dashboard_only` and stores nothing. A run created with an API key never reaches that state: when the agent asks for a secret, the run ends as `failed` with `error` `secret_required:` (see `SessionV2.error`) instead of pausing, so there is nothing to answer. Save the secret in the workspace, then retry the run naming it in `secrets`. Retrying with the same text is idempotent (`idempotent: true`). A different answer to a question that was already answered returns `409`; the first answer stands. Workspace scope: `workspaceId` in the body, otherwise the workspace bound to the API key. operationId: answerSessionHitl parameters: - $ref: '#/components/parameters/SessionId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AnswerHitlInput' responses: '202': description: Answer accepted; the run resumes content: application/json: schema: $ref: '#/components/schemas/AnswerHitlResult' '400': description: | `bad_request`: `correlation_id` or `response` is missing, or the question is a secret request. `card_details_not_allowed`: the question is a secret request and `response` is a payment card number. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '402': description: >- `credits_exhausted` or `billing_required`, as for `POST /v1/sessions/{id}/continue`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: | `secure_ask_dashboard_only`: the question is a secret request (`data.kind` `credential` or `2fa`), which only the Lusor dashboard can answer. Nothing is stored and the run stays paused. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- The session, or a question with this `correlation_id` in it, was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: | `conflict`: the question was already answered with different text; this answer was discarded. The other `409` codes of `POST /v1/sessions/{id}/continue` also apply. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '410': description: >- `stale_hitl_request`: the session has ended, or a newer message superseded the question. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: '`device_busy`: the phone is running a different session.' content: application/json: schema: $ref: '#/components/schemas/Busy' '500': description: >- `db_error`: the answer was not accepted and could not be rolled back; retry shortly. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '502': $ref: '#/components/responses/UpstreamError' components: parameters: SessionId: name: id in: path required: true schema: type: string description: Session ID. schemas: AnswerHitlInput: type: object required: - correlation_id - response properties: correlation_id: type: string format: uuid description: '`data.correlation_id` of the `hitl_requested` event being answered.' response: type: string minLength: 1 description: >- The answer. For a question with `options`, the chosen label or any other text. workspaceId: type: string format: uuid description: Optional for workspace-scoped API keys. AnswerHitlResult: type: object required: - data properties: data: type: object required: - resolved - idempotent - continuation properties: resolved: type: boolean description: Always `true`. idempotent: type: boolean description: '`true` when this repeats an answer that was already accepted.' continuation: type: object required: - status - invocationId - queued properties: status: type: string enum: - queued invocationId: type: - string - 'null' queued: type: boolean description: >- `true` when the resumed run waits behind a run still on the phone. ErrorResponse: type: object required: - error - message properties: error: type: string message: type: string Busy: type: object description: | A `429` refusal. `device_busy` carries `currentSessionId` (the run holding the phone); `cap_busy` does not. Any authenticated request can also get `rate_limit_exceeded` when the API's request rate limit is exceeded; it comes with a `Retry-After` header in seconds. required: - error properties: error: type: string enum: - device_busy - cap_busy - rate_limit_exceeded currentSessionId: type: - string - 'null' message: type: string responses: Unauthorized: description: Authentication required or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' UpstreamError: description: The phone or a Lusor service could not be reached. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKey: type: apiKey in: header name: X-Api-Key description: Workspace API key, created in the dashboard under Settings → API Keys. BearerAuth: type: http scheme: bearer description: >- The same workspace API key, sent as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.