Skip to main content
Most of this site is written for somebody integrating against the API. This page is for the other reader: a person who signed in, wants a device, and wants to drive it without writing code first. The console is a browser face over the same control plane these docs describe. It calls the same routes with the same rules. Nothing it does is a private path, which is why every screen below can be named next to the route it calls.

Signing in

The console authenticates with an interactive session, not with an API key. The door is at console.phoneuse.com, and it takes an email address and a password, or Google. Signing up confirms the address with a six digit code and creates your organization on the way in, so there is no separate step for it. Your session is the credential for every console screen. An API key can do much of what a session does, but not everything: see Two kinds of credential.

The screens that exist

In the sidebar, Keys, MCP, Webhooks and Quickstart sit together under Developers. A device you bought appears in the console’s device list, and in GET /v1/devices, once the order settles. Open it to reach /devices/:id. Buy and drive a device walks the whole loop through these screens, with the API equivalent of each step beside it.

The Control block

/devices/:id carries a Control block, and it is the part worth explaining before you use it.
  • The screen is live. A cloud phone that declares stream: "webrtc" is shown as live video, through POST /v1/devices/{deviceId}/live-session. That route needs your org to hold the phone’s lease: without one it answers 409 lease_required and takes no lease itself. When the console gets that answer, it takes a lease for your org and asks again; if that take is refused, there is no live video. A device without stream: "webrtc" shows the current still frame. Nothing records a session as video. See What PhoneUse is not.
  • Tapping the screen acts under your org’s lease. A device holds one lease at a time, across every org, and that has not changed: it is what keeps two organisations off one phone, and what the meter runs on. Inside your org the lease is shared. If an agent’s run holds it, your taps go straight to the phone under that lease and the run keeps going; the agent is told what you did on its next result and is never stopped by it. If nobody holds it, your first tap takes a lease for you, for ten minutes, and keeps it alive while you keep driving. The gesture is the browser spelling of POST /v1/devices/{deviceId}/actions, and the response says which lease it ran under and whether it was somebody else’s (coDriving).
  • The picture is the target. Click the image where you want the device tapped. The console converts where you clicked into the normalized grid described below. You never type a pixel.
  • Who else is on the phone comes from one read, GET /v1/devices/{deviceId}/driving: the run on the device, whose lease it is, and who else acted in the last minute. The console shows it only while somebody else is on the phone.
  • Pause agent and Stop run are the only interruptions, and both are yours to choose: POST /v1/runs/{runId}/pause shuts the agent’s channels until you press Resume agent, and POST /v1/runs/{runId}/cancel ends the run. Acting on the screen interrupts nothing.
  • A lease you took yourself bills until it expires. Nothing watches for idleness. It expires ten minutes after your last gesture kept it alive, or you can give it back with DELETE /v1/devices/{deviceId}/lease.

A control that cannot work is disabled, and says why

Devices differ, and the console does not pretend otherwise. A control the device in front of you cannot perform is drawn disabled with its reason attached, for example Action not supported on this device. That is the same fact the API states as capabilities, and it is worth reading directly before you plan anything. Part of a cloud phone’s actions block:
It has no element tree (uiTree: false), so its screen is read from screenshots. That is the ordinary case, not a fault. Read your own device’s block rather than carrying this one forward. Capabilities explains every field.

Coordinates are normalized, everywhere

Both axes run 0 to 1000 whatever the real screen is, with the origin at the top left in the current orientation. The device states it as coordSpace: { "width": 1000, "height": 1000 }. This is why clicking a picture works. A click at one quarter across and three quarters down a rendered image committed on a real device today at x=247, y=749. Callers never speak device pixels, and neither does the console.

What has no screen

Two surfaces are live over HTTP and have no console face at all. Do not go looking for a screen; use the API.

Two kinds of credential

An API key is refused from a browser origin. Put one in front end JavaScript and the request comes back 403 with the code api_key_from_browser_origin, whatever the key’s scopes are. The refusal is explicit rather than vague, because the audience is a developer who has just shipped a key into a browser bundle and needs to know it. Keys are for servers. Browsers get a session. If you want a browser to drive a device, the console already does that with the session it holds. Buying is narrower still. A monthly phone needs an admin’s session, or an API key that holds orders:place, which only an admin can mint or approve. Either way a person still pays on the Checkout page. A member cannot buy, and per minute phones are started from an admin’s session only. See Authentication. Managing keys is the other way round. Either role does it, from a signed in session only, and the bound is ownership rather than seniority: a member mints keys and then rotates, renews and revokes the ones they minted, while an admin can act on any key in the org. None of the four asks you to reauthenticate: a signed in session is the whole of what minting a key requires.

Where to go next

Buy and drive a device

The whole loop, in the console and over the API, with real readings.

Authentication

The eight scopes, and how a key is narrowed to a subset of your devices.