> ## 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. # Run a chain of actions > Execute a typed sequence of up to 20 deterministic actions in order, optionally collecting a UI capture per step. On a Lusor Phone, an API-key chain meters phone minutes before every step; a `402` or `503` stops the chain before that step reaches the phone. ## Capture resolution rules Per-step `capture` always wins. Top-level `capture` supplies the default policy: - `'none'` (default) — no capture on any step. - `'each'` — capture on every step. - `'final'` — capture only on the last step. ## Step verbs `tap`, `swipe`, `type`, `key`, `clear`, `back`, `home`, `recent`, `start_app`, `stop_app`, `screenshot`, `wait`. Each step has the same params as the corresponding direct-verb route plus an optional `capture` override. ## Settling Steps execute back-to-back with no implicit inter-step delay. Insert `wait` steps (`{ verb: "wait", params: { duration_ms: N } }`, 0–60000 ms) where the UI needs time to settle — e.g. after a tap that opens a screen, or before typing into a freshly focused field. Cumulative wait duration per chain is capped at 120s so the worst case stays inside the chain timeout. A step that completes with `ok: false` does not stop the chain: the next step still runs, the top-level `ok` is true only when every step succeeded, and each step's `ok` shows which one failed. A step that errors instead aborts the chain. This happens when the phone cannot be reached, when a step's capture fails, or when metering refuses a later step (`402`/`503`). The response is then that error alone, with no per-step results, and the steps before it have already run on the phone. Read the screen before you retry a chain. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/workspaces/{workspaceId}/devices/{deviceId}/chain 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/workspaces/{workspaceId}/devices/{deviceId}/chain: post: tags: - DeviceVerbs summary: Run a chain of actions description: | Execute a typed sequence of up to 20 deterministic actions in order, optionally collecting a UI capture per step. On a Lusor Phone, an API-key chain meters phone minutes before every step; a `402` or `503` stops the chain before that step reaches the phone. ## Capture resolution rules Per-step `capture` always wins. Top-level `capture` supplies the default policy: - `'none'` (default) — no capture on any step. - `'each'` — capture on every step. - `'final'` — capture only on the last step. ## Step verbs `tap`, `swipe`, `type`, `key`, `clear`, `back`, `home`, `recent`, `start_app`, `stop_app`, `screenshot`, `wait`. Each step has the same params as the corresponding direct-verb route plus an optional `capture` override. ## Settling Steps execute back-to-back with no implicit inter-step delay. Insert `wait` steps (`{ verb: "wait", params: { duration_ms: N } }`, 0–60000 ms) where the UI needs time to settle — e.g. after a tap that opens a screen, or before typing into a freshly focused field. Cumulative wait duration per chain is capped at 120s so the worst case stays inside the chain timeout. A step that completes with `ok: false` does not stop the chain: the next step still runs, the top-level `ok` is true only when every step succeeded, and each step's `ok` shows which one failed. A step that errors instead aborts the chain. This happens when the phone cannot be reached, when a step's capture fails, or when metering refuses a later step (`402`/`503`). The response is then that error alone, with no per-step results, and the steps before it have already run on the phone. Read the screen before you retry a chain. operationId: deviceChain parameters: - $ref: '#/components/parameters/WorkspaceIdPath' - $ref: '#/components/parameters/DeviceIdPath' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChainRequest' responses: '200': description: Chain executed content: application/json: schema: $ref: '#/components/schemas/ChainResponse' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '402': description: | Billing refused a step (`credits_exhausted` or `billing_required`). That step and the ones after it were not sent; steps before it may already have run. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/InternetRouteInactive' '503': description: | `meter_unavailable`: metering could not continue, so that step and the ones after it were not sent. Steps before it may already have run; read the screen before retrying. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: WorkspaceIdPath: name: workspaceId in: path required: true schema: type: string format: uuid description: Workspace UUID. Caller must have access. DeviceIdPath: name: deviceId in: path required: true schema: type: string description: Device id (paired into the workspace). schemas: ChainRequest: type: object required: - steps properties: steps: type: array minItems: 1 maxItems: 20 items: $ref: '#/components/schemas/ChainStep' capture: $ref: '#/components/schemas/ChainCapturePolicy' ChainResponse: type: object required: - ok - steps properties: ok: type: boolean description: | True iff every step's `ok` was true. steps: type: array items: $ref: '#/components/schemas/ChainStepResponse' ErrorResponse: type: object required: - error - message properties: error: type: string message: type: string ChainStep: description: | One step in a chain. The `params` shape is correlated with the `verb` discriminator via OpenAPI 3.1 `discriminator.mapping` — each variant carries the exact params shape its verb accepts. oneOf: - $ref: '#/components/schemas/TapChainStep' - $ref: '#/components/schemas/SwipeChainStep' - $ref: '#/components/schemas/TypeChainStep' - $ref: '#/components/schemas/KeyChainStep' - $ref: '#/components/schemas/ClearChainStep' - $ref: '#/components/schemas/BackChainStep' - $ref: '#/components/schemas/HomeChainStep' - $ref: '#/components/schemas/RecentChainStep' - $ref: '#/components/schemas/StartAppChainStep' - $ref: '#/components/schemas/StopAppChainStep' - $ref: '#/components/schemas/ScreenshotChainStep' - $ref: '#/components/schemas/WaitChainStep' discriminator: propertyName: verb mapping: tap: '#/components/schemas/TapChainStep' swipe: '#/components/schemas/SwipeChainStep' type: '#/components/schemas/TypeChainStep' key: '#/components/schemas/KeyChainStep' clear: '#/components/schemas/ClearChainStep' back: '#/components/schemas/BackChainStep' home: '#/components/schemas/HomeChainStep' recent: '#/components/schemas/RecentChainStep' start_app: '#/components/schemas/StartAppChainStep' stop_app: '#/components/schemas/StopAppChainStep' screenshot: '#/components/schemas/ScreenshotChainStep' wait: '#/components/schemas/WaitChainStep' ChainCapturePolicy: type: string enum: - each - final - none description: | Top-level capture policy for a chain request. Per-step `capture` always overrides this default. `'each'` captures every step; `'final'` captures only the last; `'none'` (default) captures nothing. ChainStepResponse: allOf: - $ref: '#/components/schemas/VerbResult' - type: object required: - verb properties: verb: $ref: '#/components/schemas/ChainVerb' resolved: type: object properties: x: type: integer 'y': type: integer index: type: integer cleared: type: boolean capture: $ref: '#/components/schemas/CaptureResponse' ValidationErrorResponse: type: object required: - error - details properties: error: type: string example: validation_error details: type: object additionalProperties: true TapChainStep: type: object required: - verb - params properties: verb: type: string enum: - tap params: $ref: '#/components/schemas/TapChainStepParams' capture: $ref: '#/components/schemas/CaptureField' SwipeChainStep: type: object required: - verb - params properties: verb: type: string enum: - swipe params: $ref: '#/components/schemas/SwipeChainStepParams' capture: $ref: '#/components/schemas/CaptureField' TypeChainStep: type: object required: - verb - params properties: verb: type: string enum: - type params: $ref: '#/components/schemas/TypeChainStepParams' capture: $ref: '#/components/schemas/CaptureField' KeyChainStep: type: object required: - verb - params properties: verb: type: string enum: - key params: $ref: '#/components/schemas/KeyChainStepParams' capture: $ref: '#/components/schemas/CaptureField' ClearChainStep: type: object required: - verb properties: verb: type: string enum: - clear params: $ref: '#/components/schemas/EmptyChainStepParams' capture: $ref: '#/components/schemas/CaptureField' BackChainStep: type: object required: - verb properties: verb: type: string enum: - back params: $ref: '#/components/schemas/EmptyChainStepParams' capture: $ref: '#/components/schemas/CaptureField' HomeChainStep: type: object required: - verb properties: verb: type: string enum: - home params: $ref: '#/components/schemas/EmptyChainStepParams' capture: $ref: '#/components/schemas/CaptureField' RecentChainStep: type: object required: - verb properties: verb: type: string enum: - recent params: $ref: '#/components/schemas/EmptyChainStepParams' capture: $ref: '#/components/schemas/CaptureField' StartAppChainStep: type: object required: - verb - params properties: verb: type: string enum: - start_app params: $ref: '#/components/schemas/StartAppChainStepParams' capture: $ref: '#/components/schemas/CaptureField' StopAppChainStep: type: object required: - verb - params properties: verb: type: string enum: - stop_app params: $ref: '#/components/schemas/StopAppChainStepParams' capture: $ref: '#/components/schemas/CaptureField' ScreenshotChainStep: type: object required: - verb properties: verb: type: string enum: - screenshot params: $ref: '#/components/schemas/EmptyChainStepParams' capture: $ref: '#/components/schemas/CaptureField' WaitChainStep: type: object required: - verb - params properties: verb: type: string enum: - wait params: $ref: '#/components/schemas/WaitChainStepParams' capture: $ref: '#/components/schemas/CaptureField' VerbResult: type: object required: - ok - exit_code - status properties: ok: type: boolean exit_code: type: integer description: | `0` on success, non-zero on failure. Currently derived from `ok`; it does not carry the command's own exit code. status: type: string commandId: type: string durationMs: type: - integer - 'null' message: type: string ChainVerb: type: string enum: - tap - swipe - type - key - clear - back - home - recent - start_app - stop_app - screenshot - wait description: Verb discriminator for a chain step. CaptureResponse: type: object description: | Capture payload. All inner fields are optional and present iff the corresponding source was captured: - `elements` / `element_count` / `screen_dimensions` — set iff `capture.ui` was true. - `screenshot_url` — set iff `capture.screenshot` was true. A screenshot-only capture (no UI) returns just `screenshot_url`; a UI-only capture returns the tree + count + dimensions; a full capture returns everything. The action has already run when the capture is taken. On a single action endpoint, a failed capture still returns `200` with `capture: { failed: true, error }`, so a retry does not repeat a non-idempotent action. Inside a chain, a failed capture aborts the chain with an error instead (see `POST …/chain`). properties: failed: type: boolean description: >- Present and `true` only when the capture failed on a single action endpoint. error: type: string description: Why the capture failed. Present only with `failed`. elements: type: string description: | Formatted element tree. Present iff `capture.ui` was true. The exact shape depends on `capture.verbosity`. element_count: type: integer minimum: 0 description: | Number of `[N]`-indexed interactive elements. Present iff `capture.ui` was true. screen_dimensions: type: object description: | Device screen size derived from the UI walk's bounding box. Present iff `capture.ui` was true. required: - width - height properties: width: type: integer minimum: 0 height: type: integer minimum: 0 screenshot_url: type: string description: | Present iff `capture.screenshot` was true. Links to the `GET /screenshot` endpoint, which needs the same API key and takes a new screenshot when fetched (metered on a Lusor Phone like any read). Fetch it before the next action if you want the screen this action left behind. TapChainStepParams: type: object description: | Step `params` for a `tap` step — the `TapInput` shape without `capture`, which is a sibling field of `params` on the step. Provide `index`, or `x`+`y`, or both; when both are supplied `index` wins. Supplying neither is a 400, and `x` without `y` is a 400 only when no `index` is supplied. anyOf: - required: - index - required: - x - 'y' properties: index: type: integer minimum: 1 x: type: number 'y': type: number stealth: type: boolean CaptureField: description: | `capture: boolean | CaptureOptions`. `true` captures with defaults; an object lets the caller override individual knobs. `false` or omitted = no capture. oneOf: - type: boolean - $ref: '#/components/schemas/CaptureOptions' SwipeChainStepParams: type: object required: - startX - startY - endX - endY properties: startX: type: number startY: type: number endX: type: number endY: type: number durationMs: type: integer minimum: 1 maximum: 60000 stealth: type: boolean TypeChainStepParams: type: object required: - text properties: text: type: string minLength: 1 maxLength: 8192 clear: type: boolean stealth: type: boolean KeyChainStepParams: type: object required: - keyCode properties: keyCode: type: integer minimum: 0 maximum: 2000 EmptyChainStepParams: type: object description: | Empty params object for verbs without inputs (`clear`, `back`, `home`, `recent`, `screenshot`). Server treats both `params: {}` and an omitted `params` as equivalent. StartAppChainStepParams: type: object required: - package properties: package: type: string minLength: 1 maxLength: 255 pattern: ^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$ description: | Same constraint as `StartAppInput.package` — a case-insensitive dotted Java identifier, validated before dispatch. activity: type: string minLength: 1 maxLength: 255 pattern: ^\.?[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)*$ description: | Relative-or-fully-qualified Android activity name; a leading `.` is accepted. Same regex as `StartAppInput.activity`. StopAppChainStepParams: type: object required: - package properties: package: type: string minLength: 1 maxLength: 255 pattern: ^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$ description: | Same constraint as `StopAppInput.package`; validated against the same regex as the `start_app` step. WaitChainStepParams: type: object required: - duration_ms properties: duration_ms: type: integer minimum: 0 maximum: 60000 description: | Milliseconds to pause before the next step runs. Bounded to 60s per wait step; cumulative wait duration across all wait steps in one chain must be ≤ 120s. Chains have no implicit inter-step delay — insert `wait` steps where UI settling is needed (after taps that trigger animations, before taps that follow screen transitions). CaptureOptions: type: object additionalProperties: false properties: ui: type: boolean description: Capture UI element tree (default true when `capture` is set). screenshot: type: boolean description: | When true, the response includes `screenshot_url`, a link to the `GET /screenshot` endpoint. That endpoint takes a new screenshot each time it is fetched, so the image shows the screen at fetch time, not the moment after the action. verbosity: $ref: '#/components/schemas/CaptureVerbosity' only: $ref: '#/components/schemas/CaptureOnlyFilter' min_size_px: type: integer minimum: 0 description: Drop elements smaller than N pixels. include_keyboard: type: boolean description: Include the soft-input/keyboard subtree (default false). max_depth: type: integer minimum: 1 maximum: 50 description: Cap on the depth of the element tree. CaptureVerbosity: type: string enum: - compact - default - full description: | Presentation tier for `capture.elements`. `default` is the same element tree Lusor's own agent reads. `compact` drops indentation + non-interactive nodes for 60-70% fewer tokens. `full` includes every flag. CaptureOnlyFilter: type: string enum: - all - clickable - focused - editable description: | Subset filter applied before index assignment. responses: ValidationError: description: | Request validation failed. Either `validation_error` with per-field `details`, or `bad_request` with a `message`, depending on the endpoint. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ValidationErrorResponse' - $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Authentication required or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternetRouteInactive: description: | `internet_route_inactive`: this Lusor Phone's Internet connection is not active yet. Retry once it is. 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.