> ## 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. # Create a new session on this device > Starts an agent run on this phone without a persistent agent. Returns `202 Accepted { id, status: "queued" }` immediately; poll `GET /v1/sessions/{id}/status` or `GET /v1/sessions/{id}/events` for progress. Concurrent same-device session create returns `429 { error: 'device_busy', currentSessionId }`. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/workspaces/{workspaceId}/devices/{deviceId}/sessions 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}/sessions: post: tags: - Sessions summary: Create a new session on this device description: | Starts an agent run on this phone without a persistent agent. Returns `202 Accepted { id, status: "queued" }` immediately; poll `GET /v1/sessions/{id}/status` or `GET /v1/sessions/{id}/events` for progress. Concurrent same-device session create returns `429 { error: 'device_busy', currentSessionId }`. operationId: createDeviceSession parameters: - $ref: '#/components/parameters/WorkspaceIdPath' - $ref: '#/components/parameters/DeviceIdPath' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSessionInput' responses: '202': description: Session queued content: application/json: schema: $ref: '#/components/schemas/CreateSessionResult' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '404': $ref: '#/components/responses/NotFound' '409': description: | The session cannot start on this phone. `internet_route_inactive`: the Lusor Phone's Internet connection is not active yet; retry once it is. `device_releasing`: the phone is being removed from the Phone plan; start the session on another phone. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '412': description: | `unsupported_stealth_input`: `stealthInput` was requested for a phone whose agent does not advertise human-like input. No session was created. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: | `unknown_secret`: a name in `secrets` is not saved in this workspace. The response's `missing` lists them. No session was created. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Device busy with another session. content: application/json: schema: $ref: '#/components/schemas/Busy' 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). IdempotencyKey: name: Idempotency-Key in: header schema: type: string maxLength: 256 description: | Caller-provided key for safe retries. The same key in the same workspace yields the same run id, and a duplicate POST within the retention window returns the original run instead of starting a second one. schemas: CreateSessionInput: type: object required: - prompt properties: prompt: type: string minLength: 1 maxLength: 8192 maxDurationSecs: type: integer minimum: 1 description: >- Optional cap on the run's duration, in seconds. The server applies its own upper bound. recording: type: boolean default: false description: Record a video of the run. stealthInput: type: boolean description: | Run every device action of this session in human-like (stealth) mode: jittered tap timing, curved swipe paths and a per-key typing delay. Refused at create with `412 unsupported_stealth_input` when the phone's agent does not support it, so a run never starts only to fail on its first tap. schema: type: - object - 'null' additionalProperties: true app: type: - string - 'null' secrets: type: array maxItems: 50 items: type: string pattern: ^[a-z0-9_-]+\.[a-z0-9_-]+$ maxLength: 256 description: | Saved workspace secrets this run may use, by reference: `.`, for example `gmail.password`. Values are never sent in the request; the agent types them on the phone without the model ever seeing them. Every name must already be saved in the workspace (`GET /v1/workspaces/{workspaceId}/vault` lists them), otherwise the request fails with `422` `unknown_secret`. Omitted: the run may use every secret saved in the workspace. `[]`: none. model: type: - string - 'null' description: | Provider-qualified model id for this run. Omitted, `null` or `auto` runs the default model, `deepseek/deepseek-flash`. idempotencyKey: type: string maxLength: 256 description: | Key for retry safety. The `Idempotency-Key` header takes precedence over this body field. CreateSessionResult: type: object required: - id - status - deviceId - workspaceId properties: id: type: string status: type: string enum: - queued deviceId: type: string workspaceId: type: string format: uuid invocationId: type: string 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 ValidationErrorResponse: type: object required: - error - details properties: error: type: string example: validation_error details: type: object additionalProperties: true 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' PaymentRequired: description: | The action was refused for billing and was not sent to the phone. `credits_exhausted` (`resource: "phone_minutes"`): the workspace is out of credits for Lusor Phone minutes, or reached its plan's allowance with overages off. `billing_required`: this Lusor Phone is not covered by an active paid plan. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found. 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.