> ## 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 an agent ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/agents 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/agents: post: tags: - Agents summary: Create an agent operationId: createAgent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgentInput' responses: '201': description: Agent created content: application/json: schema: $ref: '#/components/schemas/AgentDetailResponse' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' components: schemas: CreateAgentInput: allOf: - $ref: '#/components/schemas/WorkspaceScopeInput' - type: object required: - name properties: name: type: string minLength: 1 maxLength: 255 color: type: string minLength: 1 maxLength: 64 avatar: type: string pattern: ^(emojis|apps|other)/[a-z0-9-]{1,64}$ description: >- Avatar id. Omit on create for a random emoji; `null` is rejected. description: type: - string - 'null' maxLength: 4096 model: type: string minLength: 1 maxLength: 255 description: > Provider-qualified model id, for example `deepseek/deepseek-flash` (the default), `openai/gpt-6-luna` or `anthropic/claude-opus-5-5`. `auto` is accepted as an alias for the default model and is stored as `deepseek/deepseek-flash`. devices: type: array maxItems: 1 description: | An agent uses at most one device. The array wire shape is retained for client compatibility, but at most one entry is accepted — a second is rejected with a 400. items: $ref: '#/components/schemas/AgentDeviceInput' AgentDetailResponse: type: object required: - data properties: data: $ref: '#/components/schemas/AgentDetail' WorkspaceScopeInput: type: object properties: workspaceId: type: string format: uuid description: Optional for workspace-scoped API keys. AgentDeviceInput: type: object required: - device_id properties: device_id: type: string minLength: 1 maxLength: 512 label: type: - string - 'null' maxLength: 255 description: type: - string - 'null' maxLength: 4096 position: type: integer minimum: 0 maximum: 10000 AgentDetail: allOf: - $ref: '#/components/schemas/Agent' - type: object required: - devices - turns - turnsCursor - turnsHasMore properties: devices: type: array items: $ref: '#/components/schemas/AgentDevice' turns: description: Newest page of history, oldest-first. type: array items: $ref: '#/components/schemas/AgentTurn' turnsCursor: type: - string - 'null' description: >- Opaque cursor for the next OLDER page; null when history is exhausted. turnsHasMore: type: boolean ValidationErrorResponse: type: object required: - error - details properties: error: type: string example: validation_error details: type: object additionalProperties: true ErrorResponse: type: object required: - error - message properties: error: type: string message: type: string Agent: type: object required: - id - workspaceId - name - color - avatar - description - model - archivedAt - purgeAfter - createdAt - updatedAt - lastTurnAt - lastTurnSnippet properties: id: type: string format: uuid workspaceId: type: string format: uuid name: type: string color: type: string avatar: type: - string - 'null' description: Avatar id, `/` (for example `emojis/rocket`). description: type: - string - 'null' model: type: string description: >- The agent's provider-qualified model id, for example `deepseek/deepseek-flash`. archivedAt: type: - string - 'null' format: date-time purgeAfter: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time lastTurnAt: type: - string - 'null' format: date-time lastTurnSnippet: type: - string - 'null' activityAt: type: string format: date-time description: >- Roster sort key (newest session, else creation time). Roster reads only. AgentDevice: type: object required: - deviceId - label - description - position - createdAt properties: deviceId: type: string label: type: - string - 'null' description: type: - string - 'null' position: type: integer createdAt: type: string format: date-time AgentTurn: type: object required: - id - sessionId - prompt - status - deviceId - summary - recording - queued - createdAt - startedAt - completedAt properties: id: type: string description: Turn id. For older turns this is the session id. sessionId: type: string prompt: type: string status: type: string deviceId: type: - string - 'null' summary: type: - string - 'null' recording: type: boolean queued: type: boolean createdAt: type: string format: date-time startedAt: type: - string - 'null' format: date-time completedAt: type: - string - 'null' format: date-time 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' 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.