Skip to main content

​
Overview

Per-user; requires Authorization: Bearer nv_sk_…. Naïve owns the Mobilerun operator key — your agents never hold one. Each tenant is isolated by Naïve: every phone and task is recorded against (company, user), and all list/by-id operations (including the wildcard call for device/task-scoped paths) are scoped to the caller (404 cross-tenant). Billing: phones are billed per minute from your credits (~NAIVE_MOBILE_CREDITS_PER_MINUTE credits/min) — the only funding model. POST /v1/mobile/devices provisions the device immediately and the meter runs until DELETE /v1/mobile/devices/:id — there is no upstream auto-stop (credit exhaustion or max-runtime auto-terminates the device). Phones default to dedicated_premium_device (the minute-billed cloud phone). Routes are available both company-scoped (/v1/mobile/..., acting as the operator’s default user) and per-user (/v1/users/:user_id/mobile/...). Gated by the mobile primitive in the user’s AccountKit. Mobilerun usage is billed in credits.
POST /v1/mobile/devices (provision), the device lifecycle routes, POST /v1/mobile/tasks (run), POST /v1/mobile/tasks/:id/stop, POST /v1/mobile/apps (upload), and a mutating POST /v1/mobile/call are approval-gated by default. An agent (API-key) call may return 202 { "status": "pending_approval", "approval_id" }; a human approves it via Approvals and the action runs on replay.

​
Endpoints

MethodPathDescription
GET/v1/mobile/statusIntegration status (configured/reachable) + your device count
GET/v1/mobile/methodsWildcard — search the Mobilerun API catalog (?q=, ?tag=)
POST/v1/mobile/callWildcard — execute any operation ({ operation_id, path?, query?, body? }) — sensitive (non-GET)
GET/v1/mobile/devicesList this tenant’s devices (?state&type&country&page&page_size)
POST/v1/mobile/devicesCreate a phone ({ type?, country?, profile_id?, name? }) — provisions immediately, metered per minute from credits — sensitive
GET/v1/mobile/devices/:idGet a device’s live details
GET/v1/mobile/devices/:id/streamGet { stream_url, stream_token, stream_protocol, console_url } for live display
POST/v1/mobile/devices/:id/rebootReboot a device — sensitive
POST/v1/mobile/devices/:id/resetReset a device to a fresh state — sensitive
DELETE/v1/mobile/devices/:idTerminate (release) a device — stops the per-minute meter — sensitive
POST/v1/mobile/devices/:id/waitBlock until ready ({ timeout_seconds? })
GET/v1/mobile/devices/:id/proxyCurrent proxy attachment (datacenter IP by default)
POST/v1/mobile/devices/:id/proxyAttach a SOCKS5 proxy ({ host, port, user?, password?, smart_ip? }) — sensitive
DELETE/v1/mobile/devices/:id/proxyDetach the proxy — sensitive
GET/v1/mobile/tasksList agent tasks (?device_id&status)
POST/v1/mobile/tasksRun an agent task on one of your active phones ({ task, device_id (required), model?, vision?, reasoning?, steps? }) — sensitive
GET/v1/mobile/tasks/:idGet a task (status/result)
POST/v1/mobile/tasks/:id/stopCancel a running task — sensitive
GET/v1/mobile/tasks/:id/screenshotsList a task’s screenshot URLs
GET/v1/mobile/tasks/:id/trajectoryGet a task’s step-by-step trajectory
GET/v1/mobile/appsList apps (APKs) in the Mobilerun library
POST/v1/mobile/appsCreate a signed upload URL for an app ({ name, file_name? }) — sensitive

​
Wildcard search / call

GET /v1/mobile/methods returns Mobilerun’s API tags plus matching operations: 
{
  "tags": ["Devices", "Tasks", "Tools", "Proxies", "Apps", "..."],
  "methods": [
    { "operationId": "take-screenshot", "method": "GET", "path": "/devices/{deviceId}/screenshot", "tag": "Tools", "pathParams": ["deviceId"], "queryParams": [] }
  ]
}
POST /v1/mobile/call executes one by id, substituting path params and forwarding query/body: 
{ "operation_id": "take-screenshot", "path": { "deviceId": "…" } }
Read operations execute immediately; mutating ones are approval-gated. Any {deviceId} or {task_id} path is verified to belong to the calling tenant. Account-global operations (no device/task in the path — proxies, credentials, secrets, flows, and the unscoped device/task lists) are refused for tenant sub-users by default; the operator’s own default user can always call them, and MOBILERUN_ALLOW_GLOBAL_CALLS opens them for everyone. Use the curated devices/tasks/apps methods for scoped list/create flows. See the Mobile guide and the SDK sub-client.