# PhoneUse > This file is very large and may be truncated. For an index of this content, please refer to https://docs.phoneuse.com/llms.txt instead. > The mobile execution layer for AI agents. # Agent tier Source: https://docs.phoneuse.com/agent/overview Hand a goal to PhoneUse or to your own worker instead of driving each step yourself. There are two ways to use PhoneUse. **Drive it yourself.** Your agent calls tools, one gesture at a time, and decides everything. This is deterministic, auditable, and the right choice whenever you know the sequence. **Hand over a goal.** You describe what you want in a sentence, and an executor observes and acts on your leased device until it gets there or gives up. This is the agent tier. The low level tools stay available the whole time. The agent tier is an addition, not a replacement, and nothing about the surface you already use changes because you started a run. ## Get access A run needs a cloud phone in your organization. Buy one, or start one by the minute, from **Add a phone** in the console. Payment comes first, then the phone is set up for you, and you can start a run as soon as it is ready. For a larger fleet, [book a call with our team](https://cal.com/abdulla-ababakre-wubx6e/phoneuse?overlayCalendar=true) about the Enterprise plan. ## Who drives a run Every run has an `executor`, and there are two. | `executor` | Who drives the device | What `start_run` hands back | | - | - | - | | `phoneuse` | The control plane runs the run itself | No `vrxBaseUrl`. There is nothing to connect | | `self_hosted` | A worker you write and run | A `vrxBaseUrl`, once, for your worker | Pass `executor` on `start_run` to choose. Leave it out and the default follows your credential: **`self_hosted` for an API key, `phoneuse` for a signed-in person**. The response always says which one the run got, so read `executor` there before relying on it. > [!WARNING] > > A `self_hosted` run does nothing on its own. Nothing touches the device until > a program of yours picks up the `vrxBaseUrl`, and a run with no worker pointed > at it stays `queued` until its deadline passes. An API key that leaves > `executor` out gets exactly this kind of run. > > See [Bring your own worker](/agent/worker) for what a worker has to do and a > working loop to start from, or pass `"executor": "phoneuse"` to have the > control plane drive the run for you. ## How a run is put together Three parties on a `self_hosted` run, and it is worth knowing which one holds what. On a `phoneuse` run the control plane plays the worker's part itself, and no run scoped URL exists. | Party | Holds | Does | | - | - | - | | You | An org credential and a lease | Start the run, watch it, end it | | The control plane | The run record, the lease, the fencing token, the meter | Owns the state machine and every budget | | The worker, on a `self_hosted` run | A run scoped URL, and nothing else | Observes and acts on one device | A self-hosted worker is yours. It does not hold your credentials, cannot see your fleet, and never touches the real lease or the fencing token. All it has is one URL that reaches one device for one run, and expires. See [Bring your own worker](/agent/worker). ## Starting a run Acquire the device first. A run acts under **your** lease, so you have to hold one, and the control plane refuses to start a run against a lease you do not actually hold rather than issuing a credential for nothing. ```json theme={null} { "name": "start_run", "arguments": { "deviceId": "cloud-phone-01", "leaseId": "lease_9f2c...", "goal": "open settings and turn on airplane mode", "maxSteps": 20, "executor": "self_hosted" } } ``` ```json theme={null} { "runId": "task_c41e...", "agentRunId": "run_77a0...", "state": "queued", "executor": "self_hosted", "maxSteps": 20, "deadlineAt": "2026-09-03T06:10:00.000Z", "vrxBaseUrl": "https:///vrx/{runToken}/v1", "workerConnected": false } ``` `workerConnected` is always `false` in this response. On a `self_hosted` run, nothing happens on the device until your own worker connects to `vrxBaseUrl`, and no worker can have connected yet, because this response is the first place that url exists. On a `phoneuse` run the response carries no `vrxBaseUrl`, no worker ever connects, and progress shows as `stepSeq` on the run. `maxSteps` and `deadlineAt` are the budget the run actually got, not the one you asked for: an ask above the deployment's limit is capped to that limit, and the deadline is also bounded by the lease's own expiry. Read them here rather than assuming your ask was honoured. > [!WARNING] > > On a `self_hosted` run, `vrxBaseUrl` contains a credential and is returned **here only**. Nothing > else ever echoes it back, including the tool you use to watch the run. Hand > it to your worker and to nothing else: never a log, an issue, a support > thread, or a commit. Keep `runId`. That is the handle for everything afterwards, and it is safe to pass around. The same operation is available over HTTP for callers that are not speaking MCP, and both faces run the same operation underneath, so they cannot behave differently. See [Runs](/agent/runs) and the [API overview](/api/index). ## Budgets live on the control plane A run carries hard ceilings, and they are enforced where they can actually be enforced. * **Steps.** How many frames the run may consume. `maxSteps` on your request can only lower it; the deployment's own ceiling cannot be raised by a caller. Default: **50 steps per run**. * **Wall clock.** An absolute deadline, also capped by the deployment and by your lease's own expiry, whichever comes first. A lease expires **10 minutes** after it is granted, and `renew_lease` slides that expiry, so a run that keeps renewing is bounded by the **60 minute** lifetime no lease may exceed rather than by the first 10 minutes. Stop renewing and the run ends at the next expiry. * **Concurrency.** How many runs one org may have going at once. Default: **4 runs per org**. Those three defaults are what a deployment ships with, and a deployment can set its own. They are the numbers to plan against: if you need to know the values in force on the deployment you are pointed at, read them off a rejection, which names the limit it enforced. The reasoning is worth understanding, because it explains where the guard rails are. The expensive part of an autonomous run happens inside the worker, where the control plane has no visibility. But the control plane holds the device channel, so it is the only place that can actually stop one. When the control point and the cost point are in different places, the gate belongs where it can genuinely close. There is one refinement that saves real work. Running out of steps refuses the **next frame**; it does not kill the run. A worker that spends its last step finishing the job and then reports success is reporting success, not failing on a technicality. The terminal state comes from the worker's report or from the deadline. ## Metering is anchored to frames One metered step is one frame served to the worker. Not one action. A worker that looks once and then performs five taps has consumed one step. A worker that decides it is finished without acting has still consumed the step it used to decide. The step sequence is issued by the control plane, never accepted from the worker, because the party being metered must not hold the pen. And the count is written **before** the pixels are served: if the count cannot be recorded, the frame is not served. That ordering has a consequence worth stating in full, because it runs one way only. Delivered implies billed. Billed does not imply delivered: a client that drops the connection between the metering write and the response has been counted for a frame it never read, which costs at most one step per dropped connection. Everything that fails *before* the write costs nothing. See [Metering units](/billing/units#what-is-not-counted) for the complete list. This is honest about its own precision. A step is a lower bound on the number of model calls a worker made, not an equivalent: a worker may reason several times over one frame. See [Metering units](/billing/units). ## Watching and ending ```json theme={null} { "name": "get_run", "arguments": { "runId": "task_c41e...", "waitMs": 20000, "sinceState": "queued" } } ``` `get_run` is a bounded long poll. With no arguments beyond the id it answers immediately. With a wait and a state to compare against, it returns as soon as the state differs, and answers at the deadline regardless. It never hangs. `cancel_run` ends a run and destroys its credential. `resume_run` lifts a run parked for a person. Both are described in [Runs](/agent/runs). ## Scopes The run tools need `runs:start` **and** `devices:act`. Handing a device to a loop is a distinct grant from driving it yourself, and the run URL drives the device, so a credential that may not act may not start a run either. See [Authentication](/mcp/auth). ## What version 1 does not do Stated plainly, because finding out later is worse. * **There is no queue across multiple workers.** A run is claimed once. * **The built in executor is not configurable per run.** A `phoneuse` run is driven by the control plane with its own model and prompt. To choose your own, run `self_hosted` with a worker you write. See [Bring your own worker](/agent/worker). * **A run is not resumed across a restart.** Its record survives, so you can still read what it was trying to do and how it ended, but nothing picks the work back up on the other side. A run that PhoneUse was driving when the API restarted ends `canceled` by itself once the earlier of its saved time and 10 minutes has passed, sends `run.ended` and frees the phone, unless an action from before the restart has an unclear outcome: that action still holds the phone, and a new run can still be refused. A `self_hosted` run whose worker stopped answering ends at its deadline. * **A lease can be renewed, up to an hour.** It expires 10 minutes after it is granted, and `renew_lease` slides that expiry another 10 minutes without changing the lease id or the fencing token, so a goal that needs longer keeps the same claim by renewing before the expiry passes. A lease may not live more than **60 minutes** from when it was acquired; past that, acquire a new one. The 10-minute expiry is what makes a crashed client give the device back: stop renewing and the device frees itself as it always did. Runs are readable after they finish: `GET /v1/runs` lists yours, newest first, each entry carrying the goal it was started with and how it ended, so losing a run id no longer loses the run. Treat a run you cannot find the way you would treat a failed one. # Runs Source: https://docs.phoneuse.com/agent/runs The lifecycle of one autonomous run, and who is allowed to move it. A run is one autonomous attempt against one device. The control plane owns its state machine. A worker reports what happened; it does not decide what the run's state becomes. That single sentence is the design. Everything below follows from it. ## The lifecycle There are **seven** states, and two of them are stops rather than ends. ```text theme={null} queued ──> running ──┬──> succeeded ├──> failed ├──> canceled └──> needs_user_control ──resume──> running queued, running or needs_user_control ──pause──> paused ──resume──> running ``` | State | Meaning | | - | - | | `queued` | The run exists and has a credential, but no frame has been served yet | | `running` | The worker is observing and acting | | `needs_user_control` | Parked. The agent **asked** a person to do the next step on the same screen | | `paused` | On hold. A person **suspended** the agent; its channels are shut until Resume | | `succeeded` | The worker reported the goal reached | | `failed` | The run ended without reaching the goal | | `canceled` | You ended it deliberately, or the API restarted while PhoneUse was driving it (see below) | ### Goals that need a person A PhoneUse-driven run does not carry out goals that move money (pay, buy, order, subscribe, renew, send money), erase an account or everything on the phone, change a password or security setting, close an account, power off or restart the phone, sign out of or remove an account, or sideload an app ("Install unknown apps"). Such a run is created already in `needs_user_control` with the detail "This goal needs you at the phone. Open the phone and finish it yourself.", and the takeover bell rings. When a person signed in to the console presses Done, it ends as `succeeded` ("You finished this yourself"); it is never replayed. Resume from an API key (including the CLI), a third-party app or Copilot leaves it waiting for that Done. To stop it instead, cancel it (`cancel_run`, `POST /v1/runs/{runId}/cancel` or `phoneuse runs cancel `); it then ends `canceled`. While it runs, the agent also stops with `needs_user_control` when a screen asks for a payment, a verification code, an account or security setting, or a delete, erase or reset confirmation. One check does not depend on the model: the `power` key is withheld from every run, and a call to it is refused. Cloud phones publish no UI tree, so the agent cannot read the screen itself; beyond that key, only the instructions to the model apply. Self-hosted runs are unaffected. `needs_user_control` and `paused` are easy to confuse, and they are opposites. The first is the agent asking a person for help. The second is a person telling the agent to stop, on a run that asked for nothing. Neither is how a person acts on the device: see [Driving alongside a run](#driving-alongside-a-run). Only one of them freezes the run's deadline: see [Putting a run on hold](#putting-a-run-on-hold). A run leaves `queued` for `running` when the first frame is served to its worker, which is also its first metered step. A run whose deadline passes ends as `failed`, not as `canceled`: `canceled` means somebody chose to stop it. Starting is not the same as working, and the states say which is which. One `canceled` is not chosen by a person. A run PhoneUse was driving when the API restarted is not picked back up: it ends `canceled` by itself, with a plain `detail`, once the earlier of its saved time and 10 minutes has passed. It sends `run.ended` and frees the phone, so you can start a new run. The one exception: if an action from before the restart has an unclear outcome, that action still holds the phone after the run ends, and a new run can still be refused. The three terminal states are **immutable**. Nothing reopens a finished run, and calling `cancel_run` on one returns it unchanged rather than pretending to act. Terminal is terminal, which is the same discipline the receipt ledger follows. Reaching a terminal state destroys the run's credential and frees your org's concurrency slot, so another run can start. It does **not** release the device lease. That lease is still yours and still accruing [active time](/billing/units) until you release it or it expires. Release it yourself when the run is done. ## Why a run ended A run that did not simply succeed carries a `reason` from a closed set: | Reason | What happened | | - | - | | `worker_reported_failure` | The worker reported it could not reach the goal | | `deadline_exceeded` | The run's wall clock budget ran out | | `canceled_by_caller` | You cancelled it | | `lease_lost` | The device moved to another holder mid run | | `budget_exhausted` | The step budget was reached | Three of those deserve a note. `deadline_exceeded` is reached by two very different roads, and `detail` tells you which. Either no worker ever connected, which is not a timeout at all but a missing participant, or a worker connected and did not finish in time. The structured form of the same fact is `workerFirstContactAt`: `null` means nobody came. If it is `null`, start at [Bring your own worker](/agent/worker); if it is a timestamp, the reason your worker stopped is in your worker's own logs. A run parked as `needs_user_control` can also end this way. Its clock keeps running while it waits for a person and is capped by the lease, so the person has to finish and press Resume inside the run's remaining time. When that is what happened, `detail` says so and keeps the instruction the person was given. `lease_lost` is terminal on purpose. If the lease has gone, every subsequent action would fail the same way, so the run ends immediately rather than leaving a worker spinning against refusals until its deadline, holding one of your concurrency slots for nothing. `budget_exhausted` refuses the **next frame**, and does not by itself end the run. A worker that spends its last step finishing the job and then reports success has succeeded. The distinction matters: treating a finished run as a failure would feed it into retry paths and produce a second set of physical actions and a second charge for work that was already done. Deadlines are reclaimed lazily. A run past its deadline is moved to `failed` the next time anything looks at it, rather than by a background sweeper. That matters for a reason you can feel: an org's concurrency allowance counts only runs that are neither terminal nor expired, so a crashed worker does not permanently occupy a slot. ## Watching a run `get_run` is a **bounded long poll**, not a stream. ```json theme={null} { "name": "get_run", "arguments": { "runId": "task_c41e...", "waitMs": 20000, "sinceState": "running" } } ``` * With just a `runId`, it answers immediately with the current state. * With `waitMs` and `sinceState`, it returns as soon as the state differs from `sinceState`, and answers at the deadline regardless. It never hangs, and both faces give the same answer to an over-long wait: a `waitMs` above the maximum is **refused**, not silently shortened, by the `get_run` tool and by `GET /v1/runs/{runId}` alike. Loop on the call rather than trying to hold one open. The maximum is published in the [tool reference](/mcp/reference). What comes back is the run's public view: ```json theme={null} { "runId": "task_c41e...", "agentRunId": "run_77a0...", "deviceId": "cloud-phone-01", "state": "running", "stepSeq": 7, "maxSteps": 20, "deadlineAt": "2026-08-29T10:34:02.113Z", "createdAt": "2026-08-29T10:24:12.004Z", "updatedAt": "2026-08-29T10:26:41.882Z" } ``` `stepSeq` is how many metered steps have been issued so far, one per frame served. It is the live view of what this run is costing you. > [!NOTE] > > `get_run` never echoes the run URL. That credential is returned once, by > `start_run`, and nowhere else. If you lost it, cancel the run and start > another rather than looking for a way to read it back. A run has **two ids, and one run**. `runId` is the handle whoever started it kept; `agentRunId` is the id every receipt the run wrote carries and the one a permalink is built on. There is no retry mechanism here and no parent task: nothing groups several `agentRunId`s under one `runId`. Starting again is starting a new run, with both ids new. `runId` values begin `task_` for historical reasons; treat both ids as opaque. ## Ending a run `cancel_run` ends a run and destroys its credential. An already terminal run is returned unchanged. ```json theme={null} { "name": "cancel_run", "arguments": { "runId": "task_c41e..." } } ``` ## Driving alongside a run A person does not have to stop a run to act on its device. The lease a run holds is your organisation's, and inside the organisation it is shared: a signed-in person may send a gesture through `POST /v1/devices/{deviceId}/actions` without naming a lease, and it runs under the run's lease. The run keeps going. Three rules make that safe rather than chaotic: 1. **One device, one lane.** Gestures on a device run one at a time in the order they arrived, whoever sent them, so a swipe is never interleaved with a tap and a receipt is written for each one saying who took it. 2. **A person goes first.** A person's gesture waits for the action that is running to finish and then goes ahead of every action the run has waiting. Nothing the run already started is interrupted. 3. **The agent is told, and by default refused.** Every action result and every screenshot the run receives carries `others`: how many actions principals other than the run took on the device since the frame it last decided on, when the newest was, and whether they were a person or another agent. An action bound to `observedFrame` is refused `stale_frame` (reason `others_acted`) when that count is above zero, before anything physical happens and without consuming your idempotency key. A worker that already re-observes on a stale frame needs no new code; send `refuseIfOthersActed: false` to be informed instead of stopped. The person's own results carry the same `others` about the agent, plus `coDriving: true` to say the lease was somebody else's. Nothing about the lease itself changed: a device still holds one lease at a time across every organisation, the fencing token still fences a stale holder, and the meter still runs on the lease. `GET /v1/devices/{deviceId}/driving` answers who is driving in one read: the run on the device, whose lease it is, and who else acted in the last sixty seconds. ## Letting a parked run continue When the agent meets something only a person can do, a sign in or a challenge, its worker reports `needs_user_control`. The run parks rather than ending: it is asking a person to do the next step on the same screen. Parked means the agent is genuinely stopped. No new frames are served to the worker and no actions from it are accepted. Both gates are shut, not only the one that looks at the screen. The person does the step on the device, through the console or the action route, and then lets the run continue: ```json theme={null} { "name": "resume_run", "arguments": { "runId": "task_c41e..." } } ``` `resume_run` lifts **either** kind of stop, and only a person can lift either. A finished run stays finished, and a run in any other state comes back unchanged rather than being nudged sideways. Resuming is on the **human side only**. A worker cannot lift its own request, because a worker that could decide the person was finished would make the request meaningless. Secrets never travel through the run either; the person acts on the device. See [Progress and takeover](/mcp/progress-and-takeover). ## Putting a run on hold `needs_user_control` is the agent asking for a person. This is the reverse: a person telling the agent to stop, on a run that asked for nothing. You do not need it to act on the device; you need it when you want the agent's hands off the phone while you work. ```text theme={null} POST /v1/runs/{runId}/pause ``` or, over MCP: ```json theme={null} { "name": "pause_run", "arguments": { "runId": "task_c41e..." } } ``` It works from `queued`, `running` and `needs_user_control` alike, and it hands you three things: ```json theme={null} { "run": { "state": "paused", "...": "..." }, "leaseId": "...", "manualControlUntil": "2026-09-13T10:34:02.113Z" } ``` `leaseId` is the lease the run acts under, kept in this response for compatibility. You do not need it to act: a signed-in person's gestures resolve the lease themselves. It is still a **capability, not a detail**, which is why `GET /v1/leases` deliberately never publishes it. Four things follow from putting a run on hold: 1. **The agent's channels shut.** No frames are served to its worker and no actions from it are accepted until you resume. 2. **The run's deadline freezes.** `deadlineAt` stops advancing while the run is `paused`, and resuming slides it forward by however long the hold lasted. Time the agent spends on hold is not charged to the run. 3. **The worker's steps are untouched.** Resuming carries on from the current screen, whatever you did on it meanwhile, rather than redoing what is already done. 4. **`GET /v1/runs/{runId}` reports `pausedAt`**, so a client can tell a run on hold from a run that is merely between steps. Calling pause again on a run already on hold is safe: nothing is re-stamped. There are two ways the hold ends badly, and they differ: | What happened | What happens to the run | | - | - | | The run's lease was **released** while it was on hold | Ends `failed`, reason `lease_lost` | | Nobody resumed it before `manualControlUntil` passed | Ends `canceled`, with the explanation in `detail` | No new failure reason is used for either case. To keep the hold longer, renew the lease. To let the agent continue, resume the run. ### Doing it from the console The console's `/devices/:id` Control block is where all of this lives. The screen is always interactive: a tap goes to the phone under whatever lease your organisation holds, and the run, if there is one, keeps going. **Pause agent** and **Stop run** are the two interruptions, and both are yours to choose. ## The same lifecycle over HTTP If you are not speaking MCP, the same operations are HTTP routes on the control surface, authenticated with the same bearer credential: | Method and path | Equivalent tool | | - | - | | `POST /v1/runs` | `start_run` | | `GET /v1/runs` | `list_runs` | | `GET /v1/runs/{runId}` | `get_run` | | `POST /v1/runs/{runId}/pause` | `pause_run` | | `POST /v1/runs/{runId}/resume` | `resume_run` | | `POST /v1/runs/{runId}/cancel` | `cancel_run` | `GET /v1/runs/{runId}` accepts the same bounded wait as a query parameter. ### Two ids, one route `GET /v1/runs/{runId}` takes **either** id. Send the `runId` the start response returned, or the `agentRunId` a receipt carries and a permalink is built on: an id beginning `run_` is read as an `agentRunId`, anything else as a `runId`. So a run id somebody shared with you can be read directly instead of by paging the listing until it appears, and both spellings answer with the same run view and the same bounded wait. The four write routes take a `runId` only. An `agentRunId` there is `404`, the same `404` an unknown id gets. That read returns the run **head only**. The action trail is a separate, paged resource at `GET /v1/receipts?agentRunId=...`, and it is not folded in: it has its own cursor and its own retention, and embedding it would mean either truncating it at an unchosen number or running a second pagination contract inside a single resource response. The frames a run saw are archived too: read one with `GET /v1/frames/{frameId}`, using the run's `lastFrame.frameId` or a receipt's `observedFrame`. See [Frame retention](/security/frame-retention). Every one of these routes applies the calling key's device narrowing. A run on a device your key cannot address is `404`, the same `404` an unknown id gets. Both faces run the same operation underneath, so there is no second path to diverge. They also share the scope rule: `runs:start` **and** `devices:act`, enforced identically, so a credential that cannot start a run over MCP cannot start one over HTTP either. A run belonging to another org reports as not found (`run_not_found`). There is no way to learn that a run id exists but is not yours. ## What the worker sees Almost nothing, and that is the point. See [The contract in full](/agent/worker#the-contract-in-full) for the surface a worker actually talks to, and what it is structurally prevented from reaching. # Bring your own worker Source: https://docs.phoneuse.com/agent/worker On a self-hosted run you supply the worker. Here is what it has to do and how to get one running. **On a `self_hosted` run, you provide the worker.** This page is about those runs. To have PhoneUse drive the run instead, pass `"executor": "phoneuse"` on `start_run`; see [Who drives a run](/agent/overview#who-drives-a-run). On a `self_hosted` run, `start_run` creates the run, holds its state machine, meters it, and hands you a `vrxBaseUrl`. Nothing then drives the device until a program of yours picks that url up and starts asking for frames. If you never point a worker at it, the run sits in `queued` until its deadline passes and it ends as `failed`. This page exists because that is easy to miss. Read it before you write your first `start_run` call. ## Who does what | Party | Supplied by | Responsibility | | - | - | - | | The control plane | PhoneUse | Run state, lease, fencing token, budgets, metering | | The device | PhoneUse | The cloud phone your lease points at | | The worker | **You** | Deciding what to do next, and doing it through VRX | The split is deliberate. The control plane is hands and eyes. The judgment about what to tap next is yours, which is what lets you choose your own model, your own prompt, and your own stopping rule, and change any of them without waiting for us. ## If you do not want to write one You do not have to use the agent tier at all. The low level tools drive a device directly and need no worker: 1. `acquire_device` to take a lease. 2. `screenshot` to see the screen. 3. `tap`, `swipe`, `type_text` to act. 4. `release_device` when you are done. Every action returns a receipt. This is the shorter path to a first working action, and it is the right one whenever you already know the sequence of steps. See [Your first session](/getting-started/first-session). Use the agent tier when you want a goal executed by a loop instead of a script. ## What a worker has to do A worker repeats four steps until it is finished: 1. Ask for a frame. 2. Decide what to do, usually by sending the frame to a vision capable model. 3. Send one action. 4. Report the outcome when it is done or stuck. That is the whole job. A worker holds exactly one credential, the `vrxBaseUrl`, and it needs nothing else: no API key, no lease id, no headers. If your worker wants any of those, it has drifted outside the contract. ## The contract in full Everything a worker may call, rooted at the `vrxBaseUrl` you were handed: | Method | Path | Purpose | | - | - | - | | `GET` | `/devices` | Your run's device. Read `devices[0].id` | | `GET` | `/devices/{deviceId}/screenshot` | Raw `image/png` or `image/jpeg` bytes | | `POST` | `/devices/{deviceId}/actions` | One action | | `POST` | `/report` | The run's outcome | Because `GET /devices` tells your worker which device it is bound to, the `vrxBaseUrl` really is the only input it needs. Action payloads, exactly as the channel accepts them: ```json theme={null} { "action": "tap", "x": 540, "y": 1200, "coordinate_space": "screenshot_pixels", "screen": { "width": 1080, "height": 2400 } } { "action": "swipe", "x1": 540, "y1": 1800, "x2": 540, "y2": 600, "duration_ms": 300, "coordinate_space": "screenshot_pixels", "screen": { "width": 1080, "height": 2400 } } { "action": "type_text", "text": "hello" } { "action": "press_button", "button": "home" } { "action": "open_app", "package": "com.example.app" } ``` Five rules that catch people out: * **`screen` must match the frame you just received.** It is checked against the current frame, not trusted. Measure the image bytes you were served rather than assuming a device resolution, and re-measure after every frame. A mismatch is refused with a `400` telling you to re-observe. * **Coordinates are integers in that frame's own pixels**, and `coordinate_space` must be the string `screenshot_pixels`. Taps and swipes need both fields. `type_text`, `press_button` and `open_app` do not. * **Take a frame before your first action.** Acting without ever having observed is refused. There is no coordinate basis yet, so there is nothing to bind the action to. * **`type_text` takes at most 4096 characters**, the same ceiling the MCP `type_text` tool publishes. Longer text is refused with a `400`, not cut. * **`duration_ms` on a swipe is a positive integer.** Zero, a fraction or a string is refused rather than read as the default. A value above the contract's ceiling is performed at the ceiling, because the upstream driver sends very large values for a drag. `press_button` accepts `home`, `back`, `enter`, `delete`, `app_switch`, `power`, `volume_up` and `volume_down`. Not every device does all of them: the `capabilities.press_button` field on `GET /devices` tells you which ones this device advertises, and one it does not support is refused with a `409`. Report exactly one of three states when you stop: ```json theme={null} { "state": "succeeded", "detail": "airplane mode is on" } { "state": "failed", "detail": "could not find the settings icon" } { "state": "needs_user_control", "detail": "enter the code sent by SMS" } ``` ## The loop, in about thirty lines This is the shape, not a product. Fill in `decide` with a call to the vision capable model of your choice, and read [Device surface codes](/mcp/errors#device-surface-codes) for the refusals you have to handle. ```js theme={null} const base = process.env.VRX_BASE_URL; // from start_run, and a credential const { devices } = await (await fetch(`${base}/devices`)).json(); const id = devices[0].id; for (let step = 0; step < 20; step++) { const res = await fetch(`${base}/devices/${id}/screenshot`); if (res.status === 409) break; // no more frames, stop and report if (!res.ok) continue; // 503 is retryable const frame = new Uint8Array(await res.arrayBuffer()); const { width, height } = measure(frame); // read it from the bytes const next = await decide(frame, goal); // your model call if (next.done) break; await fetch(`${base}/devices/${id}/actions`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ...next.action, coordinate_space: "screenshot_pixels", screen: { width, height } }), }); } await fetch(`${base}/report`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ state: "succeeded", detail: "done" }), }); ``` > [!WARNING] > > The `vrxBaseUrl` carries a credential in its path. Pass it to your worker as an > environment variable or a secret. Never put it in a log line, a commit, an > issue, or a support thread. ## Choosing a model Any model that reads an image and returns a coordinate will work. The quality of a run is mostly the quality of this decision, so start with the strongest vision capable model you have access to and reduce only if you measure that a smaller one holds up. Your worker pays for its own model calls. PhoneUse meters frames, not tokens. One frame is one step no matter how many times you reason over it, so a worker that thinks twice about the same frame costs you model tokens and costs nothing extra here. See [Metering units](/billing/units). ## How to tell your worker never connected The run tells you. `GET /v1/runs/{runId}` and `get_run` both return `workerFirstContactAt`: * `null` means no worker has reached this run. A `queued` run with `null` here is waiting for you, not for us. * A timestamp means a worker arrived, and `stepSeq` tells you how many frames it has taken since. If the run ends as `failed` with reason `deadline_exceeded`, `detail` says which of the two happened: nobody connected, or a worker connected and did not finish. See [Runs](/agent/runs#why-a-run-ended). # Approve a CLI sign-in Source: https://docs.phoneuse.com/api/endpoints/api-keys/approve-a-cli-sign-in /api/openapi.json post /v1/cli-sessions/{userCode}/approve Approving a sign-in mints an API key for it, so it asks exactly what `POST /v1/api-keys` asks: a signed-in person of either role, and no scope your own session does not hold. No recent identity check. The key acts for the organisation you have active, is created by you, and appears on the Keys page like any other. Without `scopes` the key gets the CLI default (devices:read, devices:act, devices:lease, runs:start, orders:place) narrowed to what your session holds. Without `ttlMs` it lasts 180 days from when the CLI collects it. The key is minted on the CLI's next poll, not by this call, and that collection does not re-check your membership. An approval near the code's deadline extends it to at least 60 seconds out so the CLI can still collect. Omitting `scopes` when your session holds none of the defaults is refused 403. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Deny a CLI sign-in Source: https://docs.phoneuse.com/api/endpoints/api-keys/deny-a-cli-sign-in /api/openapi.json post /v1/cli-sessions/{userCode}/deny Ends a waiting sign-in so its code can never be approved; the CLI's next poll says `denied`. Use it on a code you did not start. Any signed-in person may deny; an API key is refused. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Describe the calling key Source: https://docs.phoneuse.com/api/endpoints/api-keys/describe-the-calling-key /api/openapi.json get /v1/api-keys/current The API key making this request, about itself: its id, name, organisation, scopes and expiry. This is what `phoneuse whoami` shows. Only an API key may call it; a signed-in person has no current key and is refused 403. It never returns the secret. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # List the org's keys Source: https://docs.phoneuse.com/api/endpoints/api-keys/list-the-orgs-keys /api/openapi.json get /v1/api-keys Your org's keys, newest first, one page at a time. Secrets are not stored in recoverable form and are never in this response. `lastUsedAt` is written off the request path, so it can lag slightly behind the last real use, which is worth knowing before you read a quiet key as unused. PAGING. A full page carries `nextBefore`; send it back as `before` to get the next (older) page, and keep going until it is absent. Its absence is how paging ends, and it is the only reliable signal: a page that happens to be exactly full is not the end. This listing previously answered a bare array truncated at 200 rows with no cursor and no flag, so an org at the ceiling and an org far past it were indistinguishable. WHO MAY READ IT. Any signed-in principal in the org, of either role. An ADMIN receives the full summary. A MEMBER receives the same keys, in the same order, with the same cursor, but a narrower projection: what a key IS (its ids, name, scopes, device narrowing, validity window and who created it) is returned, and how it has been USED is not, so `lastUsedAt` and `rotatedFrom` are withheld. A member can therefore see that their org has keys, match one they hold by its `keyId` to read why it does not work, and tell which rows are theirs to manage, without being handed the fields that rank an org's credentials by how useful one would be to take away. `createdBy` is an id and not a name; resolve it through your own directory. It is in the member projection because a member may manage the keys they created and would otherwise have no way to tell which those are. An API key cannot read this listing at all, whatever the role of whoever minted it. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Look at a CLI sign-in before approving it Source: https://docs.phoneuse.com/api/endpoints/api-keys/look-at-a-cli-sign-in-before-approving-it /api/openapi.json get /v1/cli-sessions/{userCode} What the approval page shows: the name and version the CLI reported (unverified, so compare them with the terminal in front of you), when it started and whether it is still waiting. Any signed-in person may read it; an API key is refused. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Mint an API key Source: https://docs.phoneuse.com/api/endpoints/api-keys/mint-an-api-key /api/openapi.json post /v1/api-keys Creates a headless credential for your org. ANY signed-in member of the org can mint one, whatever their role: this is the product's only headless credential, and the first step of getting started asks for it. An API key cannot mint another key, so a leaked key cannot widen its own reach. That is a rule about the CREDENTIAL and not about the person holding it, and no role change reaches it. A KEY NEVER CARRIES MORE SCOPE THAN YOUR OWN SESSION. Asking for one you do not hold is refused 403, not 400: the request is well formed and you are not allowed to make it. Every signed-in member holds the four device and run scopes; only an admin also holds `orders:place`, so a member asking for it is refused. The key records who created it, and that is what decides who may rotate, narrow or revoke it later: you can manage the keys you created, and an admin can manage any of them. `deviceIds` narrows the key to a subset of your org's devices, and every id must already belong to your org. Narrowing applies to visibility as well as addressing, so a device outside the subset is simply not there as far as that key is concerned. Without `ttlMs` the key lasts 90 days (7776000000 ms). Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Poll a CLI sign-in, and collect its key Source: https://docs.phoneuse.com/api/endpoints/api-keys/poll-a-cli-sign-in-and-collect-its-key /api/openapi.json post /v1/cli-sessions/token Poll every `intervalMs` with the poll token from `POST /v1/cli-sessions`. While nobody has answered, the status is `pending`. Once a person approves, the NEXT poll mints the key and returns it with `status: approved`, and every poll after that answers `consumed`. The key is delivered exactly once: if that response is lost, the key still exists (revoke it on the Keys page) and you have to sign in again. `denied` and `expired` are final too. Stop polling on any status but `pending`. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Rename, renew or narrow a key Source: https://docs.phoneuse.com/api/endpoints/api-keys/rename-renew-or-narrow-a-key /api/openapi.json patch /v1/api-keys/{id} Updates an active key in place. Reach can only SHRINK: `scopes` must be a subset of what the key already holds, and `deviceIds` must stay inside the key's current set (a key on the whole org can be narrowed to any devices the org owns, but there is no way back from a set to the whole org). Widening is refused, so an update can never bypass what was granted at creation; mint a new key instead. `ttlMs` renews the key: the lifetime restarts from now, at most 3650 days per renewal (lifetime is time, not reach; a live key can be renewed repeatedly). A key that has already expired cannot be renewed; rotate it or create a new one. A revoked key answers 404 exactly like a missing one and cannot be edited back to life. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Revoke a key Source: https://docs.phoneuse.com/api/endpoints/api-keys/revoke-a-key /api/openapi.json delete /v1/api-keys/{id} Revocation takes effect on the very next request: the endpoint keeps no session and holds no long lived connection, so there is nothing in flight to outlive it. THIS STEP NEEDS AN ADMINISTRATOR SIGNED IN TO THE CONSOLE. An API key is refused outright, whatever its scopes and whoever minted it, and the 403 says which action it was refused: revoking a credential is not something a program should be able to do while nobody is watching. There is no scope that grants it. A key that needs to revoke ITSELF, because the program holding it knows it leaked or is signing out, uses `DELETE /v1/api-keys/current` instead, which can reach no key but the caller. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Revoke the calling key Source: https://docs.phoneuse.com/api/endpoints/api-keys/revoke-the-calling-key /api/openapi.json delete /v1/api-keys/current The API key making this request revokes ITSELF, effective on the very next request. This is what `phoneuse logout` calls. It can reach no other key, so it is not key management, and like every revocation it asks for no fresh sign-in. A signed-in person is refused 403 and revokes keys by id instead. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Rotate a key Source: https://docs.phoneuse.com/api/endpoints/api-keys/rotate-a-key /api/openapi.json post /v1/api-keys/{id}/rotate Mints a successor key with the same name, scopes and device subset (fresh lifetime, fresh secret) and shortens the old key's expiry to the grace deadline, atomically. The successor's token appears ONCE, in this response, exactly like creation. Grace: the old key keeps working for `graceMs` (default 86400000 ms = 24 hours, 0 = immediately dead, at most 72 hours), then answers 401 as expired. Grace never EXTENDS a key: one that would expire sooner keeps its earlier deadline, and rotating an already-expired key leaves it expired (rotation is the documented way back from an expired key). Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Start a CLI sign-in Source: https://docs.phoneuse.com/api/endpoints/api-keys/start-a-cli-sign-in /api/openapi.json post /v1/cli-sessions What `phoneuse login` calls first. Takes no credential. Returns a short code to show the person, the console page to approve it on, and a poll token. A signed-in person opens the page (any device will do), checks the code and approves; the CLI then collects an ordinary API key with `POST /v1/cli-sessions/token`. The code works for 10 minutes and once. Starting a sign-in grants nothing on its own. This address is limited to a few sign-ins a minute. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Add an app to a phone's install queue Source: https://docs.phoneuse.com/api/endpoints/apps/add-an-app-to-a-phones-install-queue /api/openapi.json post /v1/app-store/queue The per-phone install queue. A phone installs one app at a time; more apps wait in line in the order they were added, at most 10 per phone (the installing one included) and 50 waiting or unfinished per workspace. A waiting app sends nothing to the phone and holds no lease. When the installing app is finished and the phone is free, the oldest waiting app starts by itself as an ordinary installation with the same id and request key, re-checked against current permission, phone, profile and catalogue build before anything is sent; its own time limits start then. An installation whose result is not confirmed pauses the line until it is checked: the next app never replaces or repeats it. Requires apps:read, devices:read, devices:act, devices:lease. Joining needs an online cloud Android phone with a confirmed primary profile that can install apps; it may be busy installing another app. The same app already waiting or installing on the phone is refused with 409 request_in_progress and field appId. A full phone line is refused with 429 quota_exceeded and field deviceId; the workspace limit with 429 quota_exceeded and no field. A request key already used for a direct install is refused with 409 idempotency_conflict: request keys are one namespace across the queue and direct installs. Replaying the same request key returns the original entry; after a lost response, recover it by that key. # Check an app installation Source: https://docs.phoneuse.com/api/endpoints/apps/check-an-app-installation /api/openapi.json get /v1/app-store/installations/{installationId} Managed Android app store. Requires apps:read, devices:read. Catalogue sources stay on the server. Accepted installs persist before the worker uses native action governance, leases and receipts. After uncertain dispatch only original-receipt and fresh inventory reads run; no automatic reinstall. Installed requires verified exact phone, primary profile, package and catalogue version. All history is tenant/device scoped; activeItems repeats every held installation on each bounded page. An uncertain confirmation result re-checks after 10 s, 30 s, 2 min, 10 min and 30 min; the next uncertain result, or 60 inventory refreshes without proof, stops automatic checks with status unconfirmed and reasonCode needs_review: the phone stays held and PhoneUse staff are alerted once. # Check an app installation again Source: https://docs.phoneuse.com/api/endpoints/apps/check-an-app-installation-again /api/openapi.json post /v1/app-store/installations/{installationId}/recheck Managed Android app store. Requires apps:read, devices:read, devices:act, devices:lease. Catalogue sources stay on the server. Accepted installs persist before the worker uses native action governance, leases and receipts. After uncertain dispatch only original-receipt and fresh inventory reads run; no automatic reinstall. Installed requires verified exact phone, primary profile, package and catalogue version. All history is tenant/device scoped; activeItems repeats every held installation on each bounded page. An uncertain confirmation result re-checks after 10 s, 30 s, 2 min, 10 min and 30 min; the next uncertain result, or 60 inventory refreshes without proof, stops automatic checks with status unconfirmed and reasonCode needs_review: the phone stays held and PhoneUse staff are alerted once. Check again asks for one more bounded confirmation pass for the original verifying or unconfirmed installation, at most once per 5 minutes per installation (429 with Retry-After otherwise; 409 for any other status). The pass re-queries the original supplier task and takes one new inventory sample; it never sends a new installation. # Discover visible devices and authoritative application scopes Source: https://docs.phoneuse.com/api/endpoints/apps/discover-visible-devices-and-authoritative-application-scopes /api/openapi.json get /v1/app-library/device-capabilities Read-only adapter capability projection. No inventory collection, wake, boot, lease acquisition/renewal or device action. Return independent supported/unsupported/unknown for inventoryRead/install/update/uninstall and authoritative scope or null; updatedAt is capability knowledge time only. Invisible devices omitted; explicit invisible deviceId ->404. Clients use non-null authoritative scope to request an inventory refresh; null remains unselectable. # Install an app Source: https://docs.phoneuse.com/api/endpoints/apps/install-an-app /api/openapi.json post /v1/app-store/installations Managed Android app store. Requires apps:read, devices:read, devices:act, devices:lease. Catalogue sources stay on the server. Accepted installs persist before the worker uses native action governance, leases and receipts. After uncertain dispatch only original-receipt and fresh inventory reads run; no automatic reinstall. Installed requires verified exact phone, primary profile, package and catalogue version. All history is tenant/device scoped; activeItems repeats every held installation on each bounded page. An uncertain confirmation result re-checks after 10 s, 30 s, 2 min, 10 min and 30 min; the next uncertain result, or 60 inventory refreshes without proof, stops automatic checks with status unconfirmed and reasonCode needs_review: the phone stays held and PhoneUse staff are alerted once. A phone installs one app at a time: a direct install is refused with 409 request_in_progress (no field) while the phone has an unfinished installation or any app waiting in its install queue. To wait in line instead, use POST /v1/app-store/queue. Request keys are one namespace across direct installs and the queue: a key that started from the queue replays its installation here; a key still waiting in, or removed from, a queue is refused with 409 idempotency_conflict (query it with GET /v1/app-store/queue/by-request/{requestKey}). While the phone is held by another operation at that moment (for example it is being released), the request is refused with 429 rate_limited, field deviceId and a Retry-After of about 5 seconds; nothing is created, so retry with the same request key. # List installable apps Source: https://docs.phoneuse.com/api/endpoints/apps/list-installable-apps /api/openapi.json get /v1/app-store/catalog Managed Android app store. Requires apps:read, devices:read. Catalogue sources stay on the server. Accepted installs persist before the worker uses native action governance, leases and receipts. After uncertain dispatch only original-receipt and fresh inventory reads run; no automatic reinstall. Installed requires verified exact phone, primary profile, package and catalogue version. All history is tenant/device scoped; activeItems repeats every held installation on each bounded page. An uncertain confirmation result re-checks after 10 s, 30 s, 2 min, 10 min and 30 min; the next uncertain result, or 60 inventory refreshes without proof, stops automatic checks with status unconfirmed and reasonCode needs_review: the phone stays held and PhoneUse staff are alerted once. With no query parameters the legacy bounded response is unchanged. Supplying a query opts into paginated search with nextCursor and categories. Follow nextCursor with the same search/category until null; installationAvailable describes the store, including when the search has no matches. # Pause or resume a phone's install queue Source: https://docs.phoneuse.com/api/endpoints/apps/pause-or-resume-a-phones-install-queue /api/openapi.json post /v1/app-store/queue/pause The per-phone install queue. A phone installs one app at a time; more apps wait in line in the order they were added, at most 10 per phone (the installing one included) and 50 waiting or unfinished per workspace. A waiting app sends nothing to the phone and holds no lease. When the installing app is finished and the phone is free, the oldest waiting app starts by itself as an ordinary installation with the same id and request key, re-checked against current permission, phone, profile and catalogue build before anything is sent; its own time limits start then. An installation whose result is not confirmed pauses the line until it is checked: the next app never replaces or repeats it. Requires apps:read, devices:read, devices:act, devices:lease. A paused line starts nothing until it is resumed; the app already installing carries on. Anyone who may install on the phone may pause or resume it. # Read a phone's install queue Source: https://docs.phoneuse.com/api/endpoints/apps/read-a-phones-install-queue /api/openapi.json get /v1/app-store/queue The per-phone install queue. A phone installs one app at a time; more apps wait in line in the order they were added, at most 10 per phone (the installing one included) and 50 waiting or unfinished per workspace. A waiting app sends nothing to the phone and holds no lease. When the installing app is finished and the phone is free, the oldest waiting app starts by itself as an ordinary installation with the same id and request key, re-checked against current permission, phone, profile and catalogue build before anything is sent; its own time limits start then. An installation whose result is not confirmed pauses the line until it is checked: the next app never replaces or repeats it. Requires apps:read, devices:read. Says whether an app added now would start at once, whether another may join, and why not. # Read application-check progress Source: https://docs.phoneuse.com/api/endpoints/apps/read-application-check-progress /api/openapi.json get /v1/app-library/inventory/refreshes/{refreshId} # Read installation history Source: https://docs.phoneuse.com/api/endpoints/apps/read-installation-history /api/openapi.json get /v1/app-store/installations Managed Android app store. Requires apps:read, devices:read. Catalogue sources stay on the server. Accepted installs persist before the worker uses native action governance, leases and receipts. After uncertain dispatch only original-receipt and fresh inventory reads run; no automatic reinstall. Installed requires verified exact phone, primary profile, package and catalogue version. All history is tenant/device scoped; activeItems repeats every held installation on each bounded page. An uncertain confirmation result re-checks after 10 s, 30 s, 2 min, 10 min and 30 min; the next uncertain result, or 60 inventory refreshes without proof, stops automatic checks with status unconfirmed and reasonCode needs_review: the phone stays held and PhoneUse staff are alerted once. # Read last confirmed phone apps Source: https://docs.phoneuse.com/api/endpoints/apps/read-last-confirmed-phone-apps /api/openapi.json get /v1/app-library/inventory Read cached authoritative facts only, no device calls/lease effects. Missing target rows are unknown, not absent. Listings filter to currently visible devices. Last refresh errors never erase last confirmed facts. # Read per-device check outcomes Source: https://docs.phoneuse.com/api/endpoints/apps/read-per-device-check-outcomes /api/openapi.json get /v1/app-library/inventory/refreshes/{refreshId}/results # Recover a lost mutation response by original key Source: https://docs.phoneuse.com/api/endpoints/apps/recover-a-lost-mutation-response-by-original-key /api/openapi.json get /v1/app-library/requests/{requestKey} Original org/principal and original operation scopes revalidated (not just apps:read). Never returns another actor request even within org. Found request points to original stable resource. 404 is not proof that an action never happened: key may be absent, hidden or expired. Never create a replacement intent on uncertainty. # Recover a queued app by its request key Source: https://docs.phoneuse.com/api/endpoints/apps/recover-a-queued-app-by-its-request-key /api/openapi.json get /v1/app-store/queue/by-request/{requestKey} The per-phone install queue. A phone installs one app at a time; more apps wait in line in the order they were added, at most 10 per phone (the installing one included) and 50 waiting or unfinished per workspace. A waiting app sends nothing to the phone and holds no lease. When the installing app is finished and the phone is free, the oldest waiting app starts by itself as an ordinary installation with the same id and request key, re-checked against current permission, phone, profile and catalogue build before anything is sent; its own time limits start then. An installation whose result is not confirmed pauses the line until it is checked: the next app never replaces or repeats it. Requires apps:read, devices:read. Only the account that sent the request can recover it. A direct install made with the key reads as started. # Recover an app installation Source: https://docs.phoneuse.com/api/endpoints/apps/recover-an-app-installation /api/openapi.json get /v1/app-store/installations/by-request/{requestKey} Managed Android app store. Requires apps:read, devices:read. Catalogue sources stay on the server. Accepted installs persist before the worker uses native action governance, leases and receipts. After uncertain dispatch only original-receipt and fresh inventory reads run; no automatic reinstall. Installed requires verified exact phone, primary profile, package and catalogue version. All history is tenant/device scoped; activeItems repeats every held installation on each bounded page. An uncertain confirmation result re-checks after 10 s, 30 s, 2 min, 10 min and 30 min; the next uncertain result, or 60 inventory refreshes without proof, stops automatic checks with status unconfirmed and reasonCode needs_review: the phone stays held and PhoneUse staff are alerted once. # Remove a waiting app from a phone's queue Source: https://docs.phoneuse.com/api/endpoints/apps/remove-a-waiting-app-from-a-phones-queue /api/openapi.json post /v1/app-store/queue/{entryId}/remove The per-phone install queue. A phone installs one app at a time; more apps wait in line in the order they were added, at most 10 per phone (the installing one included) and 50 waiting or unfinished per workspace. A waiting app sends nothing to the phone and holds no lease. When the installing app is finished and the phone is free, the oldest waiting app starts by itself as an ordinary installation with the same id and request key, re-checked against current permission, phone, profile and catalogue build before anything is sent; its own time limits start then. An installation whose result is not confirmed pauses the line until it is checked: the next app never replaces or repeats it. Requires apps:read, devices:read, devices:act, devices:lease. Only a waiting app can be removed; nothing was sent for it. Removing it again returns it unchanged. An app that already started is refused with 409 precondition_failed. # Request bounded read-only application checks Source: https://docs.phoneuse.com/api/endpoints/apps/request-bounded-read-only-application-checks /api/openapi.json post /v1/app-library/inventory/refreshes All IDs authorized before admission; invisible/cross-org target ->404. Per-target transport/offline failures recorded after acceptance. Coalesce identical concurrent reads and apply refresh policy; do not wake, acquire, renew or run an install as a probe. # Skip checking an unconfirmed installation Source: https://docs.phoneuse.com/api/endpoints/apps/skip-checking-an-unconfirmed-installation /api/openapi.json post /v1/app-store/installations/{installationId}/skip Managed Android app store. Requires apps:read, devices:read, devices:act, devices:lease. A signed-in person (never an API key) who has looked at the phone stops the checking of an installation whose result is still unconfirmed. The installation ends Failed with reasonCode skipped_by_person, which means only that nobody will confirm it: the app may in fact be on the phone. Its phone hold is released so the phone responds again and its install queue moves on. Who skipped it and when is kept. Nothing is sent, resent or uninstalled. Only an unconfirmed installation that is not being checked right now can be skipped (409 precondition_failed otherwise, also while another action holds the phone for a moment: try again); skipping again returns it unchanged. 503 feature_unavailable where this deployment cannot skip. # Answer a copilot approval Source: https://docs.phoneuse.com/api/endpoints/copilot/answer-a-copilot-approval /api/openapi.json post /v1/copilot/approvals Answer one `approval.request` from an open copilot stream. It returns as soon as the answer is recorded and tells you nothing about what happened next, because what happens next appears on the STREAM: `tool.call` then `tool.result` for an allow, `tool.denied` for a deny. A client waiting on this response to render the outcome is waiting for the wrong thing. Only the person the question was asked of may answer it, on the same organisation. An id that names nothing, one already answered, one that expired and one belonging to somebody else all answer 404 alike: telling them apart would make this a way to probe other people's outstanding questions. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Ask the copilot Source: https://docs.phoneuse.com/api/endpoints/copilot/ask-the-copilot /api/openapi.json post /v1/copilot One copilot turn, streamed. Two protocols answer on this route for one release, chosen by `Accept`. THE UI MESSAGE STREAM. List `application/vnd.phoneuse.ui-message-stream` in `Accept` and send the AI SDK transport's body: `{id, messages, trigger, messageId}`, where `id` is the thread id (a new one opens the thread) and `messages` is the client's transcript. ONLY THE LAST MESSAGE IS READ: a user message (its text parts) starts a turn, and an assistant message carrying a tool part in state `approval-responded` answers the question the previous turn ended on. The history the model is shown is the STORED thread, within a budget of 48000 characters of transcript, never the client's copy. What the budget cuts away is NOT forgotten: it is folded into a short summary the copilot writes once and keeps with the thread, shown in front of the recent messages on every turn after that, so a long conversation still knows what it was started for and which phone it was about. Nothing rebuildable from the server goes into that summary. The response is `text/event-stream` with the header `x-vercel-ai-ui-message-stream: v1`, one `data: ` frame per chunk, ended by `data: [DONE]`. It opens with `start` (naming the assistant message being written, which is the message a resumed approval continues), carries text and reasoning as deltas, every tool call as `tool-input-available` before it runs and `tool-output-available` (`{summary, text, frameId?}`), `tool-output-error` (`errorText`, which the protocol requires, and when the tool itself failed also `{message, code, retryable, retryAfterMs?}` beside it, on the stream only and never on a stored part) or `tool-output-denied` after, a `file` chunk with a `data:` URL for a screenshot of at most 204800 bytes, `data-device-choice` ({reason, devices:[{id, label}]}) when a call needed a phone and none was named, `data-suggestions` ({items:[{text, deviceId}]}, at most three, each naming a device) before `finish` on a turn that completed -- both of those ARE parts and survive a replay of the thread, and ends with `finish` (`finishReason`, and `messageMetadata.stopReason` from the copilot's own closed set) or with `error`, after which nothing follows. WHEN IT FAILS (API-232). `copilot_unfunded` means the copilot has no credit ON OUR SIDE: the message is the sentence to show, nothing the caller did caused it, and their phone and direct commands are unaffected. `rate_limited` is the provider throttling and is worth retrying. `model_unavailable` is the model being unreachable. Those three were ONE code until now, so a client could only ever say the vaguest of them; `model_refused`, `tool_failed` and `internal` complete the set. The older event stream still reports the first three as `model_unavailable`, because its console branches on the set as it stood. APPROVALS RIDE THE STREAM. Anything that changes the phone, takes or hands back the device, or starts an agent run asks first: `tool-approval-request` carries an `approvalId` and a descriptor with the tool, its arguments and one sentence to show, and the stream ENDS with `finish{finishReason: "tool-calls"}`. The descriptor says which card to draw and why: `kind` is `light` (one line and one row) or `plan` (a goal with an editable `budget` of `maxSteps` and `deadlineMs`), and `reason.code` is `start_run`, `install_app`, `dangerous_operation` or `boundary`. When one question covers the same tool on SEVERAL phones the descriptor carries `calls: [{toolCallId, tool, input}]` and one yes runs all of them, each as its own call with its own receipt; a dangerous operation is never folded into that list and always gets its own card. Answer by sending the same thread again with the assistant message's tool part in state `approval-responded` (`approval: {id, approved, reason?, input?, descriptor?}`); the next stream continues the same assistant message: the tool runs, or `tool-output-denied` ends the turn. `approval.input` is the person's EDIT of the arguments on a plan card: it is MERGED over the arguments they were shown, so sending only the field they changed does not delete the rest, and it is re-checked against the tool's published input schema. An edit the schema refuses is 400 naming the field, and nothing runs. If you echo `approval.descriptor.reason`, it must be the code the question was asked with, or the answer is 400: consent shown for one reason is not consent for another. Echoing nothing is accepted. The question does NOT expire on a clock: it waits until you answer it (Confirm or Decline) or a new message on the thread supersedes it, which closes it with `tool-output-error`. A turn takes at most 12 model steps, across the requests an approval splits it into. Closing the request aborts the turn: the copilot stops before its next step or tool call, what was written is kept, and the stored message ends with `finishReason: "stop"`. A tool already running completes and its receipt stands. THE EVENT STREAM (older). Any other `Accept`, or none, selects it. Send `{prompt}`; the response is a `text/event-stream` whose frames are named SSE events: `session.start` once, first; `message.delta` prose; `tool.call` a tool is ABOUT TO RUN; `tool.result` it finished, `isError` being the tool's own verdict; `approval.request` a question, the turn PAUSED; `tool.denied` you said no or nobody answered; `ping` keep-alive; `done` with a `stopReason`; `error` with a `code`. Exactly one `done` or one `error` ends every stream. Approvals are answered on `POST /v1/copilot/approvals`, a SEPARATE request, while the stream stays open; a client that closes the stream to answer loses the turn. This protocol goes in the release after the console has switched. WHICH PHONE (API-228). Both shapes take an optional `context` and `mentions`. When they name a device, the turn is about it: the model is told so, a call that needs a device and names none is given that one, and it does not ask which phone. When nothing names one and you have several, a `data-device-choice` chunk carries the candidates, the call is answered `tool-output-error`, and no phone is touched. A device id in `context` or `mentions` that your session cannot address is 400 naming the field; every wrong field is named in the one answer. Needs a signed in person. A copilot acts as somebody, and an API key has nobody behind it; drive the tools directly through the MCP endpoint instead. The turn can reach exactly the tools your session already has, no more, because it drives the same tool surface this service publishes. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Delete a thread Source: https://docs.phoneuse.com/api/endpoints/copilot/delete-a-thread /api/openapi.json delete /v1/copilot/threads/{id} Removes the thread from every listing and every read. There is no undo, and the id cannot be reused. Receipts for anything the copilot did in it are unaffected: they were never part of the thread. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # One thread, with a page of its messages Source: https://docs.phoneuse.com/api/endpoints/copilot/one-thread-with-a-page-of-its-messages /api/openapi.json get /v1/copilot/threads/{id} The thread and its newest messages, oldest first, as UI messages a chat client renders without translation. A tool part in state `approval-requested` on the last message is a question still waiting: answer it on POST /v1/copilot. PAGED, NEWEST FIRST. The response carries the newest `limit` messages; `nextBefore` names the oldest of them when older ones exist, and sending it back as `before` returns the page before that. A thread is heavy in a way a listing is not: every tool result carries its full text and every screenshot its bytes. Inline screenshots (`file` parts with a `data:` URL) are carried within a budget of 4194304 DECODED bytes per response (about 1.33 times that on the wire, as base64 inside JSON). The fit is greedy, newest first: each screenshot is kept if it fits what is left, so a large one that does not fit is left out while a smaller older one may still be carried. `files=none` leaves every one out. `omittedFiles` counts what was left out, and the `frameId` on the tool output beside each one still names the picture for the frames API. A thread that is not yours, one that was deleted, and one that never existed all answer 404 alike. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Pick a cut copilot stream back up Source: https://docs.phoneuse.com/api/endpoints/copilot/pick-a-cut-copilot-stream-back-up /api/openapi.json get /v1/copilot/threads/{id}/stream A phone that went to the background, a tab switched away from, a network that dropped. Reconnect here, say which message you were reading and how many of its parts you already have, and the rest arrives as the same UI message chunks the live stream sends, under the same header and ending with the same `data: [DONE]`. `since` is the `messageId` from the `start` chunk you were reading. `afterPart` is how many parts of it you already hold, so `0` (the default) replays the whole message and a number past its end sends the frame and nothing inside it, which is how you learn you are caught up. Omit `since` and the newest assistant message is replayed from the beginning, which is what a client that lost its place entirely needs. A `since` naming no message of this thread replays NOTHING rather than restarting from the top: restarting would repeat what you already have and hide that your cursor is stale. NO MODEL IS ASKED ANYTHING AND NOTHING IS WRITTEN. This reads a stored message back, so it answers the same on a deployment with no copilot configured, costs no tokens, and cannot change the thread. WHAT IT DOES NOT DO. It does not rejoin a turn that is still running, because after a disconnect there is not one: closing the request aborts the turn, the copilot stops before its next step or tool call, and what it had is written. So a reconnect delivers everything you missed up to the moment the connection died, and the turn does not carry on in the background. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Rename a thread Source: https://docs.phoneuse.com/api/endpoints/copilot/rename-a-thread /api/openapi.json patch /v1/copilot/threads/{id} The title is the one field a person edits; everything else the conversation writes. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Run one tool the person named Source: https://docs.phoneuse.com/api/endpoints/copilot/run-one-tool-the-person-named /api/openapi.json post /v1/copilot/commands Run ONE tool directly, as yourself, with no model involved and no tokens spent. This is what a `/screenshot` or a `/press_key home` typed in the console's composer becomes. It reaches the SAME tool surface a copilot turn drives, under the same permissions and the same approval table, so a command cannot do what the conversation would refuse. Two things differ from a turn, and both follow from the person having typed the tool themselves. It works on a deployment with NO copilot configured, because pressing Home should not need a model. And the receipt is not labelled `via copilot`: you did this, not the copilot on your behalf. WHAT IS DIRECT. Every read, plus `open_app`, `press_key`, `release_device`, `list_runs`, `cancel_run` and `resume_run`: the tools whose arguments a person can write out in full. `tap`, `swipe`, `type_text` and `long_press` are NOT, because the useful form of "tap the login button" is a sentence and the coordinates are the copilot's job; nor is `start_run`, which takes a goal and a budget. Those answer 400 and say to ask in the conversation instead. A tool your session has no scope for is a different answer: 403, naming the scope, because the remedy is an administrator rather than a rephrasing. WHICH PHONE. `context` and `mentions` work exactly as they do on `POST /v1/copilot`, so a command typed on a device's page needs no `deviceId`. A tool that needs one, with nothing in the input and nothing the context could resolve, is 400. IN A CONVERSATION. Send `threadId` and the result is appended to that thread as a tool part, which is what makes a command followed by a sentence work: the next turn's copilot sees what the command did instead of a gap. Without it the command still runs and leaves no trace in any conversation. IF IT ASKS FIRST. `start_run` raises a card in a command exactly as it does in the chat: the answer is 202 with an `approval` descriptor and an `approvalId`, and nothing has run. Show the card, then send the SAME `tool` and `input` again with that `approvalId`. The question is stored on the thread, so it can be answered minutes later and on any machine, and a gated command therefore needs a `threadId` to put its card in. The tool and arguments are checked against what was asked: a yes to one command cannot be spent on another. Needs a signed in person, as every copilot route does. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Stop the turn this thread is running Source: https://docs.phoneuse.com/api/endpoints/copilot/stop-the-turn-this-thread-is-running /api/openapi.json post /v1/copilot/threads/{id}/stop Stop the copilot mid-turn. The loop stops before its next model step or tool call, and what it had written is stored like any other ending, so the thread reads as a turn that stopped rather than one that vanished. A stop does not undo anything: a tool already dispatched has finished and its receipt stands. `stopped` is false when nothing was running this thread, including after the service restarted, which ends any turn it was running. That is an answer, not an error: there is nothing left to stop. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Your copilot threads Source: https://docs.phoneuse.com/api/endpoints/copilot/your-copilot-threads /api/openapi.json get /v1/copilot/threads Your own conversations with the copilot, newest activity first: titles and counts, never bodies. A thread belongs to the person who opened it. Nobody else in the organisation sees it here, and an API key has no threads at all. `q` matches the title. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Act on the device Source: https://docs.phoneuse.com/api/endpoints/device-surface/act-on-the-device /api/openapi.json post /vrx/{runToken}/v1/devices/{deviceId}/actions Look before you touch: an action is refused until this run has fetched at least one frame, because coordinates with no frame behind them have no meaning. The action is bound to the frame it was decided on. Matching geometry is not enough on its own, since two different screens at the same resolution compare equal, so a superseded frame is refused and you are told to observe again. Retrying a request whose response you lost replays the recorded outcome instead of touching the screen twice. A person may drive the same device beside this run, and their gestures go ahead of the run's waiting ones. Every response carries `others`, what principals other than this run did since the frame this action was bound to, and by default an action is refused `STALE_FRAME` when that count is above zero: re-observe as you already do. Send `refuseIfOthersActed: false` to be informed instead of stopped. Gestures on one device run one at a time in arrival order, and a device with too many waiting answers `ACTION_UNAVAILABLE`; wait and retry, the run is untouched. This operation reads no `Authorization` header. The run token in the path IS the credential, so the whole url is secret: never log it, paste it, or commit it. Every example writes `{runToken}` for that reason. # Check the run's device channel Source: https://docs.phoneuse.com/api/endpoints/device-surface/check-the-runs-device-channel /api/openapi.json get /vrx/{runToken}/v1/health Confirms the run is live and its channel is serving. This operation reads no `Authorization` header. The run token in the path IS the credential, so the whole url is secret: never log it, paste it, or commit it. Every example writes `{runToken}` for that reason. # Fetch a frame Source: https://docs.phoneuse.com/api/endpoints/device-surface/fetch-a-frame /api/openapi.json get /vrx/{runToken}/v1/devices/{deviceId}/screenshot Returns raw image bytes, not JSON and not base64. A frame is metered BEFORE the pixels are returned. If the metering write fails, the frame is withheld and the request fails: the path that could hand out an uncounted frame is the path that must not exist. The implication runs one way only, and it is stated rather than hidden: a frame that was delivered was counted, but a frame that was counted may not have been delivered, because a client can disconnect between the two. Running out of budget refuses the frame; it does not end the run. A worker that takes one last look before reporting success should not have that success turned into a failure. A frame is also refused, with the same 409, while the run is parked for a person (`needs_user_control`) or on hold (`paused`): the device is not observed by the worker while a person has stopped it, so a worker should wait and retry, not report failure. A person may drive the same device beside this run without stopping it. What they did since this run's previous frame rides in three response headers, so a worker can look again before it decides: `X-PhoneUse-Others-Actions`, `X-PhoneUse-Others-Last-At` (absent when the count is 0) and `X-PhoneUse-Others-By` (absent when the count is 0; otherwise `person`, `agent` or both, comma separated). The driver this surface exists for reads no headers and loses nothing. This operation reads no `Authorization` header. The run token in the path IS the credential, so the whole url is secret: never log it, paste it, or commit it. Every example writes `{runToken}` for that reason. # List the run's device Source: https://docs.phoneuse.com/api/endpoints/device-surface/list-the-runs-device /api/openapi.json get /vrx/{runToken}/v1/devices Returns exactly one device: the one this run is bound to. A run token is never a fleet listing, and it cannot be walked sideways onto another device. This operation reads no `Authorization` header. The run token in the path IS the credential, so the whole url is secret: never log it, paste it, or commit it. Every example writes `{runToken}` for that reason. # Report the run's outcome Source: https://docs.phoneuse.com/api/endpoints/device-surface/report-the-runs-outcome /api/openapi.json post /vrx/{runToken}/v1/report How a worker says it is done. It lives on this surface rather than on the run surface because a worker holds exactly one credential, its run token, and should never need an org credential to close its own work. The token also pins WHICH run is being reported, so a worker cannot close somebody else's. `needs_user_control` parks the run for a person, who lifts it through the run surface. Secrets never travel in this body. Once a run is parked, only a person can end it: a `succeeded` or `failed` report on a parked run is refused with a 409 until someone resumes or cancels it. Reporting `needs_user_control` again is allowed and only refreshes the handoff instruction. This operation reads no `Authorization` header. The run token in the path IS the credential, so the whole url is secret: never log it, paste it, or commit it. Every example writes `{runToken}` for that reason. # Act on a device Source: https://docs.phoneuse.com/api/endpoints/devices/act-on-a-device /api/openapi.json post /v1/devices/{deviceId}/actions One gesture per request: tap, swipe, long press, type text, press a key, open an app. Coordinates are in the normalized 0-1000 grid, so nothing has to know the device's resolution. WHOSE LEASE. Any caller may leave `leaseId` out. The gesture then runs under the lease your organisation currently holds on the device, whoever inside it took that lease (an agent's run, a colleague, you), and the response says so in `coDriving`. When your organisation holds none, a lease is taken for you and the gesture runs under it; if that gesture then fails, the lease taken for it is given back before the error is answered, and your next gesture takes one again. Two people taking an idle device at the same moment both drive it: one took the lease, the other is co-driving under it. When another organisation holds the device the answer is the 409 the acquire route gives. Taking needs `devices:lease`: a key with only `devices:act` acts on a device its organisation already holds. A signed-in person's gesture slides a lease THEY hold when it is running low; it never extends anybody else's. DRIVING BESIDE AN AGENT. A person's tap does not interrupt a run, and does not wait behind it either: gestures on one device run one at a time, a signed-in person's go ahead of every agent gesture still waiting, and the rest keep their arrival order. The lease is checked again when a gesture's turn comes (one that ended while it waited answers `lease_required`), each one is receipted with who took it, and every result carries `others`: what principals other than you did since your anchor. The agent reads the same field on its own results, so it is informed rather than stopped. The only interruptions are explicit and yours: `POST /v1/runs/{runId}/pause` and `POST /v1/runs/{runId}/cancel`. The response resolves only once the DEVICE applied the gesture. `status` has one value, and an action that did not commit is an error rather than a different status. Every attempt is on the receipt ledger before it is dispatched, so `GET /v1/receipts` can answer what happened even when this response is lost. Send your own `idempotencyKey` and a retry replays that outcome instead of touching the phone twice. A device may refuse a gesture it cannot perform; read its `capabilities` first. A robot arm, for instance, can tap and swipe and cannot type. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Give a device back Source: https://docs.phoneuse.com/api/endpoints/devices/give-a-device-back /api/openapi.json delete /v1/devices/{deviceId}/lease Release a lease by the id the acquire returned. Releasing a device you do not hold does nothing, so a retry is safe. THE LEASE ID GOES IN THE BODY, on a DELETE. That is unusual and it is on purpose: the id is a credential, and a query string is written to access logs, browser history and `Referer` headers. Nothing extra is ever asked of this call, whatever else the API gates on: the moment somebody most needs to hand a device back is the moment they are least able to complete a second step, and an attacker gains nothing from a release. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Image recovery progress and availability Source: https://docs.phoneuse.com/api/endpoints/devices/image-recovery-progress-and-availability /api/openapi.json get /v1/devices/{deviceId}/image-maintenance Requires devices:read and the caller's permitted device subset. Read the current organization's owned cloud phone recovery case and availability. Ordinary recovery returns the saved case and cancel/recheck actions; deployments without that runtime retain existing legacy maintenance information. Availability does not change the phone's main status. Supplier tasks, target images, control credentials and authorization evidence are never exposed. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Keep a device longer Source: https://docs.phoneuse.com/api/endpoints/devices/keep-a-device-longer /api/openapi.json patch /v1/devices/{deviceId}/lease Extend a lease you already hold, so work longer than one lease can keep its device. The expiry SLIDES to ten minutes from now; it does not add ten minutes to the old one, and `leaseId` and `acquiredAt` do not change, so keep using the same id. Renew before the lease expires. An expired lease cannot be renewed, because by then the device is available to everyone else and you have to take it again. Works on a device that is briefly unreachable, unlike acting on one: losing a claim because the phone blinked would hand it to the next caller while you are still mid task. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # List the devices you can see Source: https://docs.phoneuse.com/api/endpoints/devices/list-the-devices-you-can-see /api/openapi.json get /v1/devices Every device your credential can address, in any status. This is the REST counterpart of the `list_devices` tool and reads the same directory, so the two cannot disagree about what you own. READ `status` CAREFULLY. It answers whether the control plane can reach the device, and nothing more. An `online` device may be held right now by an unexpired lease, so `online` is not a promise that you can acquire it; the acquire call is the only thing that answers that, and it is deliberately unable to tell you WHY it refused. There is no `available` field here for that reason. A device your org owns that discovery cannot currently reach is reported `offline` rather than dropped, because the row is what makes a device exist, not whether a transport can see it today. The exception is a device whose backend this deployment has no adapter for: it is not listed at all, and asking for it by id answers 404. The same is true of the `list_devices` and `get_device` tools. A key narrowed to a subset of devices sees only that subset. A device outside your org, and one that never existed, answer identically. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # List the devices your organisation currently holds Source: https://docs.phoneuse.com/api/endpoints/devices/list-the-devices-your-organisation-currently-holds /api/openapi.json get /v1/leases The leases your organisation holds right now, among the devices this credential can see. This is what answers "how many of my devices are in use"; `GET /v1/devices` answers how many exist and how many are reachable, and the two are different questions. A DEVICE MISSING FROM THIS LIST IS NOT AVAILABLE TO YOU. It means only that you hold no live lease on it. It may be held by someone else, or your quota may be spent: the acquire call is deliberately unable to tell those apart, and this endpoint does not tell you either. Acquiring is the only thing that answers whether you can acquire. The listing can never name a device `GET /v1/devices` would not: leases are looked up for the devices that listing returns, so a key narrowed to a subset of devices sees leases only within that subset. The lease id and fencing token are not returned. The id is the credential `release_device` checks, and publishing it to every reader would let one of your runs release another's lease. Ordered by expiry, soonest first. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Live video fault observation Source: https://docs.phoneuse.com/api/endpoints/devices/live-video-fault-observation /api/openapi.json post /v1/devices/{deviceId}/image-maintenance/fault Requires devices:act, the caller's device subset and current organization ownership. Send only a client observation; no raw target image or recovery authority is accepted. PhoneUse verifies eligibility and persistent device faults before any nonwipe recovery. A local connection observation can be acknowledged without a saved case. For unknown outcomes, read the saved case before deciding what to do next. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Look at a device's screen Source: https://docs.phoneuse.com/api/endpoints/devices/look-at-a-devices-screen /api/openapi.json get /v1/devices/{deviceId}/screenshot The current screen, as raw image bytes. The media type says which encoding. YOU DO NOT NEED THE LEASE. Any credential in the organisation that can see the device can watch it, whoever is holding it right now. That is the difference between this route and every other way to reach a screen: the MCP `screenshot` tool takes a `leaseId` and refuses without it, and a run's `/vrx` frame endpoint is bound to that one run. This route exists so a person can see what a device is doing before deciding whether to interrupt it. Watching changes nothing, so it writes no receipt. It also returns no `frameId`, and that is not an omission: a frame id is the token you bind an action to, and taking one here would make it the device's current frame and cause the next action by whoever actually holds the lease to be refused as stale. If you intend to act, acquire the device and take a screenshot through the tool that issues frames. An offline device answers 409, not 404. It exists; there is simply no screen to read at the moment. A device your organisation does not own answers 404 exactly as an id that never existed does. Responses are `no-store`. A screen is live state and a cached one is worse than none. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Open a live video session on a device Source: https://docs.phoneuse.com/api/endpoints/devices/open-a-live-video-session-on-a-device /api/openapi.json post /v1/devices/{deviceId}/live-session Mint the short-lived vendor token a browser needs to drive this device as real-time video, the interactive alternative to polling the screenshot route. Hand the whole body to the video SDK: `token` is the SDK credential, `baseUrl` is the endpoint it connects to, `padCode` is the device's vendor instance, `userId` is a stable per-person id for the SDK, and `resolution` is the SDK's profile (16 is 720x1920, and the SDK then aligns to the device's real aspect ratio). `serverManagedLifetime` reports whether this issued session uses the server-managed lifetime and revocation path. Only true allows a video-only player to disable SDK idle recovery; false or a missing field keeps SDK defaults. The field grants no additional permission or lease. PERSON ONLY. This is a human's real-time control of a device, so an API key is refused: an agent has nobody behind it to drive as, and it drives through the governed action path instead. The token is a credential, so do not store it; it is never written to a log. YOU NEED THE SEAT. You may open a session when your organisation holds a lease on the device, whether it is yours, a colleague's, or a running agent's, and opening one never seizes the device or interrupts an agent. When your organisation holds no lease there is nothing to drive under, so take the device first with `POST /v1/devices/{deviceId}/lease`, then open the session. A device that is not a cloud phone has no video channel and answers 400. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Open a live view of a device Source: https://docs.phoneuse.com/api/endpoints/devices/open-a-live-view-of-a-device /api/openapi.json post /v1/devices/{deviceId}/stream Ask how to show this device's screen live, and get everything the player needs in one answer. Every device answers with the same shape; `transport` says which entry of `connect` to use. `provider-rtc`: a cloud phone. `connect["provider-rtc"]` holds the same connection fields `POST /v1/devices/{deviceId}/live-session` returns, for the provider's video SDK. `snapshot`: no live video for this device here. Poll `fallback.screenshot` no faster than `fallback.maxFps`. Controls never travel over the video channel. Send gestures to `controls.actions` as usual; `controls.via` is `sdk` only for a cloud phone with no agent run on it, whose player sends a person's input through the provider. While a run drives a cloud phone, `controls.via` is `api`: send the person's gestures to `controls.actions`, so the run is told somebody else acted before its next action. `via` is decided when you open the view; `GET /v1/devices/{deviceId}/driving` reports a `run` exactly while it would say `api`, so read that to notice a run starting or ending while the view is open. When this service cannot tell whether a run is on the device, it says `api`. PERSON ONLY and YOU NEED THE SEAT, exactly as for a live session: a signed-in person with `devices:act` whose organisation holds a lease on the device (theirs, a colleague's, or a running agent's). Opening a view never takes the device or interrupts an agent. Tokens are credentials; do not store them. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Original recovery result recheck Source: https://docs.phoneuse.com/api/endpoints/devices/original-recovery-result-recheck /api/openapi.json post /v1/devices/{deviceId}/image-maintenance/recheck Requires devices:act, the caller's device subset and current organization ownership. Use the original saved caseId; no target selection or replacement case is accepted. Cancel is eligible only before submission and when temporary control is clear. Recheck schedules observation of the original result; it does not replay the original device operation. Recovered and canceled cases offer neither action. The server decides availability when the request arrives. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read one device Source: https://docs.phoneuse.com/api/endpoints/devices/read-one-device /api/openapi.json get /v1/devices/{deviceId} One device's current status and capabilities without enumerating the fleet. Every status is a valid answer here, including `offline`: this route reports state, it does not refuse devices that are not usable right now. A device your org does not own answers 404 exactly as an id that never existed does. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read the server's clock Source: https://docs.phoneuse.com/api/endpoints/devices/read-the-servers-clock /api/openapi.json get /v1/time The server's clock, for a player lining its timestamps up with the device's. `receivedAt` is when the request reached the handler and `sentAt` is when the answer left it, both ISO-8601 with milliseconds. With your own send and receive times that gives the usual four-timestamp offset estimate. Any credential may call it; responses are `no-store`. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Rename a device Source: https://docs.phoneuse.com/api/endpoints/devices/rename-a-device /api/openapi.json patch /v1/devices/{deviceId} Sets the label you see this device by. The name is yours: nothing in the control plane reads it, and `deviceId` remains the only thing that addresses the device. Needs `devices:act`, not the `devices:read` the two reads need. A read scope that could also write would hand every read-only credential you have issued a write it was never meant to have. `displayName` is the only field accepted today. Tags are coming and are refused meanwhile rather than ignored, and a body with no `displayName` is refused rather than answered with the unchanged device. The response is the device as it now reads, through the same view the listing uses, so there is no second call to find out whether the write landed. A device your organisation does not own answers 404 exactly as one that never existed does. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Saved recovery plan cancellation Source: https://docs.phoneuse.com/api/endpoints/devices/saved-recovery-plan-cancellation /api/openapi.json post /v1/devices/{deviceId}/image-maintenance/cancel Requires devices:act, the caller's device subset and current organization ownership. Use the original saved caseId; no target selection or replacement case is accepted. Cancel is eligible only before submission and when temporary control is clear. Recheck schedules observation of the original result; it does not replay the original device operation. Recovered and canceled cases offer neither action. The server decides availability when the request arrives. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Small pictures of several devices' screens Source: https://docs.phoneuse.com/api/endpoints/devices/small-pictures-of-several-devices-screens /api/openapi.json get /v1/device-thumbnails The latest small picture of each device you name, for a gallery of tiles. One request answers for a whole page of devices, straight from memory: pictures are refreshed about every 30 seconds while someone is asking, and not at all when nobody is. Like the screenshot route, you do not need the lease, and looking changes nothing on the device: no receipt, no frame, no charge. Unlike it, the pictures are small (about 180 pixels wide), may be up to a few minutes old (`capturedAt` says when), and are never suitable for deciding where to tap. Each device answers in one of three states. `ready` carries the picture as a `data:` URL in `image`, with a `version`; send that version back in `have` and an unchanged picture comes back without `image`. `pending` means the first picture is still being taken. `unavailable` carries a `reason`: `offline`, `setting_up` (not delivered yet), `not_entitled` (the rental or paid period has ended), `staff_hold`, `unsupported` (this kind of device has no picture here), `provider_error` (pictures cannot be taken right now), `disabled` (not switched on for your organisation) or `not_found`. A device your organisation does not own, or one outside an API key's devices, answers `not_found` exactly as an id that never existed does. A failure to take pictures is never an error response: the last good picture stays `ready` with its old `capturedAt`, or the device is `pending` or `unavailable`. One answer carries at most 2 MB of pictures. A picture that does not fit answers `pending` with a short `refreshAfterMs`; ask again with `have` for the ones you got and it arrives next. Each caller may ask 20 times a minute here, on top of the shared rate limit. Ask again after `refreshAfterMs`. Responses are `no-store`. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Take a device Source: https://docs.phoneuse.com/api/endpoints/devices/take-a-device /api/openapi.json post /v1/devices/{deviceId}/lease Claim exclusive use of a device and get a lease back. Send the `leaseId` on every gesture and on the release; leases expire on their own after ten minutes, so renew if you are still working. A REFUSAL DOES NOT SAY WHY, and that is deliberate. Someone else holding it, a spent quota and an unreachable device all answer the same way, because a caller that could tell them apart would have a running commentary on the organisation's device state and its quota. `GET /v1/devices` says the same thing from the other side: `online` is not a promise you can take it. This is the REST counterpart of the `acquire_device` tool and runs the same lifecycle call, so the two faces cannot disagree about who may take what. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Wake a device's screen Source: https://docs.phoneuse.com/api/endpoints/devices/wake-a-devices-screen /api/openapi.json post /v1/devices/{deviceId}/wake Ask a device to wake its screen and clear its lock screen. A cloud phone that started with its screen off shows no picture until something wakes it, so a live video session opened on it would sit blank; call this to bring it up, and call it again on a reconnect if the picture has not arrived. BEST-EFFORT, which is why it answers 202 and carries no result. It asks the phone to wake through the same server-side channel that drives it, and a 202 means the request reached the device, NOT that the screen is on yet: the phone may already be awake, in which case the call does nothing, and waking is safe to repeat. `POST /v1/devices/{deviceId}/live-session` already wakes the device as it hands back a token, so a caller that opens a session does not need to call this first; this route exists for the reconnect, where there is no new token to mint. PERSON ONLY, and gated exactly like opening a live session on the same device: it needs a signed-in person with `devices:act`, an API key is refused, and your organisation must hold a lease on the device, whether it is yours, a colleague's, or a running agent's. When your organisation holds no lease there is nothing to drive, so take the device first with `POST /v1/devices/{deviceId}/lease`. A device that is not a cloud phone has no screen to wake and answers 400. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Who is driving a device Source: https://docs.phoneuse.com/api/endpoints/devices/who-is-driving-a-device /api/openapi.json get /v1/devices/{deviceId}/driving One read for the question a Control view asks after every gesture: is an agent on this device, is a colleague, and whose lease is it under. `lease` is your organisation's live lease and who inside it holds it, or null; another organisation's lease reads as none, exactly as it does on `GET /v1/leases`. `run` is the run driving the device right now, or null once it has finished. `people` are the people other than you who acted on the device in the last sixty seconds, and `agentLastActionAt` is when an agent last did. It joins three things `devices:read` can already read one route at a time, and adds nothing to them: no lease id, no run token, and never a name. A device your organisation does not own, or one outside your key's narrowing, answers 404 exactly as an id that never existed does. An offline device still answers: this route asks who is driving, not whether the phone is reachable. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Discover where to authenticate Source: https://docs.phoneuse.com/api/endpoints/discovery/discover-where-to-authenticate /api/openapi.json get /.well-known/oauth-protected-resource RFC 9728 protected resource metadata. The control plane is a resource server only: it issues no tokens and runs no authorization endpoints, and this document names the authorization server that does. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Discover where to authenticate, at the endpoint suffixed path Source: https://docs.phoneuse.com/api/endpoints/discovery/discover-where-to-authenticate-at-the-endpoint-suffixed-path /api/openapi.json get /.well-known/oauth-protected-resource/mcp The same document as the unsuffixed path, byte for byte. Both exist because clients try both, and the bearer challenge points at this one. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Check that the service is up Source: https://docs.phoneuse.com/api/endpoints/health/check-that-the-service-is-up /api/openapi.json get /healthz An unauthenticated liveness probe. `status` is the one word to branch on: `ok`, `degraded` when a background loop has stopped moving, or `incident` when an operator has declared one. A declared incident also carries `incident.title` and `incident.url`. A hosted deployment running the billing loop reports one boolean for it, and nothing else about the deployment is disclosed. # Accept the original multi-unit purchase agreement Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/accept-the-original-multi-unit-purchase-agreement /api/openapi.json post /v1/proxy-purchases Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Archive an expired detached Proxy Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/archive-an-expired-detached-proxy /api/openapi.json post /v1/proxies/{proxyId}/archive Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Cancel a Proxy order Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/cancel-a-proxy-order /api/openapi.json post /v1/proxy-orders/{orderId}/cancel Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Cancel original undelivered units Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/cancel-original-undelivered-units /api/openapi.json post /v1/proxy-purchases/{purchaseId}/cancel Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Connect or disconnect a Proxy Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/connect-or-disconnect-a-proxy /api/openapi.json post /v1/proxy-operations Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # List managed Proxy products Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/list-managed-proxy-products /api/openapi.json get /v1/proxy-products Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # List your managed Proxies Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/list-your-managed-proxies /api/openapi.json get /v1/proxies Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # List your Proxy network operations Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/list-your-proxy-network-operations /api/openapi.json get /v1/proxy-operations Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # List your Proxy orders Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/list-your-proxy-orders /api/openapi.json get /v1/proxy-orders Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Quote a managed Proxy purchase Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/quote-a-managed-proxy-purchase /api/openapi.json post /v1/proxy-quotes Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Quote a multi-unit Proxy purchase Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/quote-a-multi-unit-proxy-purchase /api/openapi.json post /v1/proxy-purchase-quotes Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read a device's confirmed Proxy relationship Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/read-a-devices-confirmed-proxy-relationship /api/openapi.json get /v1/devices/{deviceId}/proxy Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read a managed Proxy Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/read-a-managed-proxy /api/openapi.json get /v1/proxies/{proxyId} Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read a managed Proxy product Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/read-a-managed-proxy-product /api/openapi.json get /v1/proxy-products/{productId} Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read a Proxy operation Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/read-a-proxy-operation /api/openapi.json get /v1/proxy-operations/{operationId} Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read a Proxy order and its settlement Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/read-a-proxy-order-and-its-settlement /api/openapi.json get /v1/proxy-orders/{orderId} Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read the original purchase agreement Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/read-the-original-purchase-agreement /api/openapi.json get /v1/proxy-purchase-quotes/{quoteId} Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read the original quote Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/read-the-original-quote /api/openapi.json get /v1/proxy-quotes/{quoteId} Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read unit delivery and original payment facts Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/read-unit-delivery-and-original-payment-facts /api/openapi.json get /v1/proxy-purchases/{purchaseId} Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Rename a managed Proxy Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/rename-a-managed-proxy /api/openapi.json patch /v1/proxies/{proxyId} Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Request hosted Checkout for an order Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/request-hosted-checkout-for-an-order /api/openapi.json post /v1/proxy-orders/{orderId}/checkout Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Reserve a quoted Proxy order Source: https://docs.phoneuse.com/api/endpoints/managed-proxy/reserve-a-quoted-proxy-order /api/openapi.json post /v1/proxy-orders Requires a first-party interactive organization session with devices:read. Financial commands require an administrator and the configured checkout step-up policy. Network commands also require devices:act, current device authority and explicit consent. New purchase/connection commands require current admission. No credentials are returned. A deployment without the durable composition returns capability_unavailable (422). Renewal, transfer, replace, order target/delivery edits, operation resume and event feeds are not available. Preserve command identity after an uncertain reply and read the original order or operation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Send a JSON-RPC request Source: https://docs.phoneuse.com/api/endpoints/mcp/send-a-json-rpc-request /api/openapi.json post /mcp The Model Context Protocol endpoint. It speaks JSON-RPC over one request and one response, so it is a single operation here rather than one per tool: a document that flattened the tools into endpoints would describe a protocol the service does not speak, and a client written against it would fail on the first call. The tools, their parameters and their results are documented in the tool reference. The endpoint is stateless. There is no session to open or terminate, and a lease travels as an explicit tool parameter. Requests carrying a browser `Origin` are refused, and the `Host` header must match the deployment's own host. # Why there is no event stream Source: https://docs.phoneuse.com/api/endpoints/mcp/why-there-is-no-event-stream /api/openapi.json get /mcp There is no event stream to resume, so this method is refused. The refusal is documented rather than omitted, because a client that expects a stream should learn why it will not get one. # Why there is no session to end Source: https://docs.phoneuse.com/api/endpoints/mcp/why-there-is-no-session-to-end /api/openapi.json delete /mcp There is no session to terminate, so this method is refused. The refusal is documented rather than omitted, for the same reason the event stream is: a client that closes its sessions should be able to see that there is nothing here to close. # /v1/minute/cases Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minutecases /api/openapi.json get /v1/minute/cases Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/cases Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minutecases-1 /api/openapi.json post /v1/minute/cases Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/cases/:id Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minutecases:id /api/openapi.json get /v1/minute/cases/{id} Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/catalog Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minutecatalog /api/openapi.json get /v1/minute/catalog Current minute quotes and paged compute configurations. Unavailable configurations carry no payable quote; available region quote IDs reference the same response quotes. Optional timing identities describe supplier app-facing profiles separately from compute hardware; identity null means automatic allocation, and absent identity facts preserve the legacy path. Requested identities bind immutable original quotes. Optional models/nextCursor/catalogRevision appear together when the model source is configured. Legacy unpaged quotes-only response remains readable; configured model pages cap both arrays at 100. Opaque cursors bind organization, complete business revision, search and requested identity; changes return 409 and require refreshing page one. Target model is mutually exclusive with cursor and q. This read does not dispatch supplier procurement or change previously accepted quote terms. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/orders Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minuteorders /api/openapi.json get /v1/minute/orders Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/orders Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minuteorders-1 /api/openapi.json post /v1/minute/orders Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/orders/:id Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minuteorders:id /api/openapi.json get /v1/minute/orders/{id} Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/orders/:id/cancel Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minuteorders:idcancel /api/openapi.json post /v1/minute/orders/{id}/cancel Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/refunds Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minuterefunds /api/openapi.json get /v1/minute/refunds Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/refunds Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minuterefunds-1 /api/openapi.json post /v1/minute/refunds Retired on 2026-10-09: unused balance can no longer be refunded online. Every request answers 503 `minute_unavailable` with `retryable: false` and a message giving the support address. No refund, reservation or case is created, nothing is sent to the payment provider, and the balance stays available to use. `permissions.canRefund` on the wallet is always false. Requests made before the retirement stay readable at `GET /v1/minute/refunds`, and any already approved refund still completes. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/refunds/:id Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minuterefunds:id /api/openapi.json get /v1/minute/refunds/{id} Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/rentals/:deviceId Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minuterentals:deviceid /api/openapi.json get /v1/minute/rentals/{deviceId} Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/rentals/:deviceId/resume Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minuterentals:deviceidresume /api/openapi.json post /v1/minute/rentals/{deviceId}/resume Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/rentals/:deviceId/return Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minuterentals:deviceidreturn /api/openapi.json post /v1/minute/rentals/{deviceId}/return Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/requests/:requestId Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minuterequests:requestid /api/openapi.json get /v1/minute/requests/{requestId} Observe an existing committed original request without creating an account/intent, settling fees, dispatching work or invoking provider recovery. First-party OAuth administrator, devices:read, original organization and actor required. Supply only original kind/body fields: order quoteId+quantity; cancel orderId; return deviceId+expectedEpoch+expectedImpactVersion+expectedIncarnation; resume deviceId+expectedEpoch+quoteId+expectedIncarnation; topup quoteId with optional paired returnQuoteId+returnQuantity. Missing committed receipt returns found:false and does not prove an in-flight POST had no effects; changed identity is 409. Original return/resume binding is separate from the device's current allocation. Historical rental receipts grant no new action authority; order cancellation eligibility retains its current unit-state fact and scope gate. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/starts Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minutestarts /api/openapi.json post /v1/minute/starts Start pay-by-the-minute phones in one request. Each phone holds 10 minutes of its rate (startMicrosPerPhone) when it starts. Enough available balance for quantity x startMicrosPerPhone: the order is placed now and the answer is kind started with the order (no payment). Otherwise: a top-up for the missing amount (at least USD 5.00, rounded up to whole cents) is opened with this selection attached, and the answer is kind payment with checkoutUrl. When that payment is confirmed (Stripe event, GET of the start or top-up, or the background sweep) within 1 hour of the selection and nothing replaced it, the order is placed once with the supplier's offer at that moment; if it cannot start (sold out, rate changed, balance used up) the money stays as balance and state is not_started with a reason. Paid later than 1 hour: balance only (expired). A newer start or top-up replaces a selection still waiting for its payment. Same requestId and selection returns the same start; a different selection under it is 409. The order id is start:{requestId}. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/starts/:id Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minutestarts:id /api/openapi.json get /v1/minute/starts/{id} One start by its requestId. Reading it also checks an open payment with Stripe and, if paid within the hour, places the order once, like the background sweep. Includes the top-up (payment starts) and the order once it exists. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/topup-quotes Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minutetopup-quotes /api/openapi.json post /v1/minute/topup-quotes Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/topups Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minutetopups /api/openapi.json post /v1/minute/topups Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/topups/:id Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minutetopups:id /api/openapi.json get /v1/minute/topups/{id} Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/topups/:id/abandon Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minutetopups:idabandon /api/openapi.json post /v1/minute/topups/{id}/abandon Close an unpaid top-up after the customer left Stripe Checkout (Checkout's cancel return carries checkout=cancelled). Stripe decides: if it was paid, the top-up is credited once and answers confirmed; if still open, the Checkout is expired at Stripe and the top-up answers failed with closeReason abandoned; if already expired, it answers failed. No body. Repeat calls return the same final record; a top-up that is already confirmed or failed is returned unchanged. When Stripe cannot be read or the expiry is not proven, nothing changes and the answer is 503 minute_unavailable with retryable true. No failure notice is sent. Starting a new top-up closes older unpaid ones the same way (closeReason replaced). Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # /v1/minute/wallet Source: https://docs.phoneuse.com/api/endpoints/minute-billing/v1minutewallet /api/openapi.json get /v1/minute/wallet Private prepaid minute contract. Organization admin first-party session required. Stable request ID binds original operation. Pending or unknown payments do not grant funds. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Change which emails you receive Source: https://docs.phoneuse.com/api/endpoints/notifications/change-which-emails-you-receive /api/openapi.json patch /v1/me/notification-preferences Send either field or both. A field you leave out keeps its current value, and when you have never set these that value is your role's default rather than off: sending only `emailOrders: false` must not silently turn off the emails a run sends when it asks for a person too. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Mark notifications read Source: https://docs.phoneuse.com/api/endpoints/notifications/mark-notifications-read /api/openapi.json post /v1/notifications/read Marks these notifications read FOR YOU. Nobody else's bell changes. Ids that name nothing are accepted rather than refused, because one kind of notification is computed rather than stored and dismissing it is the normal case. Marking something read twice keeps the first instant: when you saw it is a fact about you, and a second call must not rewrite it. Needs a signed-in person. An API key has no reader, so it cannot record what has been read. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # The bell, and the list behind it Source: https://docs.phoneuse.com/api/endpoints/notifications/the-bell-and-the-list-behind-it /api/openapi.json get /v1/notifications What has happened that a person might want to know about: a run that needs somebody, and what became of an order. `actionRequiredUnread` is the number to put on the bell. It counts the org's unread notifications that need somebody to act, across everything and not just this page, so it does not drop to zero when somebody scrolls. An arrival is not counted: nothing is being asked of anybody. READ STATE IS PER PERSON. A colleague opening the bell does not clear it for you. An API key has no person behind it, so it reads the org's notifications with `readAt` null on all of them, and it cannot mark anything read. One kind is computed rather than stored. An order that has gone past its estimate has no event behind it, only a clock passing a recorded instant, so it appears on the FIRST page with an id prefixed `derived:`. It is marked read like any other item, and it does not repeat on later pages. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Which emails you receive Source: https://docs.phoneuse.com/api/endpoints/notifications/which-emails-you-receive /api/openapi.json get /v1/me/notification-preferences Your own email preferences. `isDefault` is true until you set them, and what you see until then is what your role implies: an admin receives everything, a member receives requests for a person only. Needs a signed-in person. An API key has no inbox. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Cancelling online is retired: contact support Source: https://docs.phoneuse.com/api/endpoints/provisioning/cancelling-online-is-retired:-contact-support /api/openapi.json post /v1/fulfilments/{id}/cancel Orders can no longer be cancelled online. Since 2026-10-09 this route answers 409 `wrong_state` for every order that has not already ended, with a message giving the support address, and the body names the state the order is in. Nothing is asked of the payment provider, nothing is changed and no refund is made. Contact support and our team will help; any refund is their decision and is made by hand. AN ORDER THAT HAS ALREADY ENDED, by our team or by an earlier cancel, answers 200 with `alreadyDone: true`, so a repeated press is told the truth rather than refused. A repeat within 24 hours of an earlier success is answered with that first answer, unchanged, and carries `Idempotent-Replayed: true`. Send no `Idempotency-Key` here; this route does not read one. ADMIN, AND A SIGNED-IN PRINCIPAL ONLY. An API key is refused before the order is read, as before. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Check one returned Checkout now Source: https://docs.phoneuse.com/api/endpoints/provisioning/check-one-returned-checkout-now /api/openapi.json post /v1/checkout-sessions/{orderId}/confirm Call when the buyer lands back from Checkout. Reads that one session from Stripe and, when it is paid, records it exactly as the payment webhook would. Safe to repeat; a repeat within 10 seconds does not read Stripe again. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Check whether your organisation is provisioned Source: https://docs.phoneuse.com/api/endpoints/provisioning/check-whether-your-organisation-is-provisioned /api/openapi.json get /v1/admission Your own organisation's provisioning state, and when it last changed. The console renders one screen per `status`, so this is the read that decides which one a signed-in user sees. IT ANSWERS ONLY ABOUT THE CALLER'S OWN ORGANISATION, taken from the verified credential and never from anything the caller supplies. `none` here is the organisation asking about itself, so it is not a cross-tenant disclosure and this endpoint is not an existence oracle for anybody else. `since` is null exactly when `status` is `none` and the organisation has never left it. MOUNTED ON EVERY HOSTED DEPLOYMENT, including one that cannot provision at all: no provisioning dependency configured, or a deployment that is not finished being set up. Those answer 503 with `Retry-After`, not 404. The route used to vanish on such a deployment, which meant it could not be described here, and an operation absent from this document is one no consumer contract check can protect. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # List what can be bought and what it costs Source: https://docs.phoneuse.com/api/endpoints/provisioning/list-what-can-be-bought-and-what-it-costs /api/openapi.json get /v1/skus The price list, one entry per pair of sku and billing mode, so that a caller drawing a purchase screen has a number to show before the customer commits. Monthly Cloud phone prices INCLUDE TAX (any tax is inside the amount, never added on top) and come from the payment provider's own price objects; this service reports them and never computes one. Any signed in principal in the organisation may read it, of either role, because a member who is allowed to buy has to be allowed to see what things cost. The admin rule lives on the purchase itself. A pair this deployment holds no price for is ABSENT from the list rather than present without a price, so the list is exactly what can be bought here today. Buying a pair that is not in it answers 503. Each entry says whether it ships today as `stock`, a verdict and never a count. The shelf is read once per request for the whole list, and a shelf that cannot be read makes every entry `unknown` rather than failing the list: prices that were read are still shown. Nothing in the answer is specific to your organisation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Open the billing portal Source: https://docs.phoneuse.com/api/endpoints/provisioning/open-the-billing-portal /api/openapi.json post /v1/billing/portal-sessions Returns a link into the payment provider's hosted billing page for your organisation. Changing the card, reading invoices and downloading receipts all happen there; this service draws none of them itself. ADMIN, AND A SIGNED-IN PRINCIPAL ONLY, the same rule the purchase route applies. An API key and a member both get 403. The link is SINGLE USE AND SHORT LIVED. Navigate to it straight away; ask again for a fresh one next time. Its Return link comes back to the console's Billing page, decided by this service rather than by the request. An organisation with NO BILLING ACCOUNT at the provider gets 409 `billing_not_started` rather than a link to a page that cannot load. An organisation whose phones were all returned still has its account, and opens it to read invoices and receipts. ONE BILLING ACCOUNT PER LINK. Each purchase has so far opened its own account at the provider, so an organisation that bought more than once has several, and this opens the one behind its most recent purchase that is still running (the newest of any state when none is). A card changed there pays that purchase's subscription; earlier subscriptions keep their card. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read a Cloud phone's current monthly renewal state Source: https://docs.phoneuse.com/api/endpoints/provisioning/read-a-cloud-phones-current-monthly-renewal-state /api/openapi.json get /v1/fulfilments/{id}/renewal-status For a paid monthly Cloud phone, read the current Stripe subscription and latest verified paid invoice. The response says whether another monthly charge is scheduled and when the current verified paid period ends. When a draft or open invoice needs review, `invoiceReview=true` and `paidThrough` can be in the past; an already issued invoice may still collect even if `renews=false`. `paidThrough` does not guarantee device availability: supplier service is checked separately. This read makes a previous period-end stop visible after the page is reloaded. An org admin must be signed in; API keys and non-Cloud orders cannot use it. An invoice review is reported only when the exact subscription and a prior paid invoice are verified; other unverified billing states answer 503. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Returning online is retired: contact support Source: https://docs.phoneuse.com/api/endpoints/provisioning/returning-online-is-retired:-contact-support /api/openapi.json post /v1/fulfilments/{id}/return Devices can no longer be returned online. Since 2026-10-09 this route answers 409 `wrong_state` for every order that has not already ended, whatever the device, with a message giving the support address, and the body names the state the order is in. Nothing is asked of the payment provider, nothing is changed and nothing is refunded. Contact support and our team will help. A Cloud phone keeps its paid period, and `POST /v1/fulfilments/{id}/cancel-renewal` stops its next charge. AN ORDER THAT HAS ALREADY ENDED answers 200 with `alreadyDone: true`, so a repeated press is told the truth rather than refused. A repeat within 24 hours of an earlier successful return is answered with that first answer, unchanged, and carries `Idempotent-Replayed: true`. Send no `Idempotency-Key` here; this route does not read one. ADMIN, AND A SIGNED-IN PRINCIPAL ONLY. An API key is refused before the order is read, as before. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Start provisioning this organisation Source: https://docs.phoneuse.com/api/endpoints/provisioning/start-provisioning-this-organisation /api/openapi.json post /v1/checkout-sessions Begins a purchase and returns somewhere to send the browser. WHAT IS BEING BOUGHT is an optional `{sku, billing}` body. Send it to buy a named thing at the price `GET /v1/skus` published for that pair. Send no body at all, as a caller with nothing to choose between does, and the deployment's single default price applies, which is what this route did for every caller before it read a body. A body naming a pair this deployment holds no price for answers 503 rather than quietly charging the default: taking the wrong amount is worse than taking none. WHO MAY CALL IT. A signed-in org ADMIN: a member cannot commit the organisation to a subscription and gets 403. A deployment may additionally require the admin's recent identity check, refusing with `reverification_required`; whether it does is configuration. OR an API key holding `orders:place`, for PREPAID plans only (pay as you go answers 403). Only an admin's session holds that scope and a key never carries more than its minter, so such a key was created or approved by an admin; a key has no sign-in to check, so no identity check is asked of it. A key without the scope gets 403. AN ORGANISATION MAY BUY AGAIN. Phones are bought one order at a time, so an organisation that already has a phone, or a subscription, can start another purchase; there is no already-provisioned refusal. What stops a double purchase is one open order per organisation, below. SEND AN `Idempotency-Key` AND A RETRY COSTS NOTHING. With one, a repeat within 24 hours is answered with the FIRST attempt's answer, the same checkout url and the same order id with no new session, and the response carries `Idempotent-Replayed: true` so you can tell. That is what makes a lost response safe to retry: the 2xx you never received is handed to you rather than reproduced. WITHOUT ONE, calling it again while an attempt is open RESTARTS that attempt where the earlier one can still be made unpayable, and refuses with 409 `checkout_in_progress` where it cannot, which is the case that matters: an order the customer has already paid for is never abandoned out from under an inbound payment. Restarting is safe for your money and costs you the session already open in the browser, which is the whole reason to send a key. Every reason this deployment cannot provision, one that is not finished being set up and one with no payment provider configured alike, answers one 503 code. From a caller's side they are one situation and splitting them would only make the console branch on a distinction it cannot act on. WHAT A KEY CAN AND CANNOT DO HERE. It opens a Checkout page and returns its url; a PERSON still has to pay on that page, so a program cannot spend money while nobody is watching. Cancelling or returning an order, the billing portal and pay as you go stay with a signed-in person, and no scope grants them. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Stop future Cloud phone renewal at Stripe's current period end Source: https://docs.phoneuse.com/api/endpoints/provisioning/stop-future-cloud-phone-renewal-at-stripes-current-period-end /api/openapi.json post /v1/fulfilments/{id}/cancel-renewal An org admin can disable a monthly Cloud phone's next Stripe charge without returning the phone or refunding the current payment. The server verifies the exact account, Customer, subscription, Price, latest verified paid invoice and current billing period, then schedules `cancel_at_period_end=true` and reads it back. The action is safe to repeat. `paidThrough` is payment evidence, not a guarantee of uninterrupted supplier availability. Cloud phones cannot be returned, and orders cannot be cancelled online (contact support). With a draft or open renewal invoice, a durable operator alert is recorded before the stop, and a confirmed stop returns 202 because the existing invoice can still collect. An uncertain Stripe state answers 503; it never claims future retries were stopped without confirmation. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # What you owe next Source: https://docs.phoneuse.com/api/endpoints/provisioning/what-you-owe-next /api/openapi.json get /v1/billing/upcoming The next bill: when it lands, what it comes to, and how many lines it has. `currentPeriodEnd` IS THE FIELD MOST CALLERS WANT: the date a subscription renews. It is answered once for the organisation rather than once per order, deliberately: a per-order answer would cost one call to the payment provider for every row of a list, and it would have to put a renewal date on ended orders, where the honest value is never. EVERY NUMBER HERE IS THE PAYMENT PROVIDER'S, read back and passed on unchanged. Nothing on this side computes, estimates or annualises an amount, and `amountMinor` is in the currency's minor unit because that is the only form it has not been through arithmetic to reach. NOTHING SCHEDULED IS A 200 WITH NULLS, not a 404. An organisation whose purchases are all pay as you go has no upcoming invoice, and neither has one that has ended everything; both are ordinary states of a working account and a screen should say so rather than show an error. ANSWERS ONLY ABOUT THE CALLER'S OWN ORGANISATION. The provider's customer reference comes off this organisation's own purchases and never off the request. NEEDS `devices:read`, the same scope `GET /v1/usage` needs. Money is read on the same terms as minutes: a credential narrow enough to be refused one device's usage is not wide enough to be told what the whole organisation owes. Until 2026-09-22 this route asked only that SOME credential was present, which put the organisation-wide number behind a weaker gate than the per-device one. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # What your organisation has bought, and where each purchase got to Source: https://docs.phoneuse.com/api/endpoints/provisioning/what-your-organisation-has-bought-and-where-each-purchase-got-to /api/openapi.json get /v1/fulfilments Your own organisation's device purchases, newest first. This is the read that lets a paid customer with no device yet be shown something other than an empty screen. IT IS NOT `GET /v1/admission`. Admission says which screen a signed-in user sees; this says what was purchased and whether it arrived. They were the same question only while admission was the thing being sold. WHEN NO DEVICE WAS FREE at the moment a purchase settled, the purchase still succeeds and comes back as `awaiting_provisioning` with an `estimatedBy` date. That is a commitment made to the customer, not an error state, and it is the case this endpoint exists for. The date can be moved by us, which is why it is an estimate; every move is recorded. ANSWERS ONLY ABOUT THE CALLER'S OWN ORGANISATION, taken from the verified credential. An empty list is the organisation asking about itself and discloses nothing about anybody else. MOUNTED ON EVERY HOSTED DEPLOYMENT, including one that is not finished being set up for provisioning: those answer 503 with `Retry-After`, not 404, for the reason given on `GET /v1/admission`. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Where the identity provider delivers Source: https://docs.phoneuse.com/api/endpoints/provisioning/where-the-identity-provider-delivers /api/openapi.json post /webhooks/clerk NOT AN ENDPOINT YOU CALL. The identity provider posts here, and today this does one thing: it sends the sign-up verification email, in plain text, when the provider's own template is set not to deliver. NO CREDENTIAL OF OURS AUTHENTICATES IT, because the sender holds none. A delivery is authenticated by a signature over the raw body, carried in three `svix-*` headers and checked before the body is parsed. WHAT THE STATUS CODES MEAN. 200 is settled and should not be delivered again, including the outcomes that could not send anything, because a repeat carries the same payload. 400 is a delivery that was not authentic or not readable, and nothing was sent. 503 is a send that failed in a way worth repeating. A repeat of a delivery whose email already went out does not send a second one. A body over 262144 bytes is refused as it streams. IT IS ABSENT ON A DEPLOYMENT WITHOUT A SIGNING SECRET OR WITHOUT AN EMAIL SENDER, and in local mode. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Where the payment provider delivers Source: https://docs.phoneuse.com/api/endpoints/provisioning/where-the-payment-provider-delivers /api/openapi.json post /webhooks/stripe NOT AN ENDPOINT YOU CALL. The payment provider posts here, and this is the step that turns a settled payment into admission and a provisioned device, and a reversal back out again. NO CREDENTIAL OF OURS AUTHENTICATES IT, because the sender holds none. A delivery is authenticated by a signature over the raw body, checked before the body is parsed and before anything is recorded. No `Authorization` header is read here and sending one changes nothing, which is why this route sits outside `/v1` rather than inside it. WHAT THE STATUS CODES MEAN, which is the real contract with the sender. 200 is settled: the transaction that recorded the event committed before the answer was sent, so the delivery is finished. 400 is a delivery that was not authentic or not readable, and nothing was recorded. 5xx is ours to fix and the delivery should be repeated; there is deliberately no retry inside this process. A repeat of an event already recorded settles again rather than applying twice. A body over 262144 bytes is refused as it streams, before any of it is held in memory. That is tighter than the service wide cap the 413 below describes, and it is the one that applies here. IT IS ABSENT ON A DEPLOYMENT THAT HAS NO SIGNING SECRET CONFIGURED. An endpoint that accepts bodies it cannot authenticate is worse than a 404, so such a deployment does not mount it at all. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Whether one checkout was paid Source: https://docs.phoneuse.com/api/endpoints/provisioning/whether-one-checkout-was-paid /api/openapi.json get /v1/orders/{orderId}/payment-status Says whether one of your organisation's checkouts is still waiting for payment, was paid, failed, or ended without a payment. A delayed payment method that fails creates no order row in `GET /v1/fulfilments`, so this is the read that tells a failed payment from one that is still being confirmed. ANSWERS ONLY FOR YOUR OWN ORGANISATION AND SIGN-IN. An order of another organisation, or one written under another sign-in instance, answers exactly as one that never existed. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # List your robot purchases Source: https://docs.phoneuse.com/api/endpoints/robot-purchases/list-your-robot-purchases /api/openapi.json get /v1/robot-purchases Requires a first-party signed-in organization session. Records only the initial robot purchase payment receipt; every quantity remains not delivered. No device provisioning, setup or current subscription entitlement is implied. Newest first, at most 100, for this workspace and sign-in instance only. Includes unpaid, expired and review states; each row is the same receipt summary as the single read, plus createdAt. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Open the original monthly robot checkout Source: https://docs.phoneuse.com/api/endpoints/robot-purchases/open-the-original-monthly-robot-checkout /api/openapi.json post /v1/robot-purchases/checkout Requires a first-party signed-in organization session. Records only the initial robot purchase payment receipt; every quantity remains not delivered. No device provisioning, setup or current subscription entitlement is implied. Only a workspace administrator may open checkout, under the configured checkout step-up policy. Charges USD149 per unit per calendar month starting at checkout, less any promotion code the buyer enters there; delivery is separate. Price, buyer and workspace are derived by the server. A pending/unknown original blocks replacement checkout. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read the monthly robot checkout offer Source: https://docs.phoneuse.com/api/endpoints/robot-purchases/read-the-monthly-robot-checkout-offer /api/openapi.json get /v1/robot-purchases/offer Requires a first-party signed-in organization session. Records only the initial robot purchase payment receipt; every quantity remains not delivered. No device provisioning, setup or current subscription entitlement is implied. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read your initial robot purchase receipt Source: https://docs.phoneuse.com/api/endpoints/robot-purchases/read-your-initial-robot-purchase-receipt /api/openapi.json get /v1/robot-purchases/{orderId} Requires a first-party signed-in organization session. Records only the initial robot purchase payment receipt; every quantity remains not delivered. No device provisioning, setup or current subscription entitlement is implied. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Cancel a run Source: https://docs.phoneuse.com/api/endpoints/runs/cancel-a-run /api/openapi.json post /v1/runs/{runId}/cancel Ends the run. An action already in flight when you cancel is refused before it reaches the device, so cancelling stops the arm rather than merely marking a record. Terminal is terminal: cancelling a finished run leaves it as it was. # Get a short-lived URL for one archived frame Source: https://docs.phoneuse.com/api/endpoints/runs/get-a-short-lived-url-for-one-archived-frame /api/openapi.json get /v1/frames/{frameId} Returns a presigned URL that renders one frame, good for about a minute. Fetch this with your credential, then use the `url` it returns as the image source: this route needs a bearer token and an `img` element cannot send one. Where a frameId comes from: a run's `lastFrame.frameId`, and the `observedFrame` an action receipt was bound to. On a finished run `lastFrame` is the frame the model's report was written from, so this is how you show what the model said next to the screen it read that off. ONE ANSWER FOR EVERY KIND OF UNAVAILABLE. A frame belonging to another org, an id that never existed, a frame whose bytes are not yet confirmed, one that was retired or has passed a finite retention expiry, an encrypted one, and a frame captured on a device your key cannot address all answer 404 `frame_not_found`. So this route cannot be used to discover which frames exist. A deployment that archives no frames answers 404 for every id, because with no bucket the frame was never stored. # Lift a stop and let the run carry on Source: https://docs.phoneuse.com/api/endpoints/runs/lift-a-stop-and-let-the-run-carry-on /api/openapi.json post /v1/runs/{runId}/resume Lifts either kind of stop, and only a person can lift either. From `needs_user_control`: the agent asked a person to do the next step on the same screen, and this is the person saying it is done (the console's Done). The worker cannot lift its own request. If `recovery` is non-null, this is instead an interrupted hosted run: send its exact `id` as `expectedRecoveryId` and currently own the device lease. Missing or stale recovery IDs leave the run unchanged. The call does not acquire a lease, clear unresolved actions, or grant extra steps. A successful continuation uses the saved time budget capped by the current lease and starts with a fresh observation. From `paused`: a person put the agent on hold, and this lets it continue. The run continues from the CURRENT screen, so nothing already done is repeated and whatever a person did meanwhile is what it sees, and its frozen deadline slides forward by however long the hold lasted, capped by the lease's own expiry. A terminal run stays terminal, and a run in any other state comes back unchanged. # List your runs Source: https://docs.phoneuse.com/api/endpoints/runs/list-your-runs /api/openapi.json get /v1/runs Your organisation's runs, newest first. Each entry carries the goal the run was started with and how it ended, so a run is still readable long after it finished and a lost runId is recoverable. Page with the `nextBefore` cursor a full page hands back; when it is absent you have reached the end. # Put a run on hold Source: https://docs.phoneuse.com/api/endpoints/runs/put-a-run-on-hold /api/openapi.json post /v1/runs/{runId}/pause Suspends the agent. The run moves to `paused`, the worker's channels are shut until Resume (it is served no frames and its actions are refused), its deadline FREEZES, and the run's lease slides to a fresh ten minute window so the hold has one. The worker's steps are untouched: resuming carries on from the current screen rather than redoing what is already done. You do not need this to act on the device. A signed-in person drives a device beside a running agent through `POST /v1/devices/{deviceId}/actions` without naming a lease, and the agent is informed of what you did rather than stopped. Pause is the explicit interruption you choose when you want the agent to stop while you work. It is not a handoff. `needs_user_control` is the agent asking a person to do the next step on the same screen, and Resume (the console's Done) lets it continue; this is a person suspending a run that asked for nothing, so it works from `queued`, `running` and `needs_user_control` alike. Two ways the hold ends badly, and they differ. RELEASE the run's lease while it is on hold and the run ends `failed` with reason `lease_lost`. Simply walk away, and when `manualControlUntil` passes the run is `canceled` with the explanation in `detail`. No new failure reason is used for either case. Calling it again on a run already on hold is safe: nothing is re-stamped and you get the same lease and the same window back. # Read a run, optionally waiting for it to move Source: https://docs.phoneuse.com/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move /api/openapi.json get /v1/runs/{runId} Returns the run as it is now. With `waitMs` it waits for the state to leave `sinceState` and returns as soon as it does, or at the deadline with whatever the state is then. It never hangs: the transport is stateless and there is no push channel. EITHER ID WORKS HERE. Send the `runId` `POST /v1/runs` returned, or the run's `agentRunId`: the id every receipt the run produced carries and the one a permalink is built on. An id starting `run_` is read as an agentRunId, anything else as a runId. Both answer with the same run through the same checks, `waitMs` included. The writes below take a runId only. This returns the run only. Its action trail is a separate, paged resource, `GET /v1/receipts?agentRunId=...`, and it is not folded in here: it is a paged collection with its own cursor and its own retention. This route applies the calling key's device narrowing: a run on a device your key cannot address is 404, the same 404 an unknown id gets. # Start a run on a device Source: https://docs.phoneuse.com/api/endpoints/runs/start-a-run-on-a-device /api/openapi.json post /v1/runs Hand one device your organisation holds to a run with a goal and a budget. Your organisation must already hold it: starting a run is permission to let a loop act for you, not permission to take the device, and this route is the one place that difference is visible (a gesture DOES take). `executor` says who drives it. `phoneuse` runs it for you and returns no url. `self_hosted` means your own worker drives it, and the response then carries the run scoped device surface url exactly once: treat it as a credential and give it to one worker only. Left out, it is `self_hosted` for an API key and `phoneuse` for a signed-in person. Your credential needs both `runs:start` and `devices:act`. # Confirm a phone looks right Source: https://docs.phoneuse.com/api/endpoints/usage/confirm-a-phone-looks-right /api/openapi.json post /v1/devices/{deviceId}/unclear-actions/confirm A person looked at the phone and says it looks right after exactly the unclear actions they were shown, named by `ref`. Those actions stop keeping agent tasks waiting; the receipts themselves do not change. An agent task whose own action is confirmed takes a new screenshot before its next action. UNLIKE marking a receipt reviewed, THIS IS A SIGN-OFF, so it needs a signed in person and `devices:act`. References that are not unclear actions you may confirm on this phone now (already confirmed, another phone, a robot hand, an install, an action still inside its 30 second wait) are ignored rather than refused, so answering a list another tab already confirmed is harmless. The answer says how many were newly confirmed, what is still unclear (with `retryAfterMs` on any still waiting) and whether agent tasks may use the phone now. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # List a phone's unclear actions Source: https://docs.phoneuse.com/api/endpoints/usage/list-a-phones-unclear-actions /api/openapi.json get /v1/devices/{deviceId}/unclear-actions The ordinary actions on a cloud phone your organization holds whose result could not be confirmed: taps, swipes, typing, keys, opening an app, rotating and waking. An agent task's own action is listed once that task has stopped acting, with `agentRunId` naming it. Oldest first, at most 50, including any left by an organization that held the phone before (shown without its key, kind, times or run). An action a signed-in person did not make directly (an agent task's, Copilot's, an API key's or any other caller that is not a person) can be confirmed only 30 seconds after it ended, so a late result has time to show on the screen first; until then `retryAfterMs` says how long is left. A person's own has no wait. People can keep using the phone meanwhile. Until a person confirms it looks right, no agent task can start or act on the phone and giving it back in the background is refused. `agentReady` says whether agent tasks may use it now, and `inProgress` whether one of your actions is still under way, which also keeps them waiting briefly. A robot hand, a real device, an app install and an action still in progress are never listed: they keep their own paths. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # List your org's receipts Source: https://docs.phoneuse.com/api/endpoints/usage/list-your-orgs-receipts /api/openapi.json get /v1/receipts Every action your org has taken, newest first. This is the enumeration counterpart to the `get_receipt` tool: use that one to recover a lost response, and this one to answer what has happened. TWO DIFFERENCES FROM `get_receipt`, both worth knowing before you reach for it. It answers about ONE key rather than a page, and it requires the `deviceId` as well as the key. This route and `GET /v1/receipts/{idempotencyKey}` do not: an idempotency key is unique PER DEVICE, so one organisation can legitimately hold the same key on two devices, and these two resolve that by answering 400 and naming `deviceId` only when it actually happens. So a recovery path that does not know which device it sent to has to come here, not to the tool. Narrowing the tool to match is filed as D170 and is not in this release. Paging is keyset based, not offset based, so rows cannot be skipped or repeated while new receipts arrive. When a page is not the last, the response carries `nextBefore` and `nextBeforeKey`; send them back as `before` and `beforeKey` for the next page, and stop when they are absent. Send BOTH, and send them unchanged: the ordering is by timestamp and key together, and receipts written concurrently routinely share a timestamp. A key narrowed to a subset of devices sees only that subset. Asking about a device outside it returns an empty page rather than a refusal, which is the same shape a narrowed key already sees in device listings: out of subset reads as nothing here, never as exists but denied. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Mark a receipt reviewed Source: https://docs.phoneuse.com/api/endpoints/usage/mark-a-receipt-reviewed /api/openapi.json post /v1/receipts/{idempotencyKey}/reviewed Records that a person opened this receipt, and who. This is what makes a needs review queue possible: `requiresManualReview` says an action's physical effect is unknown, and until now nothing said whether anybody came to look. IT IS NOT AN APPROVAL. It says somebody read the receipt. Nothing in this service treats it as consent to the action, and the receipts it is used on are precisely the ones whose effect could not be confirmed. The first call wins and later ones answer 200 with `stamped: false`, because who looked first is a fact about them and two colleagues opening the same row is ordinary rather than an error. Reading the receipt afterwards returns `reviewedAt` and `reviewedBy`. Needs a signed in person. An API key has nobody behind it, so it cannot have looked at anything. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read one receipt Source: https://docs.phoneuse.com/api/endpoints/usage/read-one-receipt /api/openapi.json get /v1/receipts/{idempotencyKey} One recorded action, addressed by the `idempotencyKey` you sent with it. This is the permanent URL for a receipt: the listing answers what has happened, and this answers what happened in one case, without paging to find it again. THE KEY IS NOT UNIQUE ON ITS OWN. Idempotency is defined per device, so one organisation may hold the same key on two devices. When it does, this answers 400 and asks for `deviceId` rather than choosing a receipt for you: a page showing the wrong action with nothing to say so is worse than a refusal. Keys minted by agent runs carry a frame id and never collide, so this is a hand written key's problem. A key belonging to another organisation answers 404 exactly as one that was never used does, and a key narrowed to a subset of devices reads only within that subset. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Read your org's usage this period Source: https://docs.phoneuse.com/api/endpoints/usage/read-your-orgs-usage-this-period /api/openapi.json get /v1/usage Settled usage for the current billing period, per device, derived from the same per-lease rows billing reads. Built for a headless integrator: the hosted product shows this in a browser, and this endpoint is how you read it without one. `activeMs` is measured active time, corrections already applied, which is the quantity this control plane measures and therefore the one it reports. `reportedMinutes` is minutes AS ALREADY REPORTED to billing, echoed rather than recalculated here, because the per-lease rounding rule has a single owner and a second implementation of it would be a second source of truth for an invoice. It is ABSENT until reporting has happened, which is a different fact from zero: read it as not reported yet, never as free. Only settled leases appear. A lease you are holding right now is still open and is not in these numbers, so this is an account of what has finished rather than a live meter. A key narrowed to a subset of devices sees only that subset. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Enable or disable a subscription Source: https://docs.phoneuse.com/api/endpoints/webhooks/enable-or-disable-a-subscription /api/openapi.json patch /v1/webhooks/{webhookId} A disabled subscription receives nothing. Deliveries already queued for it are not retried either: you said you did not want them, and finishing a retry schedule against a subscription somebody just turned off is the opposite of that. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Remove a subscription Source: https://docs.phoneuse.com/api/endpoints/webhooks/remove-a-subscription /api/openapi.json delete /v1/webhooks/{webhookId} Deletes it outright, and its delivery records with it. A delivery log for a subscription nobody can see is a log nobody can interpret, so it goes too. Disable instead if you want to keep the history. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Replace a signing secret Source: https://docs.phoneuse.com/api/endpoints/webhooks/replace-a-signing-secret /api/openapi.json post /v1/webhooks/{webhookId}/rotate Returns a new signing secret and the old one STOPS WORKING IMMEDIATELY. There is no overlap window, so a receiver still verifying with the old secret will reject every delivery from this moment: update it before you rotate, or accept a gap. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Send a test delivery Source: https://docs.phoneuse.com/api/endpoints/webhooks/send-a-test-delivery /api/openapi.json post /v1/webhooks/{webhookId}/test Queues one delivery on the SAME path a real event takes: same signature, same headers, same retries. It answers as soon as the delivery is queued rather than waiting for your endpoint, so read the result from the deliveries listing. It arrives as `run.ended` with `test: true` in the data, because a test that came in as something your router does not recognise would exercise the transport and nothing else. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Subscribe your system to what happens here Source: https://docs.phoneuse.com/api/endpoints/webhooks/subscribe-your-system-to-what-happens-here /api/openapi.json post /v1/webhooks Creates a subscription and returns its signing secret ONCE. Store the secret where your receiver can read it: to get another you have to rotate, which stops the old one working. HOW TO VERIFY A DELIVERY. Every request carries `PhoneUse-Signature: t=,v1=`, where the hex is HMAC-SHA256 of `.` under your secret. Compute it over the RAW bytes you received, before any JSON parsing, compare in constant time, and reject anything whose `t` is further from your own clock than you are willing to accept. The timestamp is inside the signed material precisely so that a captured delivery cannot be replayed at you a year later. DELIVERY IS AT LEAST ONCE. `PhoneUse-Delivery` is the same on every retry of one delivery, so deduplicate on it. A non-2xx answer is retried 5 times in all, over about twenty five minutes, and then given up on. Redirects are NOT followed: a 30x is recorded as the answer it is, because following one would send your payload to a url nobody checked. The destination must be https and must be reachable on the public internet. An address inside a private network is refused because this service would be the one making the request. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # What was delivered, and what happened Source: https://docs.phoneuse.com/api/endpoints/webhooks/what-was-delivered-and-what-happened /api/openapi.json get /v1/webhooks/{webhookId}/deliveries Every delivery attempted for one subscription, newest first: the event, when it was tried, what your endpoint answered, how many attempts it has had, and when the next one is due. A delivery id in another org answers 404, the same 404 an id that names nothing gets, so this is not an existence oracle. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # Your webhook subscriptions Source: https://docs.phoneuse.com/api/endpoints/webhooks/your-webhook-subscriptions /api/openapi.json get /v1/webhooks What your org has subscribed to, and where. Signing secrets are not here: one is returned when a subscription is created and again when it is rotated, and never after. Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404. # API overview Source: https://docs.phoneuse.com/api/index Two HTTP surfaces, and where the boundary between them runs. The control plane exposes two HTTP surfaces. They differ in who calls them and in how a caller proves it is allowed to. Reading the boundary correctly matters more than reading any single endpoint, so it comes first. ## The two surfaces | Surface | Paths | Credential | Called by | | - | - | - | - | | Control | `/healthz`, `/.well-known/oauth-protected-resource`, and the routes under `/v1` | Bearer token in the `Authorization` header | Your backend, and operators | | Device | `/vrx/{runToken}/v1/...` | The run token in the URL path | A worker executing one run | The control surface is the one you call to manage credentials, devices, runs, orders and webhooks, and to check health. Every route on it is listed in the API reference. The device surface is what a worker uses to observe and act on the one device its run is bound to. ## Driving a device Most callers never touch either surface directly for device control. An agent drives a device over MCP, at `POST /mcp`, and that endpoint speaks JSON-RPC rather than REST. Its shape is documented in the [tool reference](/mcp/reference), not here, because the unit of the MCP surface is a tool rather than an endpoint. There is also one REST route for gestures, `POST /v1/devices/{deviceId}/actions`, for a caller that does not speak MCP. [Buy and drive a device](/guides/first-device#act) shows it. For an agent, start at the [Quickstart](/quickstart). ## Authentication on the control surface Two credential channels resolve to the same authorization context, so nothing downstream needs to know which one you used. * **OAuth 2.1** for interactive clients. The control plane is a resource server only. Discovery follows RFC 9728 at `/.well-known/oauth-protected-resource`, which is also served under the `/mcp` suffix because clients try both. * **API keys** for headless callers. A key is scoped to one org, and may be narrowed further to a subset of that org's devices. Scopes are enforced when tools are registered rather than when they are called, so a tool your credential cannot use is not merely refused, it is absent. See [Authentication](/mcp/auth). ## Calling from a browser ### Browser access Browsers are refused by default. Cross origin requests from a web page only work if that page's origin has been added to the deployment's allow list, and the allow list is exact: there is no wildcard, and no subdomain matching. If you want to call this API from a web application, ask for your origin to be added. Three things about that grant are worth stating plainly, because each one is a decision rather than an accident. * **API keys are refused from browsers.** On a deployment that grants browser access at all, a request carrying both an `Origin` header and a `pbk_` (or `puk_`) key is answered `403 api_key_from_browser_origin`, and that holds for every origin, allow-listed or not. The refusal ships with the grant, so a deployment with no allow list configured does not apply it: there, such a request is authenticated in the ordinary way, because no browser can reach the API cross origin in the first place. An API key is a long lived, org wide credential, so a page holding one has effectively published it. Authenticate a browser with an OAuth session token instead. This applies to the control surface; if a server side integration of yours forwards a browser's `Origin` header upstream, strip it. * **Only the control surface is granted.** `POST /mcp` and the device surface at `/vrx/{runToken}/v1/...` refuse every request carrying an `Origin` header, and neither is part of the grant, so a page cannot call them with `fetch` and can never read a response from them. Note the exact shape of that guarantee: a browser omits `Origin` on a plain subresource load (an `img` tag, say), so a page that has somehow obtained a run token could still cause a `GET` on the device surface to execute, blind. Treat a run token as the device credential it is, and keep it out of pages you do not control. * **Credentials are sent in the header, never as cookies.** The grant does not enable `Access-Control-Allow-Credentials`, so send your bearer token in the `Authorization` header as any other client would. Rate limit headers and `WWW-Authenticate` are explicitly exposed to browser callers, so a page can read the budget it is being held to and can tell an expired token from a refused one. See [Rate limits](/api/rate-limits). ## The device surface and its run token The device surface exists so a worker can observe and act without holding an org credential. The token in the path **is** the credential: the surface reads no `Authorization` header, and sending one changes nothing. That token carries the org, the device, the lease and the run it belongs to, and it expires. It is bound to exactly one device, so it cannot be used to reach anything else in the fleet. > [!WARNING] > > A run token is a credential. Treat it like one. Never paste it into an issue, > a support thread, or a log you share, and never commit one. Every example on > this site writes `{runToken}` as a placeholder for that reason. Requesting a frame on this surface is metered before the pixels are returned. If the metering write fails, the frame is withheld and the request fails. That ordering is deliberate: it means no frame is ever served without being counted. See [The contract in full](/agent/worker#the-contract-in-full) for everything a worker may call on this surface. ## Rate limits In hosted mode both surfaces pass a limiter before anything else looks at the request, and which budget applies is decided by whether that request carries an `Authorization` header. Control surface calls do, so they are in the credentialed class. A worker on the device surface sends no such header, because its credential is in the URL path, so it is in the bare class. Local mode has no limiter at all. Every limited response carries its own budget in `RateLimit-*` headers, and those are authoritative over any number written down. See [Rate limits](/api/rate-limits). ## Health `GET /healthz` is unauthenticated and reports whether the service is up. In hosted mode it also reports whether the billing pipeline is healthy. It is the one path the limiter never applies to. # Rate limits Source: https://docs.phoneuse.com/api/rate-limits Three budgets, one refusal shape, and the headers that tell you where you stand. Every request to the hosted HTTP surfaces passes a limiter before it reaches a route. The limiter sits ahead of routing and ahead of authentication, so being refused here tells you nothing about whether your credential was any good. One thing is answered before the limiter and never counted: a browser's CORS preflight. See [If you are calling from a browser](#if-you-are-calling-from-a-browser). The numbers on this page are **defaults**. Every response that a budget applied to carries that budget in its headers, and those headers are authoritative: read them rather than hard coding what you find here. ## The three budgets | | Run | Credentialed | Bare | | - | - | - | - | | Applies to | A request on `/vrx/{runToken}/v1/...` naming a live run | Any other request with an `Authorization` header | Everything else | | Default budget | 600 requests / minute | 300 requests / minute | 60 requests / minute | | Counted per | The run | The credential | The client IP | Outside the device surface, which budget applies is decided by one thing: whether **this request** carries an `Authorization` header. It is a property of the request, not of the endpoint you aimed it at, so a client that adds a header from shared configuration changes its own budget. On the device surface the run wins, and the header is ignored there for pacing exactly as it is ignored for authorization. Two things follow from "counted per credential" that are easy to get wrong: * **The budget is per credential, not per org.** Two API keys in the same org hold two independent budgets, and one key exhausting its own cannot slow the other down. Respelling the header does not buy you a second budget: the credential is identified the same way the authenticator identifies it. * **A rotated key starts fresh.** A new token is a new budget. The limiter keeps only a hash, never the credential itself. There is also a ceiling on how many distinct credentials one client IP may hold separate budgets for at once. Past it, a credential that address has not been using is counted against its bare budget instead, and a slot is released once its credential goes quiet. Reaching the ceiling takes more than a handful of credentials in simultaneous use from one address, so if that is your shape, say so when you ask for access. It exists so that presenting a credential cannot itself become a way around the bare budget. ### If you are calling from a browser A browser sends a preflight (`OPTIONS`) before any request that carries an `Authorization` header. On a deployment that has granted your origin, the preflight is answered **before** the limiter and is not counted against any budget, yours or the bare one. It carries no `RateLimit-*` headers, because none applied. On a deployment with no origins granted there is no preflight handling at all, and an `OPTIONS` is counted like any other bare request. That is deliberate. A preflight never carries a credential, so counting it could only put it in the bare budget, shared with every other caller behind your egress address. And a refused preflight would never reach your code as a `429`: browsers treat any non-2xx preflight as a network error, with no status and no headers to read. So the API never refuses a preflight for rate, and a CORS error in your browser console is a CORS problem, not a rate limit. The request that follows the preflight is counted against your credential in the ordinary way. If it is refused, you get a real `429`: the response carries `Access-Control-Allow-Origin`, and `Retry-After` and the `RateLimit-*` headers are exposed, so your code can read them and back off. One caveat that applies to browsers more than to anything else: a session token that rotates presents a **new credential** on every rotation, and the ceiling on distinct credentials per client IP described above is reached by rotation alone. Past it, requests are counted against the bare budget until an older credential goes quiet, so a browser can find itself on the smaller budget without having changed anything it does. For bare requests the client IP is the one our edge recorded for the connection, falling back to the first hop in `X-Forwarded-For`. ### The device surface The device surface, `/vrx/{runToken}/v1/...`, carries its credential in the URL path and ignores any `Authorization` header, by design. It gets its own budget, counted **per run**. That means two runs behind one egress address do not share an allowance, and one run spending its own cannot slow another down. Adding workers behind the same address adds capacity rather than dividing it. The budget applies to a run the control plane currently holds live. A request naming a run token that has expired, ended, or never existed is counted against the **bare** budget for your client IP, alongside every other uncredentialed caller behind that address. That is the same answer such a request has always had, so a worker still calling after its run is over pays the bare rate. The switch happens when the run ends, not when you next call, so there is no window in which a finished run is still spending at the run rate. > [!NOTE] > > A run's budget bounds how fast it may call, not how much it may do in total. > The total is the run's step budget, which is fixed when the run starts and > enforced before any frame is issued. Raising one does not raise the other. Two consequences worth planning around: * **The budget arrives with the run.** It is in force from your first request, so there is nothing to register and nothing to wait for. * **It does not survive the run.** The moment the run reaches a terminal state its token stops working and its budget is withdrawn, so the next call gets a `404` counted against the bare budget. ## Being refused Over budget is `429`, with the control plane's HTTP error envelope: ```json theme={null} { "error": { "code": "rate_limited", "message": "Too many requests. Slow down and retry." } } ``` This is the HTTP envelope, not the MCP tool error envelope. The limiter runs before the MCP endpoint is reached, so a throttled tool call comes back as a transport level `429`, **not** as a result with `isError` and a `code` from the [error reference](/mcp/errors). A client that only branches on tool errors will see this as a transport failure, which is what it is. `Retry-After` on that response is an integer number of seconds, computed from how far under one request the caller actually is. It is not a fixed backoff constant, so honour it rather than replacing it with your own. ## The headers Every response that a budget applied to carries these: | Header | Value | | - | - | | `RateLimit-Limit` | The budget in effect for this caller class, in requests per minute | | `RateLimit-Remaining` | Whole requests still available when this request was admitted | | `RateLimit-Reset` | Seconds from that moment until the allowance is back to full | | `RateLimit-Policy` | The budget and its window, as `;w=60` | Both counts describe the allowance at the moment the request was admitted, not at the moment you read them. On a long running call the real figure has already crept up, so they understate rather than overstate what you have left. `RateLimit-Reset` and `Retry-After` answer different questions and will differ. Reset is seconds until **full**. `Retry-After` on a `429` is seconds until **one** request is available. Pacing against Reset when you only need one call will make you wait longer than necessary. The allowance refills continuously rather than resetting on a boundary, so a caller that has been idle can spend up to the full budget at once and then drains toward the steady rate. **Absence is information.** No `RateLimit-*` headers on a response means no budget applied to it, either because the path is exempt or because that caller class is switched off in this deployment. It never means "unknown". ## What is exempt `GET` and `HEAD` on `/healthz` are never limited, in any caller class. A `429` on a health probe would read as an outage and mask the real ones. Only those two methods are exempt, and only that exact path. On a deployment that has granted at least one origin, a CORS preflight on a path a browser may reach (`/v1/*`, `/healthz` and the discovery documents) is answered before the limiter and never counted. Only a real preflight qualifies: an `OPTIONS` request that carries an `Origin` header. An `OPTIONS` without one is an ordinary request and is counted like any other. ## What the budgets are scoped to Two boundaries worth knowing before you plan around these numbers. * **Per serving process.** The allowance lives in the process that answers you. Read the numbers as a floor you can rely on rather than a global ceiling on the deployment, and pace against the headers you actually receive. * **Hosted only.** Local mode has no limiter at all. It binds to loopback and serves one operator, so there is nothing to protect and no headers to read. Do not use local behaviour to predict hosted behaviour here. ## Living within them * Read `RateLimit-Remaining` and slow down before you are refused. Being refused costs you a round trip and tells you nothing you could not have read from the previous response. * On a `429`, wait `Retry-After` seconds and retry the same request. The refusal happens before any work, so nothing was half applied and the retry is safe. * Do not retry a `429` immediately or in a tight loop. The allowance refills on a clock, and retrying faster cannot make it refill faster. * If your steady state does not fit the default budget, say so when you ask for access. The budget is a deployment setting, not a property of the protocol. ### If you are driving a device One rule matters more on this surface than anywhere else, because getting it wrong is expensive in a way it is not elsewhere. **A `429` is not a failed run.** Wait `Retry-After` seconds and send the same request again. Nothing was applied, the device did not move, and the run's step budget was not spent: a refusal happens before any of that. A worker that treats any non-2xx as fatal, breaks out of its loop and reports the run `failed` turns one refusal into one lost run, with whatever actions it already performed left on the device. That failure mode is the reason this surface has its own budget, but the budget only widens the gap; it does not remove it. A worker that does not back off will still find the edge eventually, and when it does it should slow down rather than give up. Distinguish the two refusals you can get here, because they call for opposite responses: | Status | Meaning | What to do | | - | - | - | | `429` | Calling too fast | Wait `Retry-After`, retry the same request | | `404` | The run is over, or the token is not one | Stop. Do not retry | A `404` is deliberately the same answer for an expired run, a finished run and a token that never existed, so it is never worth retrying to find out which. # Versioning and compatibility Source: https://docs.phoneuse.com/api/versioning What the /v1 path does and does not promise, and the one mechanism that tells you when a shape you parse moves. Read this before you build something that has to keep working. It is short because the honest answer is short, and it says what is undecided as plainly as it says what is settled. ## There is one version, and it is the path `/v1` is the prefix on the control plane's REST routes, and it is the whole of the versioning scheme. A few paths sit outside it, and they carry no version in their path at all: * `/healthz`, which is the only tenant route left outside `/v1`; * `/mcp`, the MCP transport, where the tool list is the contract; * `/vrx/{runToken}/v1/...`, the worker surface a run hands out, whose `v1` comes after the run token; * `/.well-known/oauth-protected-resource` and its `/mcp` variant. The agent run routes used to be on that list, and that was the one open question on this page. It was decided on 2026-09-20, in the window before the launch, and the move has shipped: starting, reading, listing, pausing, resuming and cancelling a run are `/v1/runs` and `/v1/runs/{runId}` now. `GET /v1/runs/{runId}` also answers to the `agentRunId` that the old `GET /runs/{agentRunId}` took, so a permalink has one route rather than two. The old `/tasks` and `/runs` paths are not served at all: there is no alias and no redirect, they answer `404`. That is a break, and it is one this page can allow only because it happened **before** the 2026-09-25 baseline the freeze policy below protects. Nothing moves that way after that date. Every route in the published spec has a fingerprint, `/healthz` included, so a shape change there is just as visible to you. Four things follow from the path being the scheme, and each one is a fact about the running server rather than a plan. * **No version header selects a shape.** The server reads no request header that chooses between API versions, and one you invent is ignored. From a browser you cannot even send one: the preflight allow list for request headers is exactly `Authorization`, `Content-Type`, `x-phonebase-step-up` and `Idempotency-Key`. * **No dated version to pin.** There is no `2026-01-01` style version to request and no account level pin behind it. * **No `Deprecation`, `Sunset` or `Warning` response header.** Nothing in a response announces that a shape is on its way out. What you do get back is the rate limit budget (`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`), `Retry-After`, and `WWW-Authenticate`. See [Rate limits](/api/rate-limits). * **No `deprecated` marker in the spec.** Nothing in the published OpenAPI document is flagged as on its way out. There has never been a `/v2`. The practical consequence is the one worth stating out loud: **you cannot ask for an older shape.** When a response shape changes, it changes for every caller at the same moment. > [!NOTE] > > The OpenAPI document carries an `info.version` field. It tracks the package > that generates the document and it is not something you can request, so do > not read it as a compatibility signal. The fingerprints below are the signal. ## Pin the shape you parse This is the part to act on, and it works today. Every operation in the published spec has a fingerprint: a digest over the part of that operation your code can break on. Parameters, request body, the set of response status codes and each one's schema, response header names, security, and the `x-phoneuse` extensions all go in. Prose is excluded at every level, so rewording a description never moves a digest. The digests are published as a single file next to the spec: ```bash theme={null} curl -sS https://docs.phoneuse.com/api/contract-fingerprints.json ``` It needs no credential. Fetch it in your own CI, compare it against the digests you recorded when you wrote the parsing code, and fail your build when one of them moves. A digest that moved means the shape you parse moved, whether or not anybody remembered to tell you. That check runs in your pipeline, on your schedule, against an artifact you fetched yourself. It is the strongest thing on this page for exactly that reason. > [!WARNING] > > **A fingerprint sees shape, and it cannot see meaning.** A field that keeps > its name and its type while changing what it counts moves no digest. Neither > does a field the spec never declared. Treat the fingerprints as an alarm on > structure, and read the [changelog](/changelog) and the generated > [API reference](/api) for the rest. The spec those digests are computed from is itself generated from the route table the server runs, so it describes the surface rather than somebody's account of the surface. ## The MCP tool surface has its own rule The tool surface an agent drives is frozen from the launch on 2026-09-25 and evolves under a published program from then on. New tools, new optional parameters and new error codes are allowed. Renames and removals are not: a tool keeps its name and gains meaning, and there is no `tap_v2` family. A change that would break an existing caller goes through the deprecation program below first. Two things make that checkable from the outside. The server reports a tool surface version in the `serverInfo` a client reads at connect time, so a client can tell one published surface from another. And a parameter or field added after the frozen baseline carries an `@since` marker you can read in the [tool reference](/mcp/reference). Read [MCP surface](/mcp/overview#the-surface-is-a-frozen-contract) for the full statement of that contract. ## After launch, additive only This is the policy for `/v1` and for the MCP tool surface from the launch on **2026-09-25** onward. Before that date shapes under `/v1` changed in ways that required a caller to change with them, without notice. One example is on the receipt shape: `leaseId` and `fencingToken` were removed from it, because a read only credential could lift a live lease off the newest receipt and hand it to one that can act. The surface published on the launch date is the baseline this policy protects. Every change after launch falls into one of three tiers, and the tier decides what has to happen before it ships. 1. **Additive.** A new operation or tool, a new optional parameter, a new response field, a new error code. Allowed at any time with no notice, because a caller that ignores what it does not recognise keeps working. Parse responses that way: ignore fields you do not know. 2. **Meaning changes, shape does not.** A field keeps its name and type and what it tells you gets stricter. This is declared rather than versioned: the change is written into the [changelog](/changelog), and on the MCP surface the tool description carries an `@since` note. 3. **Breaking.** A rename, a removal, a new required parameter, or an optional field made required. This goes through a deprecation program. The change is announced in the [changelog](/changelog) with the date it takes effect, the old shape keeps being served for at least one release cycle after the announcement, and a field on its way out keeps being accepted and returned during that time rather than refused. On the MCP surface the result carries a deprecation warning, and the removal ships with a version bump in the `serverInfo` a client reads at connect time. For an HTTP operation on its way out, the announcement also travels in the response itself: a `Deprecation` header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) from the day the removal is announced, and a `Sunset` header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) carrying the date it stops being served. Nothing is deprecated today, so no response carries either header yet, which is what the list at the top of this page says. The changelog entries for these surfaces are not written from memory. Each docs publish compares the contract fingerprints and the MCP tool names against the previous publish and adds a dated entry listing what was added, what changed shape, what was removed, and what was renamed. A rename is only reported as one when the change that made it says so; otherwise it shows up as a removal and an addition, which is what it looks like to your parser. Two mechanisms back this up on our side. Every `/v1` operation, and `/healthz` outside it, has a registered set of known readers, and a change that moves an operation's fingerprint fails our build until each reader has been re-confirmed against the new digest. And the fingerprints are published, so you can **pin them** and see a shape move in your own pipeline whether or not the notice reached you. That is why that section comes before this one. ## Where to go next > [card] [Changelog](/changelog) > > What changed, and the rule that decides whether an entry may appear there. > [card] [API reference](/api) > > The two HTTP surfaces and the boundary between them. > [card] [Rate limits](/api/rate-limits) > > The budget headers, and what to do when one runs out. > [card] [MCP surface](/mcp/overview) > > The tool surface, and the contract that keeps it stable. # Billing modes Source: https://docs.phoneuse.com/billing/modes The two ways a device is billed, the current rates, and how to choose between them. Each device is billed one of two ways: **monthly**, billed every 30 days, or **per minute**, paid from a prepaid balance. The choice is per device, not per org, so a fleet can mix both. A single device runs exactly one mode, and a monthly device is never metered. > [!NOTE] > > Rates on this page were checked on 2026-10-18. The canonical, always-current > price list is [phoneuse.com](https://phoneuse.com/#pricing); if the two ever > disagree, the site wins. ## Rates | Phone | `backendKind` | `fidelityTier` | Price | | - | - | - | - | | Cloud phone (monthly) | `adb_cloud` | `software` | $20, $24, $28 or $32 a month, by model | | Cloud phone, Real phone identity (monthly) | `adb_cloud` | `software` | \$39 a month | | Cloud phone (per minute) | `adb_cloud` | `software` | \$0.024 per minute | | Robot hand + iPhone | Not in the API | Not in the API | \$149 a month per robot, bought in the console | The per minute rate is for the phone on sale today. The console shows the exact rate, and the amount you would pay, before you start a phone. For a larger fleet, the Enterprise plan is priced on a call: [book a call with our team](https://cal.com/abdulla-ababakre-wubx6e/phoneuse?overlayCalendar=true). Both identifier columns are fields you can read off a device, in the `list_devices` and `get_device` response. `backendKind` names how a device is reached, but no device field says whether a cloud phone is monthly or per minute. You choose that when you get the phone. The console's **Billing** page lists your monthly orders and your per minute phones. `fidelityTier` answers a different question: how input reaches the screen. Fidelity describes the mechanism, while price tracks the phone behind it, so do not read one column off the other. See [Capabilities](/devices/capabilities) for both fields, and [Device tiers](/devices/tiers) for what the tier means. > [!NOTE] > > You can **buy a cloud phone on the spot** from **Add a phone** > (`/devices/add`) in the console. > See [Buy and drive a device](/guides/first-device). > [!WARNING] > > **The table above is the rate card, not the order form.** What you can buy > monthly is whatever `GET /v1/skus` lists: one entry per pair of sku and > billing mode that this deployment holds a configured price for, with a price > for each model. A pair with no price is **absent** from that list rather than > shown without a number. A model whose price cannot be read right now stays > in the list without a `price` or `quoteId`; it cannot be bought until a later > read shows its price. Per minute phones are listed separately, by > `GET /v1/minute/catalog`. Believe those two reads rather than this page. > [!NOTE] > > **Robot hand + iPhone: buy it in the console.** In **Add a phone**, choose > **Robot hand + iPhone**, pick how many you want and pay \$149 a month per robot > at checkout. We prepare it within **24 hours after payment**. Your purchase > receipt in the console shows the payment, not the delivery. The robot hand is > not part of the API, MCP or CLI today: `GET /v1/skus` lists Cloud phones only. ## Monthly A flat price for the device, billed every 30 days. There is no meter, no allowance to watch, and no overage: run the device all the time and the invoice reads the same. Each model has its own 30-day price, which `GET /v1/skus` carries on each model row. Choose this when a device is in steady use, or whenever you want the bill to be a constant rather than a variable. ## Per minute No fixed fee. You pay from a prepaid balance, and a phone is charged for each minute it is rented to you, from the moment it is ready until you return it or the balance runs out. Waiting for a phone to get ready is free. Starting a phone takes one page in the console (**Add a phone**, then **Per minute**), or one call to `POST /v1/minute/starts`: 1. You choose the phone and how many. 2. When a phone starts, 10 minutes of its rate is held from your balance for it. At $0.024 per minute that is $0.24 per phone. 3. If your balance already covers that, the phones start right away and you pay nothing at that moment. 4. If it does not, you pay one Stripe top-up for **only the missing amount**, at least \$5 and rounded up to the cent. The phones start once that payment is confirmed. 5. If you leave the Stripe page without paying, that top-up closes and nothing is charged. You can start again whenever you like. If a paid start cannot go ahead (the phone sold out, or the rate changed while you were paying), the money stays in your balance and the start says why. We email you about 10 minutes before your balance would run out, so you can add funds or return the phone. Unused balance is not refunded online; contact [abdulla@phoneuse.com](mailto:abdulla@phoneuse.com) with any question about it. Per minute phones are started and topped up by an org admin, signed in to the console. An API key cannot start one. Choose this for bursty or exploratory work, where a phone would otherwise sit unused for long stretches of the month. Return a phone when you are done with it: nothing pauses the charge while it is rented to you. ## Which one to pick The break-even is arithmetic: divide the 30-day price by the per minute rate and you have the number of rented minutes that costs the same as those 30 days. Below that, per minute is cheaper. Above it, monthly is, and the gap widens as usage grows. If you do not know your usage yet, start on per minute. It is the mode that punishes a wrong guess least. A phone does not move between the two modes, so when you know your usage, start a phone in the mode that fits. ## Agent steps are a separate axis Steps consumed by the agent tier are counted independently of the device's billing mode. A device on either mode can run agent tasks, and those steps are accounted for on their own axis. See [Metering units](/billing/units). Steps are included in the device price today, and no separate step rate is published. The reasonable use ceiling is not a billing threshold you can cross into an overage. It is enforced as a per run step budget, and a run that reaches its budget is refused its next frame rather than billed more. The default budget is **50 steps per run**, a deployment can set its own, and `maxSteps` on your request can only lower it. One org may have **4 agent runs** going at once by default. See [Agent tier](/agent/overview#budgets-live-on-the-control-plane) for how each ceiling is enforced. ## Accounts start paid There is no self serve free tier. An org is billed from first use, and there is no trial that silently converts. Payments are not refunded, and devices are not returned online. If you have a question about a device or a payment, contact support at [abdulla@phoneuse.com](mailto:abdulla@phoneuse.com) and we'll help. A Cloud phone keeps its paid period, and **Cancel order** on the console's Billing page stops the next charge. See [Buy and drive a device](/guides/first-device). If you would rather buy from a browser than from code, the console does exactly that, on this same surface and at these same rates. It is not a separate product, and this page applies to it. # Spending controls Source: https://docs.phoneuse.com/billing/spending-controls What bounds your bill today, including the control that does not exist. There is **no dollar limit you can set on this surface today**. You cannot set a limit that suspends a device or refuses the next one. That is worth stating first, because the alternative is a reader who assumes a cap is there. What follows is what actually bounds your bill. The honest answer to "how do I avoid a surprise bill" is a handful of existing limits rather than one switch. ## What bounds your bill today ### A per minute phone spends only what you paid in Per minute phones run on a prepaid balance (see [Billing modes](/billing/modes#per-minute)). A phone is charged each minute from that balance, so you cannot spend more than you have added: * When the balance runs out, the phone ends. Nothing is charged to a card behind your back. * We email you about 10 minutes before the balance would run out, so you can add funds or return the phone first. * A top-up you open and then leave on the Stripe page closes, and nothing is charged for it. * Returning a phone stops its charge. Nothing pauses the charge while a phone is rented to you, whether or not anything is using it, so return a phone when you are done with it. ### Monthly mode removes the variable A monthly device has no meter, no allowance and no overage: it is billed every 30 days, and running it all the time leaves the invoice the same. If predictability matters more than the arithmetic, that is the mode that gives it to you outright. **Cancel order** on the console's Billing page stops the next charge. See [Billing modes](/billing/modes#monthly). ### A lease frees a device you forgot A lease expires on its own after **10 minutes**, and it can be renewed, but no lease may live longer than **60 minutes** from when it was acquired. A client that crashed stops renewing, and the device frees itself within 10 minutes. A lease decides who may act on a device. It is not what you are charged for: a monthly phone costs the same whether or not it is leased, and a per minute phone is charged for the minutes it is rented to you. Lease-metered billing is not sold. See [Metering units](/billing/units#active-time). > [!WARNING] > > A loop that keeps taking the device never lets it go, so no other > organization can take it. People in your own org can still act on it beside > the loop. If you write a retry that re-acquires on > failure, give it a stopping condition and a ceiling on attempts. The same > goes for a loop that releases the device and then goes on acting on it: a > gesture on a device your organization no longer holds takes it again, and > each new lease starts its own fresh hour. ### A run carries its own budget `start_run` takes two limits and both of them are real ceilings, not hints: * `maxSteps`, the number of frames the run may consume. The default is 50 per run, and your value can only lower it. * `deadlineMs`, an absolute wall clock deadline, also capped by the deployment and by your lease's own expiry, whichever comes first. A run that reaches either limit is refused its next frame rather than billed further. See [Agent tier](/agent/overview#budgets-live-on-the-control-plane). ## Reading what you have spent Two reads, both on the hosted control plane, both needing only `devices:read`: * `GET /v1/usage` returns this billing period's settled usage per device: measured active time with corrections already applied, how many leases it came from, and the minutes already reported to billing. * `GET /v1/receipts` enumerates what your org has actually done, newest first, with keyset paging. Use `get_receipt` when you hold an `idempotencyKey` and need that one outcome back. Use `GET /v1/receipts` when the question is what happened at all. Two things to read carefully before you build a budget alarm on this. Only settled leases appear in usage, so a lease you are holding right now is not in those numbers: it is an account of what has finished, not a live meter. And `reportedMinutes` is absent until reporting has happened, which is not the same as zero. The console's **Billing** page, [console.phoneuse.com/usage](https://console.phoneuse.com/usage), shows your usage and your orders. ## What is on the way A dollar limit you set yourself, that suspends a device when it is reached, is a roadmap item, not a shipped feature. The limits above are the whole of what bounds your bill today. # Metering units Source: https://docs.phoneuse.com/billing/units What the control plane counts, and what it deliberately does not. Two things are counted, on two independent axes. Knowing which one your workload consumes is the difference between a predictable bill and a surprising one. > [!NOTE] > > This page describes **what is measured**, which is not the same as what you > are charged for. A monthly phone has no meter: it is a flat price. A per > minute phone is charged for each minute it is rented to you, from your > prepaid balance, not per lease. Billing by lease time is not sold today. > Rates live on [Billing modes](/billing/modes) and, canonically, on > [phoneuse.com](https://phoneuse.com/#pricing). ## Active time The unit for holding a device is **active time**: the span of the lease itself, from when your organization takes the device until you release it or its lease expires. Active time is the lease interval itself, integrated exactly: from when the device was taken until whichever comes first, the moment you released it or the moment its lease expired. ### What takes a device, and so starts the clock A lease starts in one of two ways, and they cost the same: * **You take it explicitly** with `acquire_device` (or `POST /v1/devices/{deviceId}/lease`). * **You act on a device your organization does not hold.** A gesture sent without a `leaseId` (`tap`, `swipe`, `long_press`, `type_text`, `press_key`, `open_app`, or `POST /v1/devices/{deviceId}/actions`) takes the device for you, and so does `start_run`. This needs a key with `devices:lease`; a key with only `devices:act` acts on a device your organization already holds and is otherwise refused `lease_required`, so it can never start a lease on its own. If the gesture that took the device then fails, the lease it took is given back before the error reaches you: a refused tap does not leave you paying for a device. Watching never takes a device. `screenshot` with no `leaseId`, `ui_snapshot`, `wake`, `list_devices`, `get_device` and `get_receipt` start nothing, and `ui_snapshot` and `wake` refuse with `lease_required` rather than take one. To give back a device a gesture took for you, you need its lease id, which an MCP gesture result does not carry. Call `acquire_device`: on a device your organization already holds it returns that same lease unchanged, and `release_device` takes its `leaseId`. (The REST gesture route returns the `leaseId` in its response.) Or let it expire, ten minutes after it was taken. Read that literally. A lease that is held but untouched still accrues active time. Nothing watches for inactivity and nothing pauses the clock on your behalf. The thing that bounds a lease you forget to release is its own expiry, not idleness, so the bound is the lease TTL rather than the moment you stopped working. **A lease expires 10 minutes after it is granted, and it can be renewed.** That number is what this whole page turns on, so here it is rather than three pages away. A lease accrues active time until it expires. A client that has crashed stops renewing, so a lease forgotten that way accrues at most 10 minutes and then expires on its own. A client that goes on renewing goes on accruing, up to the **60 minute** lifetime no lease may exceed, so 60 minutes and not 10 is the ceiling on any single lease. See [Billing modes](/billing/modes) for what you are actually charged and [Spending controls](/billing/spending-controls) for what bounds your bill. The practical consequence: **release a device when you are done with it.** Holding a lease open keeps active time counting until the lease ends, and keeps other organizations off the device. It does not lock out people in your own org: they act on the device under the same lease. Active time is measured in device minutes. ## Agent steps When a worker runs a task on your behalf, the unit is a **step**, and one step is one frame served to that worker. Steps are anchored to frames rather than to actions. A worker that takes one look and then performs five taps has consumed one step, not five. The sequence is issued by the control plane, not by the worker, so a worker cannot renumber or replay its way into a different count. A frame is counted before it is served. If the count cannot be recorded, the frame is not served, and you are not charged for it. The implication runs one way only: delivered implies billed, and billed does not imply delivered. See the list below. Every run carries a ceiling on the steps it may consume. Reaching that ceiling makes the next frame request fail; it does not end the run. The run stays alive against its own deadline, so a worker that has exhausted its budget should stop and report rather than keep trying. ## What is not counted Here is that list in full. Nothing in it adds to your bill. * **Actions themselves.** There is no per action rate on any tier. A tap, a swipe, a keystroke and an app launch all cost nothing beyond the active time the lease was already accruing. Holding a device for ten minutes costs the same whether you performed one gesture in it or two hundred. * **A failed action.** An action the device refused, or that failed on the way, is recorded so you can look it up, but it is not a billable event. Only an action the device actually committed counts as an actuation at all, and even then it is counted for the ledger rather than charged. * **A refused action.** An action rejected before it reached the device costs nothing, and there are several ways that happens: a capability the device does not have, a frame that went stale between your look and your tap, a lease you no longer hold. Nothing physical happened and nothing is billed. * **A retry under the same idempotency key.** The recorded outcome is replayed rather than re-executed, so a network retry never becomes a second charge. * **A frame request that fails before its step is written.** A `503` when metering is unavailable, a `503` when the frame carries no identity, and a `409` when the run is out of budget or parked for a person all cost nothing. The single exception is a connection you drop after the step was written but before you read the bytes, which costs that one step. * **Time outside a lease.** A device your organization does not hold accrues nothing. Listing devices, reading capabilities, looking up a receipt, and watching a screen are not metered, and none of them takes the device. * **Screenshots as a separate unit.** Driving a device yourself over MCP, a screenshot is an observation inside your lease, not a step. Steps are the agent tier's unit, counted when a frame is served to a *worker*. What is left is the short version: the control plane counts the time a device was yours, and the frames served to a worker acting on your behalf. Nothing else. What you pay is set by the device's billing mode, on [Billing modes](/billing/modes). ## The two axes are independent Driving a device yourself over MCP consumes active time. Handing a goal to a worker consumes active time **and** steps, because the worker still holds a lease on the device while it works. ## Reading your own usage Every action can carry an `idempotencyKey`, and the outcome recorded under that key is retrievable afterwards with `get_receipt`. A retry that reuses the same key replays the recorded outcome instead of executing again, so a network retry does not become a second charge. That is a point lookup, for a key you already hold. To ask the broader question, the hosted control plane has two reads, both needing only `devices:read`: | Read | Answers | | - | - | | `GET /v1/receipts` | What has my org actually done? Newest first, keyset paged. | | `GET /v1/usage` | What has this billing period consumed, per device? | Usage is derived from that same recorded ledger rather than from a separate counter, which is why what you are billed for and what you can look up are the same events. `GET /v1/usage` reads the per-lease rows billing itself reads, so it is not a second opinion about your consumption. It reports **settled** leases only. A lease you are holding at this moment has not ended, so it is not in the numbers yet, and this read is an account of what has finished rather than a live meter. See [Spending controls](/billing/spending-controls). # Changelog Source: https://docs.phoneuse.com/changelog What changed on the surfaces you install or call, and how to find out when a shape moves. The current CLI is published as [`@phoneuse/cli`](https://www.npmjs.com/package/@phoneuse/cli) and installs the `phoneuse` command. See [CLI installation](/cli/installation) for setup. Earlier CLI entries below describe the legacy `phonebase` package. This page is kept under one rule, and the rule explains why the page is short. **An entry appears here only when a published artifact can be pointed at and dated.** A version on npm is one of those. A decision, a commit message, or an internal note is not, because none of them tells you when a change reached you. Where we cannot date something honestly, the entry is left out rather than estimated. ## HTTP API and MCP tool surface The entries in this section are not written by hand. Each time this site is published, the contract fingerprints and the MCP tool names are compared with the previous publish, and anything that moved gets an entry dated to that publish: operations and tools added, operations whose shape changed, and operations and tools removed. A rename is listed as one only when the change that made it declared it; otherwise it appears as a removal and an addition. A publish that moved nothing adds nothing. Two kinds of change are invisible to that comparison, because neither is in a fingerprint: what a webhook delivery carries, and what travels inside a field the spec publishes as a bare object. Those are written by hand, in [Changes the fingerprints cannot see](#changes-the-fingerprints-cannot-see). ### HTTP API and MCP tools, 2026-10-30 * Changed. The shape of `GET /v1/robot-purchases` moved: fingerprint `a9ff104c09256e06` is now `53d0c837d50c981f`. * Changed. The shape of `GET /v1/robot-purchases/offer` moved: fingerprint `ed966b5e1ee5e7ab` is now `9e8c6533df6ab98d`. * Changed. The shape of `GET /v1/robot-purchases/{orderId}` moved: fingerprint `46e87887d181e35b` is now `413325151f8bbb1a`. ### HTTP API and MCP tools, 2026-10-27 * Changed. The shape of `GET /v1/robot-purchases` moved: fingerprint `956975d05be07633` is now `a9ff104c09256e06`. * Changed. The shape of `GET /v1/robot-purchases/offer` moved: fingerprint `876e81b461719bef` is now `ed966b5e1ee5e7ab`. * Changed. The shape of `GET /v1/robot-purchases/{orderId}` moved: fingerprint `c9eaf809700564f5` is now `46e87887d181e35b`. ### HTTP API and MCP tools, 2026-10-24 * Added. `GET /v1/robot-purchases`. ### HTTP API and MCP tools, 2026-10-24 * Changed. The shape of `GET /v1/app-store/catalog` moved: fingerprint `059be1add3981f04` is now `851666e01c93d00f`. ### HTTP API and MCP tools, 2026-10-23 * Added. `GET /v1/robot-purchases/offer`. * Added. `GET /v1/robot-purchases/{orderId}`. * Added. `POST /v1/robot-purchases/checkout`. ### HTTP API and MCP tools, 2026-10-22 * Changed. The shape of `POST /v1/devices/{deviceId}/live-session` moved: fingerprint `d9243c37044b00e5` is now `f85f6489dacba422`. * Changed. The shape of `POST /v1/devices/{deviceId}/stream` moved: fingerprint `8700197c34948cd9` is now `8e7f8edb9aa64d62`. ### HTTP API and MCP tools, 2026-10-21 * Removed. `GET /v1/fulfilments/{id}/estimate-history`. ### HTTP API and MCP tools, 2026-10-21 * Changed. The shape of `GET /healthz` moved: fingerprint `e0d9f484d7e9d1bc` is now `b7c40416340b9787`. * Changed. The shape of `GET /v1/skus` moved: fingerprint `80b0d07247063820` is now `aca9f5280483bfd5`. * Changed. The shape of `POST /v1/checkout-sessions` moved: fingerprint `cc2a94a399c24a4f` is now `b87ef4fccac917c3`. ### HTTP API and MCP tools, 2026-10-21 * Removed. `GET /gateway/v1/releases/current`. * Removed. `POST /gateway/enroll`. * Changed. The shape of `GET /healthz` moved: fingerprint `bfd106f158164b39` is now `e0d9f484d7e9d1bc`. ### HTTP API and MCP tools, 2026-10-21 * Removed. `GET /v1/workflow-run-requests/{clientRequestId}`. * Removed. `GET /v1/workflow-sources/{sourceRunId}`. * Removed. `GET /v1/workflows/{workflowId}/versions`. * Removed. `GET /v1/workflows/{workflowId}/versions/{version}`. * Removed. `POST /v1/console/events`. * Removed. `POST /v1/devices/take`. * Removed. `POST /v1/workflows/{workflowId}/versions`. * Removed. `POST /v1/workflows/{workflowId}/versions/{version}/runs`. * Changed. The shape of `GET /v1/runs` moved: fingerprint `85497e408d6c3f06` is now `7360b1208a9708dd`. * Changed. The shape of `GET /v1/webhooks` moved: fingerprint `780240aa23c16ec3` is now `5831973a17c4a861`. * Changed. The shape of `GET /v1/webhooks/{webhookId}/deliveries` moved: fingerprint `207d21ac32cc6cd7` is now `c19857223d1c8e93`. * Changed. The shape of `PATCH /v1/webhooks/{webhookId}` moved: fingerprint `a839d484f0071c42` is now `edfc2f0da5a5fba9`. * Changed. The shape of `POST /v1/webhooks` moved: fingerprint `de12a70f4a40c26b` is now `9cd730c7d646e723`. * Changed. The shape of `POST /v1/webhooks/{webhookId}/rotate` moved: fingerprint `352c7df363c16e1a` is now `be7fadb6caf3dbe8`. ### HTTP API and MCP tools, 2026-10-21 * Removed. `POST /v1/devices/{deviceId}/stop`. Reason given: Stopping a robot arm is retired with robot-driven phones; no device on sale has an arm to stop. No replacement endpoint is provided. * Removed. `POST /webhooks/livekit`. Reason given: Robot arm live video and its media server are retired; this delivery address was only ever called by that media server. No replacement endpoint is provided. * Changed. The shape of `GET /healthz` moved: fingerprint `0a45b8af17deb588` is now `bfd106f158164b39`. * Changed. The shape of `POST /v1/devices/{deviceId}/stream` moved: fingerprint `e02f68d127de9afa` is now `8700197c34948cd9`. ### HTTP API and MCP tools, 2026-10-18 * Added. `GET /v1/device-thumbnails`. ### HTTP API and MCP tools, 2026-10-17 * Changed. The shape of `GET /v1/minute/requests/{requestId}` moved: fingerprint `36b72d711471be00` is now `f6225d4675bb4dc9`. * Changed. The shape of `GET /v1/minute/topups/{id}` moved: fingerprint `d38545b23be3b63f` is now `c9bdcaa3e0ffd443`. * Changed. The shape of `POST /v1/minute/topups` moved: fingerprint `d378b7c71a7b7ec1` is now `f627931d66042f21`. * Changed. The shape of `POST /v1/minute/topups/{id}/abandon` moved: fingerprint `4883ee12442286e1` is now `17487d781fc372af`. * Added. `GET /v1/minute/starts/{id}`. * Added. `POST /v1/minute/starts`. ### HTTP API and MCP tools, 2026-10-17 * Changed. The shape of `GET /v1/minute/requests/{requestId}` moved: fingerprint `bec680ea726ac157` is now `36b72d711471be00`. * Changed. The shape of `GET /v1/minute/topups/{id}` moved: fingerprint `e78eff94fd71d8fd` is now `d38545b23be3b63f`. * Changed. The shape of `POST /v1/minute/topups` moved: fingerprint `a3cf4c414f20e323` is now `d378b7c71a7b7ec1`. * Added. `POST /v1/minute/topups/{id}/abandon`. ### HTTP API and MCP tools, 2026-10-15 * Changed. The shape of `GET /v1/devices/{deviceId}/screenshot` moved: fingerprint `d71dcc3cd9616837` is now `491ea7b830867534`. * Changed. The shape of `GET /v1/runs` moved: fingerprint `b17add3a9ada7535` is now `85497e408d6c3f06`. * Changed. The shape of `GET /v1/runs/{runId}` moved: fingerprint `400678354d76997a` is now `082c2891c52dbfcb`. * Changed. The shape of `GET /v1/workflow-run-requests/{clientRequestId}` moved: fingerprint `34a47f4f6a680948` is now `19a0225926b8e539`. * Changed. The shape of `GET /vrx/{runToken}/v1/devices/{deviceId}/screenshot` moved: fingerprint `42892550a5111203` is now `d0bf310fc272b0f6`. * Changed. The shape of `POST /v1/runs` moved: fingerprint `cf40cd9d2e724804` is now `28053425dd279c59`. * Changed. The shape of `POST /v1/runs/{runId}/cancel` moved: fingerprint `da51a227fa06149a` is now `a0c2b06445081a0a`. * Changed. The shape of `POST /v1/runs/{runId}/pause` moved: fingerprint `cab6864a03998886` is now `40c66c105c500e94`. * Changed. The shape of `POST /v1/runs/{runId}/resume` moved: fingerprint `26cf9164dc358bb9` is now `4a8f58caea3e130b`. * Changed. The shape of `POST /v1/workflows/{workflowId}/versions/{version}/runs` moved: fingerprint `25855626a40c1586` is now `e369d2cfcd77b1fd`. ### HTTP API and MCP tools, 2026-10-12 * Changed. The shape of `GET /v1/workflow-run-requests/{clientRequestId}` moved: fingerprint `ff59ae3bff717f8d` is now `34a47f4f6a680948`. * Changed. The shape of `GET /v1/workflow-sources/{sourceRunId}` moved: fingerprint `b47eaf6dc5d4a69e` is now `4ca60db8e318feb5`. * Changed. The shape of `GET /v1/workflows/{workflowId}/versions` moved: fingerprint `784ad0be224b04d1` is now `223d212171f1ebdf`. * Changed. The shape of `GET /v1/workflows/{workflowId}/versions/{version}` moved: fingerprint `e783faa95014da80` is now `5025b1943ba624fd`. * Changed. The shape of `POST /v1/workflows/{workflowId}/versions` moved: fingerprint `8996215dc67337d0` is now `db891e3e6c6467e3`. * Changed. The shape of `POST /v1/workflows/{workflowId}/versions/{version}/runs` moved: fingerprint `fd8e0b748fe71444` is now `25855626a40c1586`. ### HTTP API and MCP tools, 2026-10-12 * Changed. The shape of `GET /v1/devices/{deviceId}/unclear-actions` moved: fingerprint `8a35ad7af2559740` is now `f1c355ca960c9809`. ### HTTP API and MCP tools, 2026-10-12 * Added. `GET /v1/app-store/queue`. * Added. `GET /v1/app-store/queue/by-request/{requestKey}`. * Added. `POST /v1/app-store/installations/{installationId}/skip`. * Added. `POST /v1/app-store/queue`. * Added. `POST /v1/app-store/queue/pause`. * Added. `POST /v1/app-store/queue/{entryId}/remove`. ### HTTP API and MCP tools, 2026-10-12 * Added. `GET /v1/devices/{deviceId}/unclear-actions`. * Added. `POST /v1/devices/{deviceId}/unclear-actions/confirm`. ### HTTP API and MCP tools, 2026-10-11 * Changed. The shape of `GET /healthz` moved: fingerprint `67b4fa8fca0dd4b8` is now `0a45b8af17deb588`. * Changed. The shape of `GET /v1/app-store/catalog` moved: fingerprint `c0cd1ff8d56cb9f2` is now `059be1add3981f04`. * Changed. The shape of `GET /v1/devices` moved: fingerprint `be2b3ac97dac389b` is now `60c837de4fbf289b`. * Changed. The shape of `GET /v1/devices/{deviceId}` moved: fingerprint `2bfb43d9440c26f0` is now `9da70ff1a88ca98a`. * Changed. The shape of `PATCH /v1/devices/{deviceId}` moved: fingerprint `e0c1443bb6c46abf` is now `7b2333283c45b9c0`. * Changed. The shape of `POST /v1/app-store/installations` moved: fingerprint `4c5b782d15bbabb1` is now `800317318afe2315`. * Added. `POST /v1/app-store/installations/{installationId}/recheck`. ### HTTP API and MCP tools, 2026-10-11 * Changed. The shape of `GET /v1/fulfilments` moved: fingerprint `2e11998f32a3073a` is now `d4ba17cae01ba5f9`. * Changed. The shape of `GET /v1/minute/orders` moved: fingerprint `85490f6b41b6c23d` is now `af9a6b56729f05a2`. * Changed. The shape of `GET /v1/minute/orders/{id}` moved: fingerprint `d651e388e0b6a135` is now `7fcc1850c7cd24b1`. * Changed. The shape of `GET /v1/minute/requests/{requestId}` moved: fingerprint `b6767fb296dc7286` is now `bec680ea726ac157`. * Changed. The shape of `POST /v1/minute/orders` moved: fingerprint `a07127aadb9c0392` is now `4b22e3b4f58050a7`. * Changed. The shape of `POST /v1/minute/orders/{id}/cancel` moved: fingerprint `9d11dbe295d7ef7c` is now `0273e3a82cc8a394`. * Changed. The shape of `POST /v1/minute/rentals/{deviceId}/resume` moved: fingerprint `848cf42695f7303e` is now `3674e3bf2b26f715`. * Added. `GET /v1/orders/{orderId}/payment-status`. * Added. `POST /v1/checkout-sessions/{orderId}/confirm`. ### HTTP API and MCP tools, 2026-10-11 * Removed. `GET /v1/copilot-allowance`. Reason given: The copilot token allowance is retired; it was never billed, and copilot chat is unaffected. No replacement endpoint is provided. ### HTTP API and MCP tools, 2026-10-09 * Changed. The shape of `GET /v1/devices` moved: fingerprint `9dd9274d610a179b` is now `be2b3ac97dac389b`. * Changed. The shape of `GET /v1/devices/{deviceId}` moved: fingerprint `d05d1b635721a9c3` is now `2bfb43d9440c26f0`. * Changed. The shape of `PATCH /v1/devices/{deviceId}` moved: fingerprint `f972b9748d24953c` is now `e0c1443bb6c46abf`. * Changed. The shape of `POST /v1/devices/{deviceId}/actions` moved: fingerprint `9cdfd8361653e621` is now `bfde116ebadb57ec`. ### HTTP API and MCP tools, 2026-10-09 * Changed. The shape of `GET /v1/devices/{deviceId}/image-maintenance` moved: fingerprint `d145daa753e42331` is now `f29fd4c18d7f23f1`. * Added. `POST /v1/devices/{deviceId}/image-maintenance/cancel`. * Added. `POST /v1/devices/{deviceId}/image-maintenance/fault`. * Added. `POST /v1/devices/{deviceId}/image-maintenance/recheck`. ### HTTP API and MCP tools, 2026-10-09 * Changed. The shape of `GET /v1/minute/catalog` moved: fingerprint `e7a46d916ad24f82` is now `1c97583788fb1041`. * Changed. The shape of `GET /v1/minute/orders` moved: fingerprint `4fc13777d3032d09` is now `85490f6b41b6c23d`. * Changed. The shape of `GET /v1/minute/orders/{id}` moved: fingerprint `31f3d48cb95bb800` is now `d651e388e0b6a135`. * Changed. The shape of `GET /v1/minute/requests/{requestId}` moved: fingerprint `4d73bc1e8a1ebe47` is now `b6767fb296dc7286`. * Changed. The shape of `POST /v1/minute/orders` moved: fingerprint `bcdc029a1e64bb02` is now `a07127aadb9c0392`. * Changed. The shape of `POST /v1/minute/orders/{id}/cancel` moved: fingerprint `a5a658c2544be568` is now `9d11dbe295d7ef7c`. * Changed. The shape of `POST /v1/minute/rentals/{deviceId}/resume` moved: fingerprint `4af994301b778ed3` is now `848cf42695f7303e`. ### HTTP API and MCP tools, 2026-10-08 * Added. `GET /v1/devices/{deviceId}/image-maintenance`. ### HTTP API and MCP tools, 2026-10-08 * Changed. The shape of `GET /v1/minute/catalog` moved: fingerprint `0b55c3a29ec7b8ed` is now `e7a46d916ad24f82`. * Changed. The shape of `GET /v1/minute/rentals/{deviceId}` moved: fingerprint `82b559715e0937ea` is now `04eff0e27dc17f51`. * Changed. The shape of `GET /v1/minute/requests/{requestId}` moved: fingerprint `2174b8643b08c9b0` is now `4d73bc1e8a1ebe47`. * Changed. The shape of `GET /v1/minute/topups/{id}` moved: fingerprint `acce3eb3d0bca2d6` is now `e78eff94fd71d8fd`. * Changed. The shape of `GET /v1/minute/wallet` moved: fingerprint `bc614f1df1bd1c7d` is now `49d868c6d52fa7ce`. * Changed. The shape of `POST /v1/minute/rentals/{deviceId}/return` moved: fingerprint `eb4d87f906d1261f` is now `ec525ba933da2968`. * Changed. The shape of `POST /v1/minute/topup-quotes` moved: fingerprint `c9cf8bed72c43a49` is now `41af3d66ccf1f363`. * Changed. The shape of `POST /v1/minute/topups` moved: fingerprint `41f77f790a005fa7` is now `a3cf4c414f20e323`. ### HTTP API and MCP tools, 2026-10-08 * Changed. The shape of `GET /v1/copilot/threads/{id}` moved: fingerprint `6c02e3a4fc71f80d` is now `67530bdbe135af31`. * Changed. The shape of `GET /v1/runs` moved: fingerprint `d32a6d4b1018727c` is now `b17add3a9ada7535`. * Changed. The shape of `GET /v1/runs/{runId}` moved: fingerprint `7254348bcdf878b0` is now `400678354d76997a`. * Changed. The shape of `POST /v1/copilot` moved: fingerprint `ad516a6f7b55c575` is now `b561eb7af84d588d`. * Changed. The shape of `POST /v1/copilot/commands` moved: fingerprint `96c0c08ca839dea1` is now `258e9e5080645946`. * Changed. The shape of `POST /v1/runs` moved: fingerprint `bae32ebbe9ac7cf0` is now `cf40cd9d2e724804`. * Changed. The shape of `POST /v1/runs/{runId}/cancel` moved: fingerprint `16159beedc679d57` is now `da51a227fa06149a`. * Changed. The shape of `POST /v1/runs/{runId}/pause` moved: fingerprint `b2cc5f5a263b0f31` is now `cab6864a03998886`. * Changed. The shape of `POST /v1/runs/{runId}/resume` moved: fingerprint `e59994e31ac63c4c` is now `26cf9164dc358bb9`. * Added. `GET /v1/workflow-run-requests/{clientRequestId}`. * Added. `GET /v1/workflow-sources/{sourceRunId}`. * Added. `GET /v1/workflows/{workflowId}/versions`. * Added. `GET /v1/workflows/{workflowId}/versions/{version}`. * Added. `POST /v1/workflows/{workflowId}/versions`. * Added. `POST /v1/workflows/{workflowId}/versions/{version}/runs`. ### HTTP API and MCP tools, 2026-10-08 * Changed. The shape of `GET /v1/minute/rentals/{deviceId}` moved: fingerprint `e47dfc21e8dec257` is now `82b559715e0937ea`. * Changed. The shape of `GET /v1/minute/requests/{requestId}` moved: fingerprint `5b484c59d55ec7fb` is now `2174b8643b08c9b0`. * Changed. The shape of `GET /v1/notifications` moved: fingerprint `8d48f3a2a5672e32` is now `66e51a4fa4129bb8`. * Changed. The shape of `POST /v1/minute/rentals/{deviceId}/return` moved: fingerprint `f03a3a909bd98b89` is now `eb4d87f906d1261f`. * Added. `GET /v1/devices/{deviceId}/proxy`. * Added. `GET /v1/proxies`. * Added. `GET /v1/proxies/{proxyId}`. * Added. `GET /v1/proxy-operations`. * Added. `GET /v1/proxy-operations/{operationId}`. * Added. `GET /v1/proxy-orders`. * Added. `GET /v1/proxy-orders/{orderId}`. * Added. `GET /v1/proxy-products`. * Added. `GET /v1/proxy-products/{productId}`. * Added. `GET /v1/proxy-purchase-quotes/{quoteId}`. * Added. `GET /v1/proxy-purchases/{purchaseId}`. * Added. `GET /v1/proxy-quotes/{quoteId}`. * Added. `PATCH /v1/proxies/{proxyId}`. * Added. `POST /v1/proxies/{proxyId}/archive`. * Added. `POST /v1/proxy-operations`. * Added. `POST /v1/proxy-orders`. * Added. `POST /v1/proxy-orders/{orderId}/cancel`. * Added. `POST /v1/proxy-orders/{orderId}/checkout`. * Added. `POST /v1/proxy-purchase-quotes`. * Added. `POST /v1/proxy-purchases`. * Added. `POST /v1/proxy-purchases/{purchaseId}/cancel`. * Added. `POST /v1/proxy-quotes`. ### HTTP API and MCP tools, 2026-10-08 * Added. `GET /v1/minute/cases`. * Added. `GET /v1/minute/cases/{id}`. * Added. `GET /v1/minute/catalog`. * Added. `GET /v1/minute/orders`. * Added. `GET /v1/minute/orders/{id}`. * Added. `GET /v1/minute/refunds`. * Added. `GET /v1/minute/refunds/{id}`. * Added. `GET /v1/minute/rentals/{deviceId}`. * Added. `GET /v1/minute/requests/{requestId}`. * Added. `GET /v1/minute/topups/{id}`. * Added. `GET /v1/minute/wallet`. * Added. `POST /v1/minute/cases`. * Added. `POST /v1/minute/orders`. * Added. `POST /v1/minute/orders/{id}/cancel`. * Added. `POST /v1/minute/refunds`. * Added. `POST /v1/minute/rentals/{deviceId}/resume`. * Added. `POST /v1/minute/rentals/{deviceId}/return`. * Added. `POST /v1/minute/topup-quotes`. * Added. `POST /v1/minute/topups`. ### HTTP API and MCP tools, 2026-10-07 * Changed. The shape of `GET /v1/fulfilments` moved: fingerprint `a57e156f5305bafd` is now `2e11998f32a3073a`. * Changed. The shape of `GET /v1/skus` moved: fingerprint `46d804dcf5b07374` is now `80b0d07247063820`. * Changed. The shape of `POST /v1/checkout-sessions` moved: fingerprint `465fb159ff3a2633` is now `cc2a94a399c24a4f`. ### HTTP API and MCP tools, 2026-10-07 * Changed. The shape of `POST /v1/checkout-sessions` moved: fingerprint `d8795a0afef8856c` is now `465fb159ff3a2633`. ### HTTP API and MCP tools, 2026-10-06 * Removed. `GET /v1/devices/{deviceId}/proxy`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `GET /v1/proxies`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `GET /v1/proxies/{proxyId}`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `GET /v1/proxy-operations`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `GET /v1/proxy-operations/{operationId}`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `GET /v1/proxy-orders`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `GET /v1/proxy-orders/{orderId}`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `GET /v1/proxy-products`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `GET /v1/proxy-products/{productId}`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `GET /v1/proxy-quotes/{quoteId}`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `PATCH /v1/proxies/{proxyId}`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `POST /v1/proxies/{proxyId}/archive`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `POST /v1/proxy-operations`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `POST /v1/proxy-orders`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `POST /v1/proxy-orders/{orderId}/cancel`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `POST /v1/proxy-orders/{orderId}/checkout`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. * Removed. `POST /v1/proxy-quotes`. Reason given: US fixed IP and managed proxy services are permanently retired; no replacement endpoint is provided. ### HTTP API and MCP tools, 2026-10-05 * Removed. `DELETE /v1/app-library/versions/{versionId}`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-library/apps`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-library/apps/{appId}`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-library/apps/{appId}/versions`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-library/deletions/{deletionId}`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-library/jobs`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-library/jobs/{jobId}`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-library/jobs/{jobId}/targets`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-library/jobs/{jobId}/targets/{targetId}/attempts`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-library/policy`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-library/previews/{previewId}`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-library/previews/{previewId}/targets`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-library/uploads/{uploadId}`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-library/uploads/{uploadId}/parts`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-library/versions/{versionId}`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `GET /v1/app-packages/{uploadId}`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `PATCH /v1/app-library/apps/{appId}`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `POST /v1/app-library/jobs`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `POST /v1/app-library/jobs/{jobId}/retry`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `POST /v1/app-library/jobs/{jobId}/stop`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `POST /v1/app-library/previews`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `POST /v1/app-library/uploads`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `POST /v1/app-library/uploads/{uploadId}/abort`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `POST /v1/app-library/uploads/{uploadId}/complete`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `POST /v1/app-library/uploads/{uploadId}/parts/{partNumber}/url`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `POST /v1/app-library/uploads/{uploadId}/publish`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `POST /v1/app-library/versions/{versionId}/archive`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `POST /v1/app-library/versions/{versionId}/restore`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `POST /v1/app-packages`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. `PUT /v1/app-packages/{uploadId}/content`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `create_app_job`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `get_app_job`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `get_app_preview`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `get_app_upload`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `install_app`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `list_app_job_targets`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `list_app_jobs`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `list_app_preview_targets`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `list_app_versions`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `list_apps`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `preview_app_operation`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `publish_app_upload`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `reserve_app_upload`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `retry_app_targets`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Removed. MCP tool `stop_app_targets`. Reason given: Custom APK uploads and their library operations are permanently retired; managed catalog installations are a separate feature. * Changed. The shape of `GET /v1/app-library/inventory` moved: fingerprint `c633e579b227a186` is now `4359ebe9cbff82fd`. * Changed. The shape of `GET /v1/app-library/inventory/refreshes/{refreshId}/results` moved: fingerprint `ce91ec9cb141dccc` is now `1e3574cb9795908c`. * Changed. The shape of `POST /v1/app-library/inventory/refreshes` moved: fingerprint `235720f6ae50d088` is now `6cc80ea7254fb558`. * Added. `GET /v1/app-store/catalog`. * Added. `GET /v1/app-store/installations`. * Added. `GET /v1/app-store/installations/by-request/{requestKey}`. * Added. `GET /v1/app-store/installations/{installationId}`. * Added. `POST /v1/app-store/installations`. ### HTTP API and MCP tools, 2026-10-05 * Removed. `DELETE /v1/copilot/automation-defaults/{id}`. * Removed. `DELETE /v1/files/{fileId}`. * Removed. `GET /v1/copilot/automation-defaults`. * Removed. `GET /v1/devices/{deviceId}/file-transfers`. * Removed. `GET /v1/devices/{deviceId}/file-transfers/{transferId}`. * Removed. `GET /v1/files`. * Removed. `GET /v1/phone-number-eligibility`. * Removed. `PATCH /v1/copilot/automation-defaults`. * Removed. `POST /v1/devices/{deviceId}/file-transfers`. * Removed. `POST /v1/file-transfers`. * Removed. `POST /v1/files`. * Removed. `POST /v1/files/{fileId}/complete`. * Removed. `POST /v1/files/{fileId}/parts/{partNumber}/url`. ### HTTP API and MCP tools, 2026-10-05 * Changed. The shape of `GET /v1/fulfilments` moved: fingerprint `9d87ccbf0d01318a` is now `a57e156f5305bafd`. * Changed. The shape of `GET /v1/skus` moved: fingerprint `b32659727f5c5dd7` is now `46d804dcf5b07374`. * Changed. The shape of `POST /v1/checkout-sessions` moved: fingerprint `9f3b7af5b2a77606` is now `d8795a0afef8856c`. ### HTTP API and MCP tools, 2026-10-05 * Changed. The shape of `GET /v1/fulfilments` moved: fingerprint `30f1e1b79864a9a5` is now `9d87ccbf0d01318a`. ### HTTP API and MCP tools, 2026-10-04 * Added. `POST /v1/file-transfers`. ### HTTP API and MCP tools, 2026-10-04 * Changed. The shape of `POST /v1/files` moved: fingerprint `8ef0d6063aaa567e` is now `2370d3fa472ced4a`. * Added. `DELETE /v1/files/{fileId}`. * Added. `GET /v1/files`. ### HTTP API and MCP tools, 2026-10-04 * Changed. The shape of `GET /v1/app-library/apps` moved: fingerprint `620dda44e0682952` is now `66f3800649843a45`. * Changed. The shape of `GET /v1/app-library/apps/{appId}` moved: fingerprint `090fba60dba2ddbc` is now `86e6a26c924568b3`. * Changed. The shape of `PATCH /v1/app-library/apps/{appId}` moved: fingerprint `1f03b3f6ef0b745c` is now `efc6d84b0445a9f8`. * Changed. The shape of `POST /v1/app-library/uploads/{uploadId}/publish` moved: fingerprint `4e634fbfb2baaa5c` is now `c9a0739e75f095fb`. ### HTTP API and MCP tools, 2026-10-04 * Changed. The shape of `GET /v1/fulfilments` moved: fingerprint `b6a912c5b62a24f7` is now `30f1e1b79864a9a5`. * Changed. The shape of `POST /v1/checkout-sessions` moved: fingerprint `1f23e1ffdd2a8b2e` is now `9f3b7af5b2a77606`. ### HTTP API and MCP tools, 2026-10-04 * Changed. The shape of `POST /v1/checkout-sessions` moved: fingerprint `c527f120581abe92` is now `1f23e1ffdd2a8b2e`. ### HTTP API and MCP tools, 2026-10-04 * Changed. The shape of `GET /v1/copilot/threads/{id}` moved: fingerprint `acbdf6d484dc6f9b` is now `6c02e3a4fc71f80d`. ### HTTP API and MCP tools, 2026-10-04 * Changed. The shape of `POST /v1/billing/portal-sessions` moved: fingerprint `292ec8cc7de85905` is now `ee1225818fdeab1a`. ### HTTP API and MCP tools, 2026-10-03 * Added. `GET /v1/devices/{deviceId}/file-transfers`. * Added. `GET /v1/devices/{deviceId}/file-transfers/{transferId}`. * Added. `POST /v1/devices/{deviceId}/file-transfers`. ### HTTP API and MCP tools, 2026-10-03 * Added. `POST /v1/files`. * Added. `POST /v1/files/{fileId}/complete`. * Added. `POST /v1/files/{fileId}/parts/{partNumber}/url`. ### HTTP API and MCP tools, 2026-10-03 * Changed. The shape of `GET /v1/skus` moved: fingerprint `baa98a4e17a172f4` is now `b32659727f5c5dd7`. ### HTTP API and MCP tools, 2026-10-03 * Changed. The shape of `DELETE /v1/api-keys/current` moved: fingerprint `ede45c8efef4e7da` is now `2568cf855fa0d4ec`. * Changed. The shape of `DELETE /v1/api-keys/{id}` moved: fingerprint `fd0e24ddda430e6a` is now `127026348c43481c`. * Changed. The shape of `DELETE /v1/copilot/automation-defaults/{id}` moved: fingerprint `dd7f69104957de09` is now `5fd9022d25f82e1c`. * Changed. The shape of `DELETE /v1/copilot/threads/{id}` moved: fingerprint `bc66b4f578a235a1` is now `4645c1e5b0f85ec1`. * Changed. The shape of `DELETE /v1/devices/{deviceId}/lease` moved: fingerprint `e85e64d3c2bcaef8` is now `9415a8406f875734`. * Changed. The shape of `DELETE /v1/webhooks/{webhookId}` moved: fingerprint `8b698553403c99df` is now `313a2e7b3d95ce82`. * Changed. The shape of `GET /v1/admission` moved: fingerprint `f7aa822968eb07dc` is now `5512c92b2a3cd6e5`. * Changed. The shape of `GET /v1/api-keys` moved: fingerprint `4c5d4ca3c65cf901` is now `21bf78f8286896d3`. * Changed. The shape of `GET /v1/api-keys/current` moved: fingerprint `46aa96f91f96c1a2` is now `5b1b5e27cab09e15`. * Changed. The shape of `GET /v1/app-packages/{uploadId}` moved: fingerprint `cc9dc1804b465221` is now `47f989fd27bb1b2e`. * Changed. The shape of `GET /v1/billing/upcoming` moved: fingerprint `b5a016d76ab2c492` is now `1e318ceb42b26d1e`. * Changed. The shape of `GET /v1/cli-sessions/{userCode}` moved: fingerprint `56808ddb51155b2e` is now `4ca184793879254a`. * Changed. The shape of `GET /v1/copilot/automation-defaults` moved: fingerprint `f6454dc5e0480da4` is now `961fd59b8dac48f0`. * Changed. The shape of `GET /v1/copilot/threads` moved: fingerprint `45d0ef6a595c3615` is now `6220d1ffe6c7faa0`. * Changed. The shape of `GET /v1/copilot/threads/{id}` moved: fingerprint `17710206d662bcb5` is now `acbdf6d484dc6f9b`. * Changed. The shape of `GET /v1/copilot/threads/{id}/stream` moved: fingerprint `bffb249526f4e3a7` is now `7a3331f9363a4aed`. * Changed. The shape of `GET /v1/devices` moved: fingerprint `e255f756070f1804` is now `9dd9274d610a179b`. * Changed. The shape of `GET /v1/devices/{deviceId}` moved: fingerprint `e90ecbcdc520a5cf` is now `d05d1b635721a9c3`. * Changed. The shape of `GET /v1/devices/{deviceId}/driving` moved: fingerprint `b2ae6fb0bca7a922` is now `15df33f94a38b558`. * Changed. The shape of `GET /v1/devices/{deviceId}/screenshot` moved: fingerprint `5496d77578e3d599` is now `d71dcc3cd9616837`. * Changed. The shape of `GET /v1/frames/{frameId}` moved: fingerprint `3af35158b3c904e9` is now `5df720f291c770f6`. * Changed. The shape of `GET /v1/fulfilments/{id}/estimate-history` moved: fingerprint `acf1fbe8fe84fc0d` is now `91a8db1d9100f24f`. * Changed. The shape of `GET /v1/fulfilments/{id}/renewal-status` moved: fingerprint `5142eb3ef4015c6b` is now `a69b81bf56c71b0f`. * Changed. The shape of `GET /v1/leases` moved: fingerprint `c9b1159a47f9ad61` is now `07c9b1d810172174`. * Changed. The shape of `GET /v1/me/notification-preferences` moved: fingerprint `4ddfd8d29eef3a80` is now `5961954260c353f5`. * Changed. The shape of `GET /v1/notifications` moved: fingerprint `67fd9cdfdb93647a` is now `8d48f3a2a5672e32`. * Changed. The shape of `GET /v1/phone-number-eligibility` moved: fingerprint `0f39bcb06cf42c91` is now `abd0507d8c967f89`. * Changed. The shape of `GET /v1/receipts` moved: fingerprint `2a0da7e3cbd6f442` is now `9fd9b9a8bd80addc`. * Changed. The shape of `GET /v1/receipts/{idempotencyKey}` moved: fingerprint `c1e21559cc98cba0` is now `27482c67e7c5d689`. * Changed. The shape of `GET /v1/runs` moved: fingerprint `6297b21fde2babd0` is now `d32a6d4b1018727c`. * Changed. The shape of `GET /v1/runs/{runId}` moved: fingerprint `3f6fc660233e2689` is now `7254348bcdf878b0`. * Changed. The shape of `GET /v1/time` moved: fingerprint `16fc873d71ab267b` is now `5de249af9a09c006`. * Changed. The shape of `GET /v1/usage` moved: fingerprint `1cc7f97fced7536d` is now `fe7a524f89072bad`. * Changed. The shape of `GET /v1/webhooks` moved: fingerprint `adfcb421a995cfb8` is now `780240aa23c16ec3`. * Changed. The shape of `GET /v1/webhooks/{webhookId}/deliveries` moved: fingerprint `c7f46eea421acddc` is now `207d21ac32cc6cd7`. * Changed. The shape of `PATCH /v1/api-keys/{id}` moved: fingerprint `06382650a9541099` is now `17f7f3b85a7c00a1`. * Changed. The shape of `PATCH /v1/copilot/automation-defaults` moved: fingerprint `9a56a282f62efbf0` is now `db5d2d57dcef7fbc`. * Changed. The shape of `PATCH /v1/copilot/threads/{id}` moved: fingerprint `97d0ce2c56c6ce0a` is now `3786df61af85bfa0`. * Changed. The shape of `PATCH /v1/devices/{deviceId}` moved: fingerprint `198b3990f7046451` is now `f972b9748d24953c`. * Changed. The shape of `PATCH /v1/devices/{deviceId}/lease` moved: fingerprint `5766c8ed776d284a` is now `a91a9ffd0c4a612a`. * Changed. The shape of `PATCH /v1/me/notification-preferences` moved: fingerprint `b4deff15f148860e` is now `222b0242db648b02`. * Changed. The shape of `PATCH /v1/webhooks/{webhookId}` moved: fingerprint `df102f51aa147233` is now `a839d484f0071c42`. * Changed. The shape of `POST /mcp` moved: fingerprint `63b42f4bccf1b88a` is now `a8ce2dc84704b2d3`. * Changed. The shape of `POST /v1/api-keys` moved: fingerprint `dd1d0a972386f970` is now `49849c9f6bd44c94`. * Changed. The shape of `POST /v1/api-keys/{id}/rotate` moved: fingerprint `63e79021e92b55e9` is now `543880d244c7861f`. * Changed. The shape of `POST /v1/app-packages` moved: fingerprint `cbc119691f064c3e` is now `734fd0a0b96124ca`. * Changed. The shape of `POST /v1/billing/portal-sessions` moved: fingerprint `ee662674c45fd9fa` is now `292ec8cc7de85905`. * Changed. The shape of `POST /v1/checkout-sessions` moved: fingerprint `f0581ce04ca26cf5` is now `c527f120581abe92`. * Changed. The shape of `POST /v1/cli-sessions` moved: fingerprint `2420d38b679208bc` is now `49466938747586a9`. * Changed. The shape of `POST /v1/cli-sessions/token` moved: fingerprint `e4869828189519fa` is now `303ab0e1674a3d47`. * Changed. The shape of `POST /v1/cli-sessions/{userCode}/approve` moved: fingerprint `16a2a44744a517db` is now `29c171e90398bebc`. * Changed. The shape of `POST /v1/cli-sessions/{userCode}/deny` moved: fingerprint `31110ca3f796d056` is now `d65d7fd46b33c97e`. * Changed. The shape of `POST /v1/console/events` moved: fingerprint `e292e612c88d966f` is now `3ce7102c86b80c82`. * Changed. The shape of `POST /v1/copilot` moved: fingerprint `acff7f5148ca1fc9` is now `ad516a6f7b55c575`. * Changed. The shape of `POST /v1/copilot/approvals` moved: fingerprint `b2789587012595ee` is now `2def393d6618957a`. * Changed. The shape of `POST /v1/copilot/commands` moved: fingerprint `2430028d0aebc3e3` is now `96c0c08ca839dea1`. * Changed. The shape of `POST /v1/copilot/threads/{id}/stop` moved: fingerprint `1f4ec90d9c21123b` is now `a6f5b97b1d5ec559`. * Changed. The shape of `POST /v1/devices/take` moved: fingerprint `8dbc4f20fd93ec50` is now `ceb3d25425c4eec0`. * Changed. The shape of `POST /v1/devices/{deviceId}/actions` moved: fingerprint `d45e9d0955ee0c4b` is now `9cdfd8361653e621`. * Changed. The shape of `POST /v1/devices/{deviceId}/lease` moved: fingerprint `d36943492c0ac518` is now `2ccbc93a425cef14`. * Changed. The shape of `POST /v1/devices/{deviceId}/live-session` moved: fingerprint `158c96c7b3d1216a` is now `d9243c37044b00e5`. * Changed. The shape of `POST /v1/devices/{deviceId}/stop` moved: fingerprint `be9bc6095208d439` is now `60694644c1859695`. * Changed. The shape of `POST /v1/devices/{deviceId}/stream` moved: fingerprint `82c23215b1993467` is now `e02f68d127de9afa`. * Changed. The shape of `POST /v1/devices/{deviceId}/wake` moved: fingerprint `f1454f742ecd9f76` is now `0ca825080b80fc3e`. * Changed. The shape of `POST /v1/fulfilments/{id}/cancel` moved: fingerprint `693600e0e5d30b15` is now `3646b193e9ce2030`. * Changed. The shape of `POST /v1/fulfilments/{id}/cancel-renewal` moved: fingerprint `b34ffa54b502becb` is now `80fe152d345e33ac`. * Changed. The shape of `POST /v1/fulfilments/{id}/return` moved: fingerprint `693600e0e5d30b15` is now `3646b193e9ce2030`. * Changed. The shape of `POST /v1/notifications/read` moved: fingerprint `c87dc4141a99872c` is now `7168d0ba8c68ff22`. * Changed. The shape of `POST /v1/receipts/{idempotencyKey}/reviewed` moved: fingerprint `e92d5f045a83dccd` is now `7de13b692c093074`. * Changed. The shape of `POST /v1/runs` moved: fingerprint `7a756e58f844f9d1` is now `bae32ebbe9ac7cf0`. * Changed. The shape of `POST /v1/runs/{runId}/cancel` moved: fingerprint `9715e0e4884b7e6e` is now `16159beedc679d57`. * Changed. The shape of `POST /v1/runs/{runId}/pause` moved: fingerprint `d73ccf237fcfd539` is now `b2cc5f5a263b0f31`. * Changed. The shape of `POST /v1/runs/{runId}/resume` moved: fingerprint `ad1864ad5cbc579f` is now `e59994e31ac63c4c`. * Changed. The shape of `POST /v1/webhooks` moved: fingerprint `2fb5898890290e6e` is now `de12a70f4a40c26b`. * Changed. The shape of `POST /v1/webhooks/{webhookId}/rotate` moved: fingerprint `52728176b958ba18` is now `352c7df363c16e1a`. * Changed. The shape of `POST /v1/webhooks/{webhookId}/test` moved: fingerprint `1a779d09043ac024` is now `2525b5b26dd40f5d`. * Changed. The shape of `PUT /v1/app-packages/{uploadId}/content` moved: fingerprint `dee89d4a28c910c8` is now `2ca571f2585e1453`. ### HTTP API and MCP tools, 2026-10-03 * Changed. The shape of `GET /healthz` moved: fingerprint `15b85882830569db` is now `67b4fa8fca0dd4b8`. ### HTTP API and MCP tools, 2026-10-02 * Changed. The shape of `GET /v1/app-library/policy` moved: fingerprint `fb84f81069d8a35e` is now `6f978842fb295ed7`. ### HTTP API and MCP tools, 2026-10-02 * Changed. The shape of `POST /v1/app-library/uploads/{uploadId}/publish` moved: fingerprint `7d0d5b448a8df800` is now `4e634fbfb2baaa5c`. ### HTTP API and MCP tools, 2026-10-02 * Changed. The shape of `GET /.well-known/oauth-protected-resource` moved: fingerprint `006fcfd7d5a85eba` is now `31bd6a8aba089614`. * Changed. The shape of `GET /.well-known/oauth-protected-resource/mcp` moved: fingerprint `006fcfd7d5a85eba` is now `31bd6a8aba089614`. * Changed. The shape of `GET /v1/api-keys` moved: fingerprint `9c9f1476ded55c69` is now `4c5d4ca3c65cf901`. * Changed. The shape of `GET /v1/api-keys/current` moved: fingerprint `2fd321d2c8dce1de` is now `46aa96f91f96c1a2`. * Changed. The shape of `PATCH /v1/api-keys/{id}` moved: fingerprint `9608d49dd15bb121` is now `06382650a9541099`. * Changed. The shape of `POST /v1/api-keys` moved: fingerprint `9a2b06ecd8c6c571` is now `dd1d0a972386f970`. * Changed. The shape of `POST /v1/api-keys/{id}/rotate` moved: fingerprint `3e9dfa4d50e5ba0a` is now `63e79021e92b55e9`. * Changed. The shape of `POST /v1/cli-sessions/token` moved: fingerprint `846e0dc7b09c54b8` is now `e4869828189519fa`. * Changed. The shape of `POST /v1/cli-sessions/{userCode}/approve` moved: fingerprint `4f6d28fbb230d7e4` is now `16a2a44744a517db`. * Added. `DELETE /v1/app-library/versions/{versionId}`. * Added. `GET /v1/app-library/apps`. * Added. `GET /v1/app-library/apps/{appId}`. * Added. `GET /v1/app-library/apps/{appId}/versions`. * Added. `GET /v1/app-library/deletions/{deletionId}`. * Added. `GET /v1/app-library/device-capabilities`. * Added. `GET /v1/app-library/inventory`. * Added. `GET /v1/app-library/inventory/refreshes/{refreshId}`. * Added. `GET /v1/app-library/inventory/refreshes/{refreshId}/results`. * Added. `GET /v1/app-library/jobs`. * Added. `GET /v1/app-library/jobs/{jobId}`. * Added. `GET /v1/app-library/jobs/{jobId}/targets`. * Added. `GET /v1/app-library/jobs/{jobId}/targets/{targetId}/attempts`. * Added. `GET /v1/app-library/policy`. * Added. `GET /v1/app-library/previews/{previewId}`. * Added. `GET /v1/app-library/previews/{previewId}/targets`. * Added. `GET /v1/app-library/requests/{requestKey}`. * Added. `GET /v1/app-library/uploads/{uploadId}`. * Added. `GET /v1/app-library/uploads/{uploadId}/parts`. * Added. `GET /v1/app-library/versions/{versionId}`. * Added. `PATCH /v1/app-library/apps/{appId}`. * Added. `POST /v1/app-library/inventory/refreshes`. * Added. `POST /v1/app-library/jobs`. * Added. `POST /v1/app-library/jobs/{jobId}/retry`. * Added. `POST /v1/app-library/jobs/{jobId}/stop`. * Added. `POST /v1/app-library/previews`. * Added. `POST /v1/app-library/uploads`. * Added. `POST /v1/app-library/uploads/{uploadId}/abort`. * Added. `POST /v1/app-library/uploads/{uploadId}/complete`. * Added. `POST /v1/app-library/uploads/{uploadId}/parts/{partNumber}/url`. * Added. `POST /v1/app-library/uploads/{uploadId}/publish`. * Added. `POST /v1/app-library/versions/{versionId}/archive`. * Added. `POST /v1/app-library/versions/{versionId}/restore`. * Added. MCP tool `create_app_job`. * Added. MCP tool `get_app_inventory`. * Added. MCP tool `get_app_inventory_refresh`. * Added. MCP tool `get_app_job`. * Added. MCP tool `get_app_preview`. * Added. MCP tool `get_app_request`. * Added. MCP tool `get_app_upload`. * Added. MCP tool `list_app_device_capabilities`. * Added. MCP tool `list_app_inventory_refresh_results`. * Added. MCP tool `list_app_job_targets`. * Added. MCP tool `list_app_jobs`. * Added. MCP tool `list_app_preview_targets`. * Added. MCP tool `list_app_versions`. * Added. MCP tool `list_apps`. * Added. MCP tool `preview_app_operation`. * Added. MCP tool `publish_app_upload`. * Added. MCP tool `refresh_app_inventory`. * Added. MCP tool `reserve_app_upload`. * Added. MCP tool `retry_app_targets`. * Added. MCP tool `stop_app_targets`. ### HTTP API and MCP tools, 2026-10-02 * Changed. The shape of `GET /v1/devices/{deviceId}/driving` moved: fingerprint `c9d6bea00309dea4` is now `b2ae6fb0bca7a922`. * Changed. The shape of `GET /v1/runs` moved: fingerprint `3c7c18fd5ca5b7e4` is now `6297b21fde2babd0`. * Changed. The shape of `GET /v1/runs/{runId}` moved: fingerprint `345536479c95f200` is now `3f6fc660233e2689`. * Changed. The shape of `POST /v1/runs/{runId}/cancel` moved: fingerprint `790f1ff4498167ea` is now `9715e0e4884b7e6e`. * Changed. The shape of `POST /v1/runs/{runId}/pause` moved: fingerprint `1173bf007be64e6e` is now `d73ccf237fcfd539`. * Changed. The shape of `POST /v1/runs/{runId}/resume` moved: fingerprint `e05aec8c68877d15` is now `ad1864ad5cbc579f`. ### HTTP API and MCP tools, 2026-10-02 * Changed. The shape of `GET /v1/devices/{deviceId}/proxy` moved: fingerprint `8a0fb83f8048d2ae` is now `3bc7af1c01ebee9e`. * Changed. The shape of `GET /v1/proxies` moved: fingerprint `eb356b464cdfbc7f` is now `54954c38abac2a42`. * Changed. The shape of `GET /v1/proxies/{proxyId}` moved: fingerprint `078ed9ad7c662a9d` is now `b11e7bb849915d0f`. * Changed. The shape of `GET /v1/proxy-orders` moved: fingerprint `35d204c3539e7381` is now `34e145a2a53335a9`. * Changed. The shape of `GET /v1/proxy-orders/{orderId}` moved: fingerprint `c3a014f3b579e10f` is now `2fc1ea62980803e8`. * Changed. The shape of `GET /v1/proxy-products` moved: fingerprint `99fc2742fb7c586d` is now `2cb9f77d29bd30d6`. * Changed. The shape of `GET /v1/proxy-products/{productId}` moved: fingerprint `2daf971681ec1883` is now `b1a6be876c43fbba`. * Changed. The shape of `GET /v1/proxy-quotes/{quoteId}` moved: fingerprint `532e61fa58f43c40` is now `2cf16f7adee861ed`. * Changed. The shape of `POST /v1/proxy-operations` moved: fingerprint `110e1484dea3c970` is now `2d9b79bde9c7102c`. * Changed. The shape of `POST /v1/proxy-orders` moved: fingerprint `65d4925bc1ca84c5` is now `e04f9a1888014472`. ### HTTP API and MCP tools, 2026-10-02 * Changed. The shape of `GET /healthz` moved: fingerprint `85c945a5c98ddcd7` is now `15b85882830569db`. ### HTTP API and MCP tools, 2026-10-01 * Added. `GET /v1/phone-number-eligibility`. ### HTTP API and MCP tools, 2026-10-01 * Changed. The shape of `POST /v1/api-keys` moved: fingerprint `3178d5a1bb673bb6` is now `9a2b06ecd8c6c571`. * Changed. The shape of `POST /v1/api-keys/{id}/rotate` moved: fingerprint `eb20edeaf87d4eaa` is now `3e9dfa4d50e5ba0a`. * Changed. The shape of `POST /v1/cli-sessions/{userCode}/approve` moved: fingerprint `2d8ee586cb71d7e8` is now `4f6d28fbb230d7e4`. ### HTTP API and MCP tools, 2026-10-01 * Added. `GET /v1/devices/{deviceId}/proxy`. * Added. `GET /v1/proxies`. * Added. `GET /v1/proxies/{proxyId}`. * Added. `GET /v1/proxy-operations`. * Added. `GET /v1/proxy-operations/{operationId}`. * Added. `GET /v1/proxy-orders`. * Added. `GET /v1/proxy-orders/{orderId}`. * Added. `GET /v1/proxy-products`. * Added. `GET /v1/proxy-products/{productId}`. * Added. `GET /v1/proxy-quotes/{quoteId}`. * Added. `PATCH /v1/proxies/{proxyId}`. * Added. `POST /v1/proxies/{proxyId}/archive`. * Added. `POST /v1/proxy-operations`. * Added. `POST /v1/proxy-orders`. * Added. `POST /v1/proxy-orders/{orderId}/cancel`. * Added. `POST /v1/proxy-orders/{orderId}/checkout`. * Added. `POST /v1/proxy-quotes`. ### HTTP API and MCP tools, 2026-09-30 * Added. `GET /v1/app-packages/{uploadId}`. * Added. `POST /v1/app-packages`. * Added. `PUT /v1/app-packages/{uploadId}/content`. ### HTTP API and MCP tools, 2026-09-29 * Changed. The shape of `POST /v1/console/events` moved: fingerprint `7413d5a36da7ae6c` is now `e292e612c88d966f`. ### HTTP API and MCP tools, 2026-09-29 * Changed. The shape of `DELETE /v1/api-keys/current` moved: fingerprint `df5e1c6324c6a43e` is now `ede45c8efef4e7da`. * Changed. The shape of `DELETE /v1/api-keys/{id}` moved: fingerprint `f5e4821e4d404d9f` is now `fd0e24ddda430e6a`. * Changed. The shape of `DELETE /v1/copilot/automation-defaults/{id}` moved: fingerprint `e92fd4e9daeb0114` is now `dd7f69104957de09`. * Changed. The shape of `DELETE /v1/copilot/threads/{id}` moved: fingerprint `5e6e2b2403d0353f` is now `bc66b4f578a235a1`. * Changed. The shape of `DELETE /v1/devices/{deviceId}/lease` moved: fingerprint `b899d9af74047623` is now `e85e64d3c2bcaef8`. * Changed. The shape of `DELETE /v1/webhooks/{webhookId}` moved: fingerprint `43653be33b222698` is now `8b698553403c99df`. * Changed. The shape of `GET /healthz` moved: fingerprint `43cdacd79b7aea91` is now `85c945a5c98ddcd7`. * Changed. The shape of `GET /v1/admission` moved: fingerprint `a21ab0aefbcc0189` is now `f7aa822968eb07dc`. * Changed. The shape of `GET /v1/api-keys` moved: fingerprint `cdd8f84cc547c7e9` is now `9c9f1476ded55c69`. * Changed. The shape of `GET /v1/api-keys/current` moved: fingerprint `b20b4de662a87bce` is now `2fd321d2c8dce1de`. * Changed. The shape of `GET /v1/billing/upcoming` moved: fingerprint `0dca876aab1a4bff` is now `b5a016d76ab2c492`. * Changed. The shape of `GET /v1/cli-sessions/{userCode}` moved: fingerprint `ea41e78e743d67b8` is now `56808ddb51155b2e`. * Changed. The shape of `GET /v1/copilot/automation-defaults` moved: fingerprint `7928a21d76eef7d1` is now `f6454dc5e0480da4`. * Changed. The shape of `GET /v1/copilot/threads` moved: fingerprint `834e3c459eac6069` is now `45d0ef6a595c3615`. * Changed. The shape of `GET /v1/copilot/threads/{id}` moved: fingerprint `8073860469634ab4` is now `17710206d662bcb5`. * Changed. The shape of `GET /v1/copilot/threads/{id}/stream` moved: fingerprint `3695f0e4d16752ca` is now `bffb249526f4e3a7`. * Changed. The shape of `GET /v1/devices` moved: fingerprint `e7aba39bfe155e7a` is now `e255f756070f1804`. * Changed. The shape of `GET /v1/devices/{deviceId}` moved: fingerprint `68d25aaef27f2cbc` is now `e90ecbcdc520a5cf`. * Changed. The shape of `GET /v1/devices/{deviceId}/driving` moved: fingerprint `f73b6c29540415ae` is now `c9d6bea00309dea4`. * Changed. The shape of `GET /v1/devices/{deviceId}/screenshot` moved: fingerprint `4069f32756110eaa` is now `5496d77578e3d599`. * Changed. The shape of `GET /v1/frames/{frameId}` moved: fingerprint `eba60e5e2c9e0baa` is now `3af35158b3c904e9`. * Changed. The shape of `GET /v1/fulfilments` moved: fingerprint `fc2f650b993a9bf2` is now `b6a912c5b62a24f7`. * Changed. The shape of `GET /v1/fulfilments/{id}/estimate-history` moved: fingerprint `c3f6a723bcc22c1a` is now `acf1fbe8fe84fc0d`. * Changed. The shape of `GET /v1/leases` moved: fingerprint `9d2763721e2a86ff` is now `c9b1159a47f9ad61`. * Changed. The shape of `GET /v1/me/notification-preferences` moved: fingerprint `cd64d726a5230682` is now `4ddfd8d29eef3a80`. * Changed. The shape of `GET /v1/notifications` moved: fingerprint `62572ef90eb56e3c` is now `67fd9cdfdb93647a`. * Changed. The shape of `GET /v1/receipts` moved: fingerprint `0f71b23de36cc6b8` is now `2a0da7e3cbd6f442`. * Changed. The shape of `GET /v1/receipts/{idempotencyKey}` moved: fingerprint `2e636a5bc0483369` is now `c1e21559cc98cba0`. * Changed. The shape of `GET /v1/runs` moved: fingerprint `577072a724afb874` is now `3c7c18fd5ca5b7e4`. * Changed. The shape of `GET /v1/runs/{runId}` moved: fingerprint `a75c5c6d6301b874` is now `345536479c95f200`. * Changed. The shape of `GET /v1/skus` moved: fingerprint `bb7a9e3a52a08eb3` is now `baa98a4e17a172f4`. * Changed. The shape of `GET /v1/time` moved: fingerprint `96922d023a616c2e` is now `16fc873d71ab267b`. * Changed. The shape of `GET /v1/usage` moved: fingerprint `dbf374d6a8f5b361` is now `1cc7f97fced7536d`. * Changed. The shape of `GET /v1/webhooks` moved: fingerprint `f63735e2ac0c746f` is now `adfcb421a995cfb8`. * Changed. The shape of `GET /v1/webhooks/{webhookId}/deliveries` moved: fingerprint `8b0c814a85f62986` is now `c7f46eea421acddc`. * Changed. The shape of `PATCH /v1/api-keys/{id}` moved: fingerprint `3b79c800f3dcc3ef` is now `9608d49dd15bb121`. * Changed. The shape of `PATCH /v1/copilot/automation-defaults` moved: fingerprint `ca0a1bb96c5ae70d` is now `9a56a282f62efbf0`. * Changed. The shape of `PATCH /v1/copilot/threads/{id}` moved: fingerprint `d09a75cd08f8b680` is now `97d0ce2c56c6ce0a`. * Changed. The shape of `PATCH /v1/devices/{deviceId}` moved: fingerprint `e36db972e547c4b3` is now `198b3990f7046451`. * Changed. The shape of `PATCH /v1/devices/{deviceId}/lease` moved: fingerprint `46c469d75abf68ee` is now `5766c8ed776d284a`. * Changed. The shape of `PATCH /v1/me/notification-preferences` moved: fingerprint `ba4bdfaa3017b5d2` is now `b4deff15f148860e`. * Changed. The shape of `PATCH /v1/webhooks/{webhookId}` moved: fingerprint `0f4d49d04f581efb` is now `df102f51aa147233`. * Changed. The shape of `POST /mcp` moved: fingerprint `1c38629b8fd53d1d` is now `63b42f4bccf1b88a`. * Changed. The shape of `POST /v1/api-keys` moved: fingerprint `815e887b3c92da4d` is now `3178d5a1bb673bb6`. * Changed. The shape of `POST /v1/api-keys/{id}/rotate` moved: fingerprint `32f46a28955b5843` is now `eb20edeaf87d4eaa`. * Changed. The shape of `POST /v1/billing/portal-sessions` moved: fingerprint `8be207dda5207860` is now `ee662674c45fd9fa`. * Changed. The shape of `POST /v1/checkout-sessions` moved: fingerprint `083c071c611a0019` is now `f0581ce04ca26cf5`. * Changed. The shape of `POST /v1/cli-sessions` moved: fingerprint `64e28afa99e3f1d1` is now `2420d38b679208bc`. * Changed. The shape of `POST /v1/cli-sessions/token` moved: fingerprint `dd775e39ff1297cb` is now `846e0dc7b09c54b8`. * Changed. The shape of `POST /v1/cli-sessions/{userCode}/approve` moved: fingerprint `0a0f44137f3c1bcf` is now `2d8ee586cb71d7e8`. * Changed. The shape of `POST /v1/cli-sessions/{userCode}/deny` moved: fingerprint `9a6ec7ea1e33e32d` is now `31110ca3f796d056`. * Changed. The shape of `POST /v1/console/events` moved: fingerprint `c3d65838a165ef56` is now `7413d5a36da7ae6c`. * Changed. The shape of `POST /v1/copilot` moved: fingerprint `619fd77c3dc9339d` is now `acff7f5148ca1fc9`. * Changed. The shape of `POST /v1/copilot/approvals` moved: fingerprint `baf0e51d4bb078ce` is now `b2789587012595ee`. * Changed. The shape of `POST /v1/copilot/commands` moved: fingerprint `8d967a36a70053f0` is now `2430028d0aebc3e3`. * Changed. The shape of `POST /v1/copilot/threads/{id}/stop` moved: fingerprint `b7c8943e5fa9c575` is now `1f4ec90d9c21123b`. * Changed. The shape of `POST /v1/devices/take` moved: fingerprint `685f6e4584a2b1f0` is now `8dbc4f20fd93ec50`. * Changed. The shape of `POST /v1/devices/{deviceId}/actions` moved: fingerprint `5959c328c6d8aa96` is now `d45e9d0955ee0c4b`. * Changed. The shape of `POST /v1/devices/{deviceId}/lease` moved: fingerprint `e363c930071a9d79` is now `d36943492c0ac518`. * Changed. The shape of `POST /v1/devices/{deviceId}/live-session` moved: fingerprint `e9730e8919e45e06` is now `158c96c7b3d1216a`. * Changed. The shape of `POST /v1/devices/{deviceId}/stop` moved: fingerprint `ec795d8f2157462c` is now `be9bc6095208d439`. * Changed. The shape of `POST /v1/devices/{deviceId}/stream` moved: fingerprint `e2f664a282f6338e` is now `82c23215b1993467`. * Changed. The shape of `POST /v1/devices/{deviceId}/wake` moved: fingerprint `caefb03847fcf6a6` is now `f1454f742ecd9f76`. * Changed. The shape of `POST /v1/fulfilments/{id}/cancel` moved: fingerprint `bafd48570a085178` is now `693600e0e5d30b15`. * Changed. The shape of `POST /v1/fulfilments/{id}/return` moved: fingerprint `bafd48570a085178` is now `693600e0e5d30b15`. * Changed. The shape of `POST /v1/notifications/read` moved: fingerprint `cbb50100f79e2bb0` is now `c87dc4141a99872c`. * Changed. The shape of `POST /v1/receipts/{idempotencyKey}/reviewed` moved: fingerprint `3d574a3a05ce59e2` is now `e92d5f045a83dccd`. * Changed. The shape of `POST /v1/runs` moved: fingerprint `f57171b481517066` is now `7a756e58f844f9d1`. * Changed. The shape of `POST /v1/runs/{runId}/cancel` moved: fingerprint `b5f7915c3c107868` is now `790f1ff4498167ea`. * Changed. The shape of `POST /v1/runs/{runId}/pause` moved: fingerprint `3d35bff4e2b57d9f` is now `1173bf007be64e6e`. * Changed. The shape of `POST /v1/runs/{runId}/resume` moved: fingerprint `31c7dad781ef20c5` is now `e05aec8c68877d15`. * Changed. The shape of `POST /v1/webhooks` moved: fingerprint `9d06da8b27728917` is now `2fb5898890290e6e`. * Changed. The shape of `POST /v1/webhooks/{webhookId}/rotate` moved: fingerprint `8ee3b6c73f195228` is now `52728176b958ba18`. * Changed. The shape of `POST /v1/webhooks/{webhookId}/test` moved: fingerprint `83d923320bda9408` is now `1a779d09043ac024`. * Added. `GET /v1/fulfilments/{id}/renewal-status`. * Added. `POST /v1/fulfilments/{id}/cancel-renewal`. ### HTTP API and MCP tools, 2026-09-28 * Changed. The shape of `GET /v1/devices` moved: fingerprint `9b6a728bfe815156` is now `e7aba39bfe155e7a`. * Changed. The shape of `GET /v1/devices/{deviceId}` moved: fingerprint `de9390dfd686abf2` is now `68d25aaef27f2cbc`. * Changed. The shape of `PATCH /v1/devices/{deviceId}` moved: fingerprint `f762d457536c9510` is now `e36db972e547c4b3`. ### HTTP API and MCP tools, 2026-09-28 * Changed. The shape of `GET /v1/devices` moved: fingerprint `072c21afd98860b7` is now `9b6a728bfe815156`. * Changed. The shape of `GET /v1/devices/{deviceId}` moved: fingerprint `5ae9f2fb7b2419fb` is now `de9390dfd686abf2`. * Changed. The shape of `PATCH /v1/devices/{deviceId}` moved: fingerprint `9539daa01895e8f9` is now `f762d457536c9510`. ### HTTP API and MCP tools, 2026-09-28 * Added. `GET /gateway/v1/releases/current`. ### HTTP API and MCP tools, 2026-09-28 * Changed. The shape of `GET /healthz` moved: fingerprint `de7ccc7df2f673a1` is now `43cdacd79b7aea91`. ### HTTP API and MCP tools, 2026-09-28 * Changed. The shape of `GET /healthz` moved: fingerprint `fc56fd6a3dfebbb5` is now `de7ccc7df2f673a1`. ### HTTP API and MCP tools, 2026-09-28 * Changed. The shape of `GET /healthz` moved: fingerprint `c0c8d0bd8c75a34b` is now `fc56fd6a3dfebbb5`. ### HTTP API and MCP tools, 2026-09-28 * Changed. The shape of `GET /healthz` moved: fingerprint `d8a599b61de18fd9` is now `c0c8d0bd8c75a34b`. ### HTTP API and MCP tools, 2026-09-26 * Changed. The shape of `GET /healthz` moved: fingerprint `e1c7893c41f693ac` is now `d8a599b61de18fd9`. ### HTTP API and MCP tools, 2026-09-26 * Changed. The shape of `GET /healthz` moved: fingerprint `14f95c1bba60c4e0` is now `e1c7893c41f693ac`. * Added. `POST /v1/console/events`. * Added. `POST /webhooks/livekit`. ### HTTP API and MCP tools, 2026-09-26 * Added. `POST /gateway/enroll`. ### HTTP API and MCP tools, 2026-09-25 * Changed. The shape of `GET /healthz` moved: fingerprint `a764472d659983c5` is now `14f95c1bba60c4e0`. ### HTTP API and MCP tools, 2026-09-25 * Changed. The shape of `GET /v1/devices` moved: fingerprint `ec2fbcdaa95e06b6` is now `072c21afd98860b7`. * Changed. The shape of `GET /v1/devices/{deviceId}` moved: fingerprint `d22750b4dfb2b50f` is now `5ae9f2fb7b2419fb`. * Changed. The shape of `GET /v1/devices/{deviceId}/screenshot` moved: fingerprint `7bc6e87966a0dc16` is now `4069f32756110eaa`. * Changed. The shape of `PATCH /v1/devices/{deviceId}` moved: fingerprint `ea868eddc1f029b6` is now `9539daa01895e8f9`. * Changed. The shape of `POST /v1/devices/{deviceId}/actions` moved: fingerprint `251ac9a0fecd3cdb` is now `5959c328c6d8aa96`. * Added. `GET /v1/time`. * Added. `POST /v1/devices/{deviceId}/stop`. * Added. `POST /v1/devices/{deviceId}/stream`. ### HTTP API and MCP tools, 2026-09-24 * Changed. The shape of `GET /.well-known/oauth-protected-resource` moved: fingerprint `d92f969962990042` is now `006fcfd7d5a85eba`. * Changed. The shape of `GET /.well-known/oauth-protected-resource/mcp` moved: fingerprint `d92f969962990042` is now `006fcfd7d5a85eba`. * Changed. The shape of `GET /v1/api-keys` moved: fingerprint `7b73e9aecb6975f0` is now `cdd8f84cc547c7e9`. * Changed. The shape of `GET /v1/api-keys/current` moved: fingerprint `ff52c00cb9c297a3` is now `b20b4de662a87bce`. * Changed. The shape of `PATCH /v1/api-keys/{id}` moved: fingerprint `35aa3bbcf6dc8cdb` is now `3b79c800f3dcc3ef`. * Changed. The shape of `POST /v1/api-keys` moved: fingerprint `e40b28687cf45504` is now `815e887b3c92da4d`. * Changed. The shape of `POST /v1/api-keys/{id}/rotate` moved: fingerprint `7ae2481be5b3cb1d` is now `32f46a28955b5843`. * Changed. The shape of `POST /v1/cli-sessions/token` moved: fingerprint `b717144d56d7ef8a` is now `dd775e39ff1297cb`. * Changed. The shape of `POST /v1/cli-sessions/{userCode}/approve` moved: fingerprint `bdf341f775d50a88` is now `0a0f44137f3c1bcf`. ### HTTP API and MCP tools, 2026-09-24 * Added. `DELETE /v1/api-keys/current`. * Added. `GET /v1/api-keys/current`. * Added. `GET /v1/cli-sessions/{userCode}`. * Added. `POST /v1/cli-sessions`. * Added. `POST /v1/cli-sessions/token`. * Added. `POST /v1/cli-sessions/{userCode}/approve`. * Added. `POST /v1/cli-sessions/{userCode}/deny`. ### HTTP API and MCP tools, 2026-09-24 * Changed. The shape of `GET /v1/fulfilments` moved: fingerprint `4655e376a518f488` is now `fc2f650b993a9bf2`. * Changed. The shape of `GET /v1/notifications` moved: fingerprint `13e2855ada3c8d69` is now `62572ef90eb56e3c`. ### HTTP API and MCP tools, 2026-09-23 * Changed. The shape of `GET /healthz` moved: fingerprint `ca8d4efb257cffc7` is now `a764472d659983c5`. * Changed. The shape of `GET /v1/skus` moved: fingerprint `cfa15a2c72a38c2c` is now `bb7a9e3a52a08eb3`. * Changed. The shape of `POST /v1/checkout-sessions` moved: fingerprint `7d70b3b60515725e` is now `083c071c611a0019`. ### HTTP API and MCP tools, 2026-09-23 * Changed. The shape of `POST /v1/copilot` moved: fingerprint `0fb3d76804dac135` is now `619fd77c3dc9339d`. ### HTTP API and MCP tools, 2026-09-23 * Changed. The shape of `GET /v1/notifications` moved: fingerprint `8157035f57fce56d` is now `13e2855ada3c8d69`. * Changed. The shape of `GET /v1/skus` moved: fingerprint `70cd68f6992b64d1` is now `cfa15a2c72a38c2c`. ### HTTP API and MCP tools, 2026-09-23 * Changed. The shape of `DELETE /v1/api-keys/{id}` moved: fingerprint `1351253ab1c5328c` is now `f5e4821e4d404d9f`. * Changed. The shape of `DELETE /v1/copilot/automation-defaults/{id}` moved: fingerprint `0cef8860ef4dacad` is now `e92fd4e9daeb0114`. * Changed. The shape of `DELETE /v1/copilot/threads/{id}` moved: fingerprint `5ae1c87ce116c156` is now `5e6e2b2403d0353f`. * Changed. The shape of `DELETE /v1/devices/{deviceId}/lease` moved: fingerprint `cd23643e603be41a` is now `b899d9af74047623`. * Changed. The shape of `DELETE /v1/webhooks/{webhookId}` moved: fingerprint `3a6d2d2112f61f2f` is now `43653be33b222698`. * Changed. The shape of `GET /v1/admission` moved: fingerprint `8d6dfe41e13d9691` is now `a21ab0aefbcc0189`. * Changed. The shape of `GET /v1/api-keys` moved: fingerprint `4a2d69e45d0f8da3` is now `7b73e9aecb6975f0`. * Changed. The shape of `GET /v1/billing/upcoming` moved: fingerprint `6be6d04d844fcde5` is now `0dca876aab1a4bff`. * Changed. The shape of `GET /v1/copilot/automation-defaults` moved: fingerprint `219e7fe6fdc233f9` is now `7928a21d76eef7d1`. * Changed. The shape of `GET /v1/copilot/threads` moved: fingerprint `ab08c0f17ff93b29` is now `834e3c459eac6069`. * Changed. The shape of `GET /v1/copilot/threads/{id}` moved: fingerprint `99f09ae350647f32` is now `8073860469634ab4`. * Changed. The shape of `GET /v1/copilot/threads/{id}/stream` moved: fingerprint `bd14d9cb19834c78` is now `3695f0e4d16752ca`. * Changed. The shape of `GET /v1/devices` moved: fingerprint `68bda2bd93799cc2` is now `ec2fbcdaa95e06b6`. * Changed. The shape of `GET /v1/devices/{deviceId}` moved: fingerprint `c95ef16659fca7c6` is now `d22750b4dfb2b50f`. * Changed. The shape of `GET /v1/devices/{deviceId}/driving` moved: fingerprint `8733972db746cd22` is now `f73b6c29540415ae`. * Changed. The shape of `GET /v1/devices/{deviceId}/screenshot` moved: fingerprint `179b9a4fde1b49ef` is now `7bc6e87966a0dc16`. * Changed. The shape of `GET /v1/frames/{frameId}` moved: fingerprint `fa7e536d7e236c00` is now `eba60e5e2c9e0baa`. * Changed. The shape of `GET /v1/fulfilments/{id}/estimate-history` moved: fingerprint `9b9ac46a00876fa7` is now `c3f6a723bcc22c1a`. * Changed. The shape of `GET /v1/leases` moved: fingerprint `121a83c4a6adaa48` is now `9d2763721e2a86ff`. * Changed. The shape of `GET /v1/me/notification-preferences` moved: fingerprint `c01ebf367ba112b6` is now `cd64d726a5230682`. * Changed. The shape of `GET /v1/notifications` moved: fingerprint `722539ef72c0d537` is now `8157035f57fce56d`. * Changed. The shape of `GET /v1/receipts` moved: fingerprint `fb902c0ef21b7a24` is now `0f71b23de36cc6b8`. * Changed. The shape of `GET /v1/receipts/{idempotencyKey}` moved: fingerprint `1ec3308f586a71de` is now `2e636a5bc0483369`. * Changed. The shape of `GET /v1/runs` moved: fingerprint `37e03cbdac05d31f` is now `577072a724afb874`. * Changed. The shape of `GET /v1/runs/{runId}` moved: fingerprint `3efdfc8b317ad5d0` is now `a75c5c6d6301b874`. * Changed. The shape of `GET /v1/usage` moved: fingerprint `8491b51d442b553c` is now `dbf374d6a8f5b361`. * Changed. The shape of `GET /v1/webhooks` moved: fingerprint `a929507a33318a43` is now `f63735e2ac0c746f`. * Changed. The shape of `GET /v1/webhooks/{webhookId}/deliveries` moved: fingerprint `355efeb65abeba54` is now `8b0c814a85f62986`. * Changed. The shape of `PATCH /v1/api-keys/{id}` moved: fingerprint `c4da3fb6fb5022c7` is now `35aa3bbcf6dc8cdb`. * Changed. The shape of `PATCH /v1/copilot/automation-defaults` moved: fingerprint `8c9db68907dedadb` is now `ca0a1bb96c5ae70d`. * Changed. The shape of `PATCH /v1/copilot/threads/{id}` moved: fingerprint `1793b89337d7d1b5` is now `d09a75cd08f8b680`. * Changed. The shape of `PATCH /v1/devices/{deviceId}` moved: fingerprint `c6031da3015bb0b7` is now `ea868eddc1f029b6`. * Changed. The shape of `PATCH /v1/devices/{deviceId}/lease` moved: fingerprint `5bd47aa4fde8eb41` is now `46c469d75abf68ee`. * Changed. The shape of `PATCH /v1/me/notification-preferences` moved: fingerprint `1829e3fb46616b0e` is now `ba4bdfaa3017b5d2`. * Changed. The shape of `PATCH /v1/webhooks/{webhookId}` moved: fingerprint `c37f069ed6ffe831` is now `0f4d49d04f581efb`. * Changed. The shape of `POST /mcp` moved: fingerprint `dec98b1cdd3afd23` is now `1c38629b8fd53d1d`. * Changed. The shape of `POST /v1/api-keys` moved: fingerprint `75c18c2cd14ceffc` is now `e40b28687cf45504`. * Changed. The shape of `POST /v1/api-keys/{id}/rotate` moved: fingerprint `17f3d7fca10f0393` is now `7ae2481be5b3cb1d`. * Changed. The shape of `POST /v1/checkout-sessions` moved: fingerprint `419098ce9867508d` is now `7d70b3b60515725e`. * Changed. The shape of `POST /v1/copilot` moved: fingerprint `8e0ac61287a675d0` is now `0fb3d76804dac135`. * Changed. The shape of `POST /v1/copilot/approvals` moved: fingerprint `b43ab33b3538cb78` is now `baf0e51d4bb078ce`. * Changed. The shape of `POST /v1/copilot/commands` moved: fingerprint `02689647bc3fd4db` is now `8d967a36a70053f0`. * Changed. The shape of `POST /v1/copilot/threads/{id}/stop` moved: fingerprint `f66fa6ea3baaa234` is now `b7c8943e5fa9c575`. * Changed. The shape of `POST /v1/devices/take` moved: fingerprint `5d7bd28f1e1a5f85` is now `685f6e4584a2b1f0`. * Changed. The shape of `POST /v1/devices/{deviceId}/actions` moved: fingerprint `b16dcb4c0c646c7b` is now `251ac9a0fecd3cdb`. * Changed. The shape of `POST /v1/devices/{deviceId}/lease` moved: fingerprint `9dfdbf8c417754d4` is now `e363c930071a9d79`. * Changed. The shape of `POST /v1/devices/{deviceId}/live-session` moved: fingerprint `0391c45944ffc9ab` is now `e9730e8919e45e06`. * Changed. The shape of `POST /v1/devices/{deviceId}/wake` moved: fingerprint `0ee72cfe1bba7e50` is now `caefb03847fcf6a6`. * Changed. The shape of `POST /v1/fulfilments/{id}/cancel` moved: fingerprint `b67ef4be1f473159` is now `bafd48570a085178`. * Changed. The shape of `POST /v1/fulfilments/{id}/return` moved: fingerprint `b67ef4be1f473159` is now `bafd48570a085178`. * Changed. The shape of `POST /v1/notifications/read` moved: fingerprint `2caff5f56d93231b` is now `cbb50100f79e2bb0`. * Changed. The shape of `POST /v1/receipts/{idempotencyKey}/reviewed` moved: fingerprint `1c49d6c798858eeb` is now `3d574a3a05ce59e2`. * Changed. The shape of `POST /v1/runs` moved: fingerprint `a794e5ba193e0d50` is now `f57171b481517066`. * Changed. The shape of `POST /v1/runs/{runId}/cancel` moved: fingerprint `6fde98089ed35512` is now `b5f7915c3c107868`. * Changed. The shape of `POST /v1/runs/{runId}/pause` moved: fingerprint `fa9538fe90d28606` is now `3d35bff4e2b57d9f`. * Changed. The shape of `POST /v1/runs/{runId}/resume` moved: fingerprint `92dce316bf33f2a4` is now `31c7dad781ef20c5`. * Changed. The shape of `POST /v1/webhooks` moved: fingerprint `fd72dd556d8c8147` is now `9d06da8b27728917`. * Changed. The shape of `POST /v1/webhooks/{webhookId}/rotate` moved: fingerprint `094c35eb0d3028dd` is now `8ee3b6c73f195228`. * Changed. The shape of `POST /v1/webhooks/{webhookId}/test` moved: fingerprint `cd748bc5a1faea40` is now `83d923320bda9408`. * Added. `POST /v1/billing/portal-sessions`. ### HTTP API and MCP tools, 2026-09-23 * Added. `POST /webhooks/clerk`. ### HTTP API and MCP tools, 2026-09-22 * Changed. The shape of `GET /healthz` moved: fingerprint `6582c4776cc8e80a` is now `ca8d4efb257cffc7`. * Changed. The shape of `GET /v1/billing/upcoming` moved: fingerprint `35263974095b1d62` is now `6be6d04d844fcde5`. * Changed. The shape of `GET /v1/notifications` moved: fingerprint `c98249adccef6bfe` is now `722539ef72c0d537`. ### HTTP API and MCP tools, 2026-09-22 * Added. `POST /webhooks/stripe`. ### HTTP API and MCP tools, 2026-09-21 * Changed. The shape of `GET /v1/skus` moved: fingerprint `b2b5cf3f36eecc53` is now `70cd68f6992b64d1`. ### HTTP API and MCP tools, 2026-09-21 * Changed. The shape of `GET /v1/devices` moved: fingerprint `168a1e34395d81b5` is now `68bda2bd93799cc2`. * Changed. The shape of `GET /v1/devices/{deviceId}` moved: fingerprint `509deff6694b3ea7` is now `c95ef16659fca7c6`. * Changed. The shape of `PATCH /v1/devices/{deviceId}` moved: fingerprint `4267bc5f25f3eea2` is now `c6031da3015bb0b7`. ### HTTP API and MCP tools, 2026-09-21 * Changed. The shape of `GET /v1/runs` moved: fingerprint `b928c81e10d4c2a7` is now `37e03cbdac05d31f`. * Changed. The shape of `GET /v1/runs/{runId}` moved: fingerprint `3dbb56ecec62844c` is now `3efdfc8b317ad5d0`. * Changed. The shape of `POST /v1/runs/{runId}/cancel` moved: fingerprint `0b29bc0248a3fadc` is now `6fde98089ed35512`. * Changed. The shape of `POST /v1/runs/{runId}/pause` moved: fingerprint `12a9d4ad9f6f4591` is now `fa9538fe90d28606`. * Changed. The shape of `POST /v1/runs/{runId}/resume` moved: fingerprint `c5a6a8605e5a7901` is now `92dce316bf33f2a4`. * Added. `GET /v1/frames/{frameId}`. ### HTTP API and MCP tools, 2026-09-21 * Changed. The shape of `DELETE /v1/api-keys/{id}` moved: fingerprint `8673120cc6b5fc82` is now `1351253ab1c5328c`. * Changed. The shape of `DELETE /v1/copilot/automation-defaults/{id}` moved: fingerprint `64d8632363f6dd07` is now `0cef8860ef4dacad`. * Changed. The shape of `DELETE /v1/copilot/threads/{id}` moved: fingerprint `eeafa5b8707c1aa9` is now `5ae1c87ce116c156`. * Changed. The shape of `DELETE /v1/devices/{deviceId}/lease` moved: fingerprint `e1550c8338d33ded` is now `cd23643e603be41a`. * Changed. The shape of `DELETE /v1/webhooks/{webhookId}` moved: fingerprint `0556a29de20886f3` is now `3a6d2d2112f61f2f`. * Changed. The shape of `GET /v1/admission` moved: fingerprint `19696235c57fac2a` is now `8d6dfe41e13d9691`. * Changed. The shape of `GET /v1/api-keys` moved: fingerprint `1e1c4786d5d8c81f` is now `4a2d69e45d0f8da3`. * Changed. The shape of `GET /v1/billing/upcoming` moved: fingerprint `46e89e8f02075496` is now `35263974095b1d62`. * Changed. The shape of `GET /v1/copilot-allowance` moved: fingerprint `8c5ff8172b2fab86` is now `87ce788065163101`. * Changed. The shape of `GET /v1/copilot/automation-defaults` moved: fingerprint `6829594780b28914` is now `219e7fe6fdc233f9`. * Changed. The shape of `GET /v1/copilot/threads` moved: fingerprint `64c88e0656207256` is now `ab08c0f17ff93b29`. * Changed. The shape of `GET /v1/copilot/threads/{id}` moved: fingerprint `f9d845aa07f628ea` is now `99f09ae350647f32`. * Changed. The shape of `GET /v1/copilot/threads/{id}/stream` moved: fingerprint `c151083d8fdcdb1b` is now `bd14d9cb19834c78`. * Changed. The shape of `GET /v1/devices` moved: fingerprint `818fa9f7a8689698` is now `168a1e34395d81b5`. * Changed. The shape of `GET /v1/devices/{deviceId}` moved: fingerprint `3eb025fc71aba5ae` is now `509deff6694b3ea7`. * Changed. The shape of `GET /v1/devices/{deviceId}/driving` moved: fingerprint `71e8df18cc052ca6` is now `8733972db746cd22`. * Changed. The shape of `GET /v1/devices/{deviceId}/screenshot` moved: fingerprint `2a1d16fae6e182f8` is now `179b9a4fde1b49ef`. * Changed. The shape of `GET /v1/fulfilments` moved: fingerprint `254df8efba6891a8` is now `4655e376a518f488`. * Changed. The shape of `GET /v1/fulfilments/{id}/estimate-history` moved: fingerprint `0e6ee682516ce488` is now `9b9ac46a00876fa7`. * Changed. The shape of `GET /v1/leases` moved: fingerprint `304ef3aa20c17d05` is now `121a83c4a6adaa48`. * Changed. The shape of `GET /v1/me/notification-preferences` moved: fingerprint `316bf96e0d31b44e` is now `c01ebf367ba112b6`. * Changed. The shape of `GET /v1/notifications` moved: fingerprint `789cd7c5b962dc49` is now `c98249adccef6bfe`. * Changed. The shape of `GET /v1/receipts` moved: fingerprint `53e1ee2246e304da` is now `fb902c0ef21b7a24`. * Changed. The shape of `GET /v1/receipts/{idempotencyKey}` moved: fingerprint `ecc1bcdd6e08aa09` is now `1ec3308f586a71de`. * Changed. The shape of `GET /v1/runs` moved: fingerprint `b5de8bab4434ca34` is now `b928c81e10d4c2a7`. * Changed. The shape of `GET /v1/runs/{runId}` moved: fingerprint `eaefe32c8985fcd6` is now `3dbb56ecec62844c`. * Changed. The shape of `GET /v1/skus` moved: fingerprint `7ab63e3711bff143` is now `b2b5cf3f36eecc53`. * Changed. The shape of `GET /v1/usage` moved: fingerprint `86d4e13938b869bd` is now `8491b51d442b553c`. * Changed. The shape of `GET /v1/webhooks` moved: fingerprint `d0c263bb375ef039` is now `a929507a33318a43`. * Changed. The shape of `GET /v1/webhooks/{webhookId}/deliveries` moved: fingerprint `d84cfd45ab723048` is now `355efeb65abeba54`. * Changed. The shape of `PATCH /v1/api-keys/{id}` moved: fingerprint `edb9c26504feff1b` is now `c4da3fb6fb5022c7`. * Changed. The shape of `PATCH /v1/copilot/automation-defaults` moved: fingerprint `472a1c11fefd2582` is now `8c9db68907dedadb`. * Changed. The shape of `PATCH /v1/copilot/threads/{id}` moved: fingerprint `63d6ae4258590c0e` is now `1793b89337d7d1b5`. * Changed. The shape of `PATCH /v1/devices/{deviceId}` moved: fingerprint `1514b8906d076807` is now `4267bc5f25f3eea2`. * Changed. The shape of `PATCH /v1/devices/{deviceId}/lease` moved: fingerprint `a8d617b89eb1cd14` is now `5bd47aa4fde8eb41`. * Changed. The shape of `PATCH /v1/me/notification-preferences` moved: fingerprint `f37c032b61f310d0` is now `1829e3fb46616b0e`. * Changed. The shape of `PATCH /v1/webhooks/{webhookId}` moved: fingerprint `8691f4ee94f387b7` is now `c37f069ed6ffe831`. * Changed. The shape of `POST /mcp` moved: fingerprint `2402cb5e32b96260` is now `dec98b1cdd3afd23`. * Changed. The shape of `POST /v1/api-keys` moved: fingerprint `d0fd810b97e12a99` is now `75c18c2cd14ceffc`. * Changed. The shape of `POST /v1/api-keys/{id}/rotate` moved: fingerprint `5598b2313e06918d` is now `17f3d7fca10f0393`. * Changed. The shape of `POST /v1/checkout-sessions` moved: fingerprint `0511c35acce166ca` is now `419098ce9867508d`. * Changed. The shape of `POST /v1/copilot` moved: fingerprint `937da5baf857131f` is now `8e0ac61287a675d0`. * Changed. The shape of `POST /v1/copilot/approvals` moved: fingerprint `1a9e1b8df732b737` is now `b43ab33b3538cb78`. * Changed. The shape of `POST /v1/copilot/commands` moved: fingerprint `9111c9715be98d9c` is now `02689647bc3fd4db`. * Changed. The shape of `POST /v1/copilot/threads/{id}/stop` moved: fingerprint `747189d1b29984e5` is now `f66fa6ea3baaa234`. * Changed. The shape of `POST /v1/devices/take` moved: fingerprint `94bad117ddc653dd` is now `5d7bd28f1e1a5f85`. * Changed. The shape of `POST /v1/devices/{deviceId}/actions` moved: fingerprint `eaebdf57ef775c6d` is now `b16dcb4c0c646c7b`. * Changed. The shape of `POST /v1/devices/{deviceId}/lease` moved: fingerprint `28771d2cd4faaf18` is now `9dfdbf8c417754d4`. * Changed. The shape of `POST /v1/devices/{deviceId}/live-session` moved: fingerprint `92b0a414aa237e2f` is now `0391c45944ffc9ab`. * Changed. The shape of `POST /v1/devices/{deviceId}/wake` moved: fingerprint `a14393037d6ac212` is now `0ee72cfe1bba7e50`. * Changed. The shape of `POST /v1/fulfilments/{id}/cancel` moved: fingerprint `36951a3d486e584e` is now `b67ef4be1f473159`. * Changed. The shape of `POST /v1/fulfilments/{id}/return` moved: fingerprint `36951a3d486e584e` is now `b67ef4be1f473159`. * Changed. The shape of `POST /v1/notifications/read` moved: fingerprint `8a2764c00a9b2eff` is now `2caff5f56d93231b`. * Changed. The shape of `POST /v1/receipts/{idempotencyKey}/reviewed` moved: fingerprint `a0ed8ccdaa6d377d` is now `1c49d6c798858eeb`. * Changed. The shape of `POST /v1/runs` moved: fingerprint `b5b1404a74c62d0b` is now `a794e5ba193e0d50`. * Changed. The shape of `POST /v1/runs/{runId}/cancel` moved: fingerprint `d54f66ac74a4b546` is now `0b29bc0248a3fadc`. * Changed. The shape of `POST /v1/runs/{runId}/pause` moved: fingerprint `a9ed3cf38c671484` is now `12a9d4ad9f6f4591`. * Changed. The shape of `POST /v1/runs/{runId}/resume` moved: fingerprint `5a2fa0ab35e67afd` is now `c5a6a8605e5a7901`. * Changed. The shape of `POST /v1/webhooks` moved: fingerprint `ec5b86818e0ca15c` is now `fd72dd556d8c8147`. * Changed. The shape of `POST /v1/webhooks/{webhookId}/rotate` moved: fingerprint `f3d57bb5859a0be5` is now `094c35eb0d3028dd`. * Changed. The shape of `POST /v1/webhooks/{webhookId}/test` moved: fingerprint `b03100d84bbd8953` is now `cd748bc5a1faea40`. ### HTTP API and MCP tools, 2026-09-21 * Changed. The shape of `GET /v1/devices/{deviceId}/driving` moved: fingerprint `179853a96bc7a269` is now `71e8df18cc052ca6`. * Changed. The shape of `GET /v1/leases` moved: fingerprint `df5290f50cfb4d05` is now `304ef3aa20c17d05`. * Changed. The shape of `GET /v1/receipts` moved: fingerprint `fa8bac2d8ff98d36` is now `53e1ee2246e304da`. * Changed. The shape of `GET /v1/receipts/{idempotencyKey}` moved: fingerprint `cb8ea7070a3da9af` is now `ecc1bcdd6e08aa09`. * Changed. The shape of `GET /v1/runs` moved: fingerprint `282c36f5cb60c1b2` is now `b5de8bab4434ca34`. * Changed. The shape of `GET /v1/runs/{runId}` moved: fingerprint `2360bc37e6fe00ea` is now `eaefe32c8985fcd6`. * Changed. The shape of `POST /v1/runs` moved: fingerprint `de9f9e6ed85f465f` is now `b5b1404a74c62d0b`. * Changed. The shape of `POST /v1/runs/{runId}/cancel` moved: fingerprint `d1fc111d2b4487e3` is now `d54f66ac74a4b546`. * Changed. The shape of `POST /v1/runs/{runId}/pause` moved: fingerprint `09da7d79d6106e77` is now `a9ed3cf38c671484`. * Changed. The shape of `POST /v1/runs/{runId}/resume` moved: fingerprint `9b794525d6ae97c6` is now `5a2fa0ab35e67afd`. * Added. `POST /v1/copilot/threads/{id}/stop`. ### HTTP API and MCP tools, 2026-09-21 * Changed. The shape of `GET /v1/devices` moved: fingerprint `cd7d995dcdb4f1d5` is now `818fa9f7a8689698`. * Changed. The shape of `GET /v1/devices/{deviceId}` moved: fingerprint `69f8e835f88bff47` is now `3eb025fc71aba5ae`. * Changed. The shape of `GET /vrx/{runToken}/v1/devices` moved: fingerprint `fa80397a26c76602` is now `b9ec62bdc4169b80`. * Changed. The shape of `GET /vrx/{runToken}/v1/devices/{deviceId}/screenshot` moved: fingerprint `a91016de7508d68c` is now `42892550a5111203`. * Changed. The shape of `GET /vrx/{runToken}/v1/health` moved: fingerprint `9b9295bb71d96b39` is now `1312d92abbc2e88b`. * Changed. The shape of `PATCH /v1/devices/{deviceId}` moved: fingerprint `b5a45783a6b6fc51` is now `1514b8906d076807`. * Changed. The shape of `POST /v1/devices/take` moved: fingerprint `ae22b78dd970aa3e` is now `94bad117ddc653dd`. * Changed. The shape of `POST /v1/runs` moved: fingerprint `a6775e75b07ad75b` is now `de9f9e6ed85f465f`. * Changed. The shape of `POST /vrx/{runToken}/v1/devices/{deviceId}/actions` moved: fingerprint `f8c05a19c6ac0526` is now `d52e408e99afcab3`. * Changed. The shape of `POST /vrx/{runToken}/v1/report` moved: fingerprint `b4acfea0169cc81f` is now `760a12de9026ecc6`. ### HTTP API and MCP tools, 2026-09-21 * Changed. `GET /tasks` is renamed to `GET /v1/runs`. Its shape changed as well, so re-pin its fingerprint. Reason given: /tasks -> /v1/runs. * Changed. `GET /runs/{agentRunId}` and `GET /tasks/{taskId}` are now the single route `GET /v1/runs/{runId}`. The shape changed as well, so re-pin the fingerprint. Reasons given: /runs -> /v1/runs; /tasks -> /v1/runs. * Changed. `POST /tasks` is renamed to `POST /v1/runs`. Its shape changed as well, so re-pin its fingerprint. Reason given: /tasks -> /v1/runs. * Changed. `POST /tasks/{taskId}/cancel` is renamed to `POST /v1/runs/{runId}/cancel`. Its shape changed as well, so re-pin its fingerprint. Reason given: /tasks -> /v1/runs. * Changed. `POST /tasks/{taskId}/pause` is renamed to `POST /v1/runs/{runId}/pause`. Its shape changed as well, so re-pin its fingerprint. Reason given: /tasks -> /v1/runs. * Changed. `POST /tasks/{taskId}/resume` is renamed to `POST /v1/runs/{runId}/resume`. Its shape changed as well, so re-pin its fingerprint. Reason given: /tasks -> /v1/runs. * Changed. MCP tool `cancel_task` is renamed to `cancel_run`. Reason given: cancel_task -> cancel_run. * Changed. MCP tool `list_tasks` is renamed to `list_runs`. Reason given: list_tasks -> list_runs. * Changed. MCP tool `resume_task` is renamed to `resume_run`. Reason given: resume_task -> resume_run. * Changed. MCP tool `run_task` is renamed to `start_run`. Reason given: run_task -> start_run. * Changed. MCP tool `task_monitor` is renamed to `get_run`. Reason given: task_monitor -> get_run. * Removed. `DELETE /v1/schedules/{scheduleId}`. Reason given: the six /v1/schedules REST routes are withdrawn before launch and nothing replaces them. * Removed. `GET /v1/schedules`. Reason given: the six /v1/schedules REST routes are withdrawn before launch and nothing replaces them. * Removed. `GET /v1/schedules/{scheduleId}`. Reason given: the six /v1/schedules REST routes are withdrawn before launch and nothing replaces them. * Removed. `PATCH /v1/schedules/{scheduleId}`. Reason given: the six /v1/schedules REST routes are withdrawn before launch and nothing replaces them. * Removed. `POST /v1/schedules`. Reason given: the six /v1/schedules REST routes are withdrawn before launch and nothing replaces them. * Removed. `POST /v1/schedules/{scheduleId}/run`. Reason given: the six /v1/schedules REST routes are withdrawn before launch and nothing replaces them. * Changed. The shape of `DELETE /v1/api-keys/{id}` moved: fingerprint `cec92d1d2bee2f68` is now `8673120cc6b5fc82`. * Changed. The shape of `DELETE /v1/copilot/automation-defaults/{id}` moved: fingerprint `a3a2c758a8813cbe` is now `64d8632363f6dd07`. * Changed. The shape of `DELETE /v1/copilot/threads/{id}` moved: fingerprint `2882dc082cee9dfc` is now `eeafa5b8707c1aa9`. * Changed. The shape of `DELETE /v1/devices/{deviceId}/lease` moved: fingerprint `3805b0e0d7758038` is now `e1550c8338d33ded`. * Changed. The shape of `DELETE /v1/webhooks/{webhookId}` moved: fingerprint `d99dd9ed217b371c` is now `0556a29de20886f3`. * Changed. The shape of `GET /.well-known/oauth-protected-resource` moved: fingerprint `a9df7149bc5b949d` is now `d92f969962990042`. * Changed. The shape of `GET /.well-known/oauth-protected-resource/mcp` moved: fingerprint `a9df7149bc5b949d` is now `d92f969962990042`. * Changed. The shape of `GET /v1/admission` moved: fingerprint `759a7964208858f1` is now `19696235c57fac2a`. * Changed. The shape of `GET /v1/api-keys` moved: fingerprint `6ebb3ade7ddafbac` is now `1e1c4786d5d8c81f`. * Changed. The shape of `GET /v1/billing/upcoming` moved: fingerprint `0a56d3b54f615df8` is now `46e89e8f02075496`. * Changed. The shape of `GET /v1/copilot-allowance` moved: fingerprint `11ba7dbc68ce640c` is now `8c5ff8172b2fab86`. * Changed. The shape of `GET /v1/copilot/automation-defaults` moved: fingerprint `7aded6a8afe1b66a` is now `6829594780b28914`. * Changed. The shape of `GET /v1/copilot/threads` moved: fingerprint `1d1d7ec2434ac491` is now `64c88e0656207256`. * Changed. The shape of `GET /v1/copilot/threads/{id}` moved: fingerprint `a2131f0575aff1cf` is now `f9d845aa07f628ea`. * Changed. The shape of `GET /v1/copilot/threads/{id}/stream` moved: fingerprint `6a833c7bbacdf295` is now `c151083d8fdcdb1b`. * Changed. The shape of `GET /v1/devices` moved: fingerprint `d74625a81ff70da8` is now `cd7d995dcdb4f1d5`. * Changed. The shape of `GET /v1/devices/{deviceId}` moved: fingerprint `123dbc0fb03f4809` is now `69f8e835f88bff47`. * Changed. The shape of `GET /v1/devices/{deviceId}/driving` moved: fingerprint `b442eddcbcfefcac` is now `179853a96bc7a269`. * Changed. The shape of `GET /v1/devices/{deviceId}/screenshot` moved: fingerprint `8e9027d6d574c268` is now `2a1d16fae6e182f8`. * Changed. The shape of `GET /v1/fulfilments` moved: fingerprint `a7bc66f37435f79b` is now `254df8efba6891a8`. * Changed. The shape of `GET /v1/fulfilments/{id}/estimate-history` moved: fingerprint `5ccae923ae2dd3c3` is now `0e6ee682516ce488`. * Changed. The shape of `GET /v1/leases` moved: fingerprint `f0d0bcc2569cc2f3` is now `df5290f50cfb4d05`. * Changed. The shape of `GET /v1/me/notification-preferences` moved: fingerprint `0ddf9b592a7c3a5b` is now `316bf96e0d31b44e`. * Changed. The shape of `GET /v1/notifications` moved: fingerprint `46c7fe2e2b8dc56d` is now `789cd7c5b962dc49`. * Changed. The shape of `GET /v1/receipts` moved: fingerprint `b605221a32491536` is now `fa8bac2d8ff98d36`. * Changed. The shape of `GET /v1/receipts/{idempotencyKey}` moved: fingerprint `bc5b0c46b471de34` is now `cb8ea7070a3da9af`. * Changed. The shape of `GET /v1/skus` moved: fingerprint `66169d32b5376cff` is now `7ab63e3711bff143`. * Changed. The shape of `GET /v1/usage` moved: fingerprint `d636e68e4ac9e0d8` is now `86d4e13938b869bd`. * Changed. The shape of `GET /v1/webhooks` moved: fingerprint `0b7bd0976025cac9` is now `d0c263bb375ef039`. * Changed. The shape of `GET /v1/webhooks/{webhookId}/deliveries` moved: fingerprint `2116bba639c81068` is now `d84cfd45ab723048`. * Changed. The shape of `PATCH /v1/api-keys/{id}` moved: fingerprint `9ed2d3fb558316f8` is now `edb9c26504feff1b`. * Changed. The shape of `PATCH /v1/copilot/automation-defaults` moved: fingerprint `d7827b862ac24b89` is now `472a1c11fefd2582`. * Changed. The shape of `PATCH /v1/copilot/threads/{id}` moved: fingerprint `e167c586f5939d5a` is now `63d6ae4258590c0e`. * Changed. The shape of `PATCH /v1/devices/{deviceId}` moved: fingerprint `997ae27908061b7b` is now `b5a45783a6b6fc51`. * Changed. The shape of `PATCH /v1/devices/{deviceId}/lease` moved: fingerprint `f5f541aec6784082` is now `a8d617b89eb1cd14`. * Changed. The shape of `PATCH /v1/me/notification-preferences` moved: fingerprint `ec7372a2b5c35bd8` is now `f37c032b61f310d0`. * Changed. The shape of `PATCH /v1/webhooks/{webhookId}` moved: fingerprint `e0dd367bc76eb877` is now `8691f4ee94f387b7`. * Changed. The shape of `POST /mcp` moved: fingerprint `db90642df351573c` is now `2402cb5e32b96260`. * Changed. The shape of `POST /v1/api-keys` moved: fingerprint `767a36cc5e5f51f0` is now `d0fd810b97e12a99`. * Changed. The shape of `POST /v1/api-keys/{id}/rotate` moved: fingerprint `df42f0c99b28741b` is now `5598b2313e06918d`. * Changed. The shape of `POST /v1/checkout-sessions` moved: fingerprint `4fdc689adeb901d0` is now `0511c35acce166ca`. * Changed. The shape of `POST /v1/copilot` moved: fingerprint `03b02d41b09322aa` is now `937da5baf857131f`. * Changed. The shape of `POST /v1/copilot/approvals` moved: fingerprint `99c1f4c45e1f8be8` is now `1a9e1b8df732b737`. * Changed. The shape of `POST /v1/copilot/commands` moved: fingerprint `11694194ea4ee022` is now `9111c9715be98d9c`. * Changed. The shape of `POST /v1/devices/take` moved: fingerprint `6f550d9ffe7128de` is now `ae22b78dd970aa3e`. * Changed. The shape of `POST /v1/devices/{deviceId}/actions` moved: fingerprint `ff1deb5da13fb202` is now `eaebdf57ef775c6d`. * Changed. The shape of `POST /v1/devices/{deviceId}/lease` moved: fingerprint `9485e3c14c730ab3` is now `28771d2cd4faaf18`. * Changed. The shape of `POST /v1/devices/{deviceId}/live-session` moved: fingerprint `e97bc5ac3d2f83f8` is now `92b0a414aa237e2f`. * Changed. The shape of `POST /v1/devices/{deviceId}/wake` moved: fingerprint `fcd638fbc11b13db` is now `a14393037d6ac212`. * Changed. The shape of `POST /v1/fulfilments/{id}/cancel` moved: fingerprint `ac0db66e2c13edaa` is now `36951a3d486e584e`. * Changed. The shape of `POST /v1/fulfilments/{id}/return` moved: fingerprint `ac0db66e2c13edaa` is now `36951a3d486e584e`. * Changed. The shape of `POST /v1/notifications/read` moved: fingerprint `7e371b3f018bc203` is now `8a2764c00a9b2eff`. * Changed. The shape of `POST /v1/receipts/{idempotencyKey}/reviewed` moved: fingerprint `47151a0b9864ef3d` is now `a0ed8ccdaa6d377d`. * Changed. The shape of `POST /v1/webhooks` moved: fingerprint `f80ff8ffe463e1df` is now `ec5b86818e0ca15c`. * Changed. The shape of `POST /v1/webhooks/{webhookId}/rotate` moved: fingerprint `3eb1402b871d1adb` is now `f3d57bb5859a0be5`. * Changed. The shape of `POST /v1/webhooks/{webhookId}/test` moved: fingerprint `838d2f9c2ac3c257` is now `b03100d84bbd8953`. * Added. MCP tool `pause_run`. ## Changes the fingerprints cannot see ### Webhook payloads and copilot approvals, 2026-09-25 Changed. On the `run.ended` webhook, the field that carries the run's own handle is named `runId`. It was `taskId`. A receiver reading `taskId` now reads nothing: the field is absent rather than empty, so a strict parser fails and a lenient one records an undefined id. `agentRunId`, the shareable id beside it, is unchanged. See [Webhooks](/guides/webhooks) for the full payload. Changed. In the copilot, the approval reason code for starting a run is `start_run`. It was `run_task`. It is the value of `reason.code` on an approval card, and the value an answer echoes back when it echoes one. The other three codes are unchanged. Nothing rejects the old spelling loudly, so a client that switches on this code will quietly draw its fallback card for a run it should be naming. Changed. `GET /v1/receipts` and `GET /v1/receipts/:idempotencyKey` no longer carry `userId` or `viaCopilot` at the top level of a receipt. Read `actor.userId` and `actor.viaCopilot`, which carry the same values. The `Receipt` schema never declared the two top-level fields, so no fingerprint moved. ## Other ways to find out what moved An entry above tells you that a shape moved and when it was published. Three things tell you more. * **Read the generated references for what the surface is today.** The [API reference](/api) and the [tool reference](/mcp/reference) are produced from the source the server registers, so they cannot describe something that does not exist or leave out something that does. They are regenerated and republished with this site. * **Pin the contract fingerprints to find out when a shape you parse moves.** That is a mechanism you can wire into your own pipeline today, and it is stronger than watching a page, because it fails your build rather than waiting to be read. See [Versioning and compatibility](/api/versioning#pin-the-shape-you-parse). * **Read [Versioning and compatibility](/api/versioning)** for what we do and do not promise about `/v1`, stated plainly, including the policy for breaking changes after launch. ## Command line interface ### 0.7.0 Removed. `phoneuse mcp --stdio --local` and `phoneuse rows` are gone, and `PHONEUSE_TENANCY`, `PHONEUSE_DEVICE_ROWS` or a device rows file no longer change where `phoneuse mcp --stdio` goes: it always relays to your cloud phones. ### 0.6.0, 2026-10-22 Changed. Robot backends and robot-only MCP fields are removed, and login works after starting `phoneuse mcp --stdio`. ### 0.5.1, 2026-10-19 Fixed. `phoneuse screenshot` on a phone your organization does not hold now says it is a watch-only picture that cannot aim a tap, instead of printing "frameId undefined (sequence undefined, captured undefined)". ### 0.5.0, 2026-10-15 Changed. `phoneuse mcp --stdio` now gives a stdio-only MCP client your cloud phones: it relays to `https://mcp.phoneuse.com/mcp` with the key `phoneuse login` stored. Before, it only served phones attached to your own machine. `--local` keeps that, and any local setting you already made (`PHONEUSE_TENANCY`, `PHONEUSE_DEVICE_ROWS`, `PHONEUSE_DEVICE_ROWS_PATH` or a device rows file) still selects it on its own. Added. `phoneuse runs show|resume|cancel `. A run that stops at `needs_user_control` keeps the phone until it is resumed or canceled, and the CLI had no way to do either. Added. The CLI accepts API keys that start with `puk_` as well as `pbk_`, in `PHONEUSE_API_KEY`, `phoneuse login --with-key` and a saved login. Changed. `phoneuse run` without `--executor` lets PhoneUse drive the run when you signed in with `phoneuse login`. A key from `PHONEUSE_API_KEY` keeps the server's default, `self_hosted`. Changed. `apps library capabilities` and `apps library check` print a table unless you pass `--json`; `check` leaves out protected system packages and says when the list may be out of date. A mistyped command prints its own usage line instead of the whole index, and refusals for a missing lease, `ui` on a cloud phone and `open` of an app that is not there name the command to run next. Install this release with `npm install -g @phoneuse/cli@0.5.0`. ### 0.4.0, 2026-10-07 Added. The first PhoneUse release is published as [`@phoneuse/cli@0.4.0`](https://www.npmjs.com/package/@phoneuse/cli/v/0.4.0) and installs the `phoneuse` command. It defaults to `https://mcp.phoneuse.com`; `phoneuse login` opens the PhoneUse console to approve an API key for your organization. Existing `PHONEBASE_*` environment variables, credential storage and API identifiers remain supported. Install this release with `npm install -g @phoneuse/cli@0.4.0`. `npm view @phoneuse/cli time --json` reports npm's publication times. ### Legacy package history The entries below retain the command names and server origins of their historical releases. Use [CLI installation](/cli/installation) for the current PhoneUse package and endpoints. The legacy CLI was published to npm as `phonebase`, and its version is the npm package's version. Every date below is the publish time npm recorded, so `npm view phonebase time --json` checks this section without you having to trust this page. ### 0.3.0, not yet published This entry is written ahead of the publish and carries no date yet. Backfill it when `publish-cli` has run. Added. `phonebase login` logs the CLI in without copying a key by hand. It prints a link and a short code and opens your browser; approve the request in the console and the terminal receives a new API key for your organization, named after the computer, and stores it in the macOS Keychain, the Linux Secret Service, or a file only you can read. `phonebase login --with-key` stores a key you already have after the server confirms it. `phonebase whoami` shows the organization, key id, scopes and expiry of the key in use and where it came from. `phonebase logout` revokes the stored key and removes it from the machine. Changed. Commands talk to the hosted control plane, `https://mcp.phonebase.co`, unless `--server` says otherwise. They used to default to `http://127.0.0.1:8788`, so a command against a control plane on your own machine now needs `--server http://127.0.0.1:8788`, or `PHONEBASE_SERVER=http://127.0.0.1:8788` set once in the shell. `PHONEBASE_API_KEY` still takes precedence over a stored login, so CI keeps working unchanged. Security. `PHONEBASE_DEV_TOKEN` is now sent only to a loopback server. A command that would have sent it anywhere else refuses and says how to target a local control plane or log in to the hosted one. Also in 0.3.0. These changes were prepared as 0.2.2, which was never published; they ship in 0.3.0 instead. Added. `phonebase --help` now answers about that command: its usage line, what each positional argument takes, the flags it reads and one runnable example. Until now `--help` was read before the command word was, so all sixteen commands printed the same index, and `phonebase swipe --help` listed the signature without saying which of the two coordinate pairs the gesture starts from. Breaking, in a patch release, and called that rather than "changed": a script on 0.2.1 that ran `phonebase rows list --server ...` exited 0 and now exits 2. A flag a command does not read is now a usage error and exits 2, which is what a misspelled flag already did. `phonebase devices --lease X` and `phonebase doctor --json` used to be accepted in full and then ignored, so there was no way to tell a flag that had taken effect from one that had not. `--server` counts as one of these on `phonebase rows` and `phonebase mcp`: neither talks to a control plane. `--help` and `--version` remain accepted everywhere, because they ask about the CLI rather than about a command. Fixed. `phonebase run --watch` on a `self_hosted` run now prints the worker URL once, to an interactive terminal, before it starts watching. It used to print nothing, so the worker had no way to reach the run and the run stayed `queued` until its deadline. Where the URL has no safe place to go, `--json` or a stderr that is not a terminal, `--executor self_hosted --watch` is refused before anything starts, and a run your credential's default made `self_hosted` is canceled at once with the remedy named. Fixed. `phonebase run` without `--watch` no longer suggests `phonebase run ... --watch` to follow the run, because that command starts a new run. It names `GET /v1/runs/` and the `get_run` tool instead. ### 0.2.1, 2026-09-21 Fixed. Every command works again. `0.2.0` installed from npm and did nothing: `phonebase --help`, `--version`, `doctor` and `devices` each exited 0 having printed nothing at all. The entry guard decided whether it had been started as a program by testing whether `argv[1]` ended in `main.js`, and npm installs a bin as a symlink named `phonebase`, so on every installed copy the answer was no and the program never ran. Running it out of a checkout was unaffected, which is why it reached the registry. If you installed `0.2.0`, upgrade; there is nothing to un-do, because it never did anything. ### 0.2.0, 2026-09-21 Withdrawn in favour of 0.2.1: as published, no command produced any output. The changes below were in it and are in 0.2.1. Security. `phonebase run` no longer writes the run's worker URL, which carries the run token, to a stderr nobody is watching: when stderr is not a terminal and neither `--json` nor `--watch` was given, the command is refused before a run starts. Every earlier version is affected. Added. Seven commands: `swipe`, `long-press`, `type`, `key`, `open`, `ui` and `renew`, so a lease no longer expires under you and every gesture the service offers can be sent from a terminal. `phonebase run` also prints the step budget and deadline the run was actually given. Added. `phonebase doctor` has an `auth` row, which passes only when a key is set and listing devices with it succeeds, and otherwise says whether no key was set, the key was rejected, or something else failed. Changed. A remote control plane refusing your credential now reads `not authenticated: set PHONEBASE_API_KEY` instead of saying the control plane cannot be reached. `phonebase doctor` exits 1 on node 20 or 21, which the package never supported. ### 0.1.3, 2026-09-02 Docs. The README on the package page documents `--version`. ### 0.1.2, 2026-09-02 Added. `phonebase --version` prints the CLI's own version, and asks nothing of the network to do it. The package also carries its license file from this release onwards, so the terms are in the tarball rather than only named by it. ### 0.1.1, 2026-09-02 Fixed. A link in the README on the package page pointed at a documentation page that does not exist. ### 0.1.0, 2026-09-02 Added. First published release of the CLI. See [Installation](/cli/installation). ## Before this record The first artifact this page can date is the CLI release above. Changes made before 2026-09-02 are not listed, because there is no published thing to date them against, and a list assembled from memory is the kind of changelog that is worse than none. # CLI in CI Source: https://docs.phoneuse.com/cli/ci-cd How to run the CLI in your own pipeline, and what ours does with it today. This page has two halves. The first states what our own pipeline runs today, so you can see the CLI used in a real one. The second is guidance for putting it into yours. The pipeline examples below target [`@phoneuse/cli@0.6.0`](https://www.npmjs.com/package/@phoneuse/cli/v/0.6.0), the current release on npm, and run the `phoneuse` command. Node 22 or newer is required. The [REST API example](/cli/installation#use-phoneuse-now) and [MCP quickstart](/quickstart) are also available. ## What this repository's CI runs today On every pull request and on pushes to the trunk, CI checks the source, regenerates the documentation and verifies that generated files match. Its CLI checks include: ```bash theme={null} corepack pnpm typecheck corepack pnpm check:docs corepack pnpm gen:docs git diff --exit-code corepack pnpm check:content corepack pnpm build corepack pnpm pack:cli corepack pnpm check:packed-cli corepack pnpm test ``` The workflow also runs contract, database and integration checks. For the CLI, these steps establish the following: * **The docs regenerate and the tree must not move.** `gen:docs` rebuilds the reference pages from the code, and `git diff --exit-code` fails if that produced any change. A tool, scope, error code, route or CLI command that changed without a regeneration turns this red. It is the only thing stopping these pages from quietly describing an older surface. * **The staged CLI is executed through its installed binary.** `check:packed-cli` installs the staged package into a temporary directory and checks that its binary produces output. This catches a broken package entry point that running the source alone would miss. It does not control a real device or prove a customer's installation works. * **An end to end script exercises the whole sequence.** `corepack pnpm e2e:cli` starts a control plane and a stand in device, then runs the full sequence from registering a row through acquiring, observing, acting and releasing, plus the negative cases. It is run on demand rather than on every commit. Documentation publishing is a separate workflow. It is decoupled from this one on purpose, so that fixing a typo does not rebuild the application. Releasing the CLI to npm is a third workflow, and it is manual: someone dispatches it, and it publishes the version currently written into the source. It runs the typecheck, the unit tests, the build and the packed CLI check, and it refuses a version that is already on the registry. The first scoped release used the owner's authenticated npm session. npm now trusts this repository and this workflow as the package's publisher, so later releases publish from the workflow without a personal npm login. Each workflow dispatch remains a separate release decision. ## Using the CLI in your own pipeline Nothing above stops you from running it. These are the constraints that actually apply. ### Install the npm package Pin the package version so your runner uses the release you tested: ```bash theme={null} npm install -g @phoneuse/cli@0.6.0 phoneuse --version ``` ### Optional: run from a checkout If your runner has authorized access to the private repository, use a reviewed repository revision, install its locked dependencies and run the source entry point: ```bash theme={null} corepack pnpm install --frozen-lockfile corepack pnpm cli --version ``` From that checkout, substitute `corepack pnpm cli` for `phoneuse` in the examples below. ### Authenticate from the environment A runner has nobody to approve `phoneuse login`, so put an API key in a secret and export it. `PHONEUSE_API_KEY` takes precedence over any key a login stored, and the CLI never reads a credential from a flag, so a key cannot leak into a command line that a build log echoes. ```bash theme={null} export PHONEUSE_API_KEY="$PHONEUSE_API_KEY" phoneuse whoami phoneuse devices --json ``` The hosted control plane, `https://mcp.phoneuse.com`, is the default; pass `--server `, or set `PHONEUSE_SERVER`, for any other. The server must be `https` unless it is loopback. Sending a credential in the clear to a remote host is refused rather than warned about. ### Give the key only what the job needs Issue a separate key per pipeline, scoped to what that pipeline does and, if the job only ever touches one device, narrowed to that device. A key restricted to a subset cannot see the rest of the fleet, so a mistake in a script cannot reach a device the job was never meant to touch. See [Authentication](/mcp/auth). ### Release what you acquire A lease is exclusive, and a job that exits without releasing blocks the next one until the lease expires on its own. Release in whatever your runner calls a cleanup step, not on the happy path. ```bash theme={null} LEASE=$(phoneuse acquire "$DEVICE" --json | jq -r .leaseId) trap 'phoneuse release "$DEVICE" "$LEASE" >/dev/null 2>&1 || true' EXIT ``` Releasing a device you no longer hold is a no operation, so the trap is safe even when the lease already expired. ### Parse the machine readable output Use `--json` for anything a script reads. It prints the structured result the tool returned, whose shape is published in the [tool reference](/mcp/reference). The default human summary is written for a person and is free to change. ### Expect to queue A device holds one lease at a time, so a job may wait for a device rather than getting one immediately. Build for that: fail the step with a clear message rather than retrying an acquire in a tight loop. ### Watch a run to completion If your job hands a goal to the agent tier rather than driving each step, `run` returns a run id immediately. Pass `--watch` to poll until the run reaches a terminal state, and the exit code follows the outcome. ```bash theme={null} phoneuse run "$DEVICE" "open settings" --lease "$LEASE" --executor phoneuse --watch --json ``` Name `--executor phoneuse` in CI to let PhoneUse drive the run. An API key's default executor is `self_hosted`, which needs your own worker and a worker URL that a CI log must not hold. `--watch --json` refuses an explicit `self_hosted` run before starting it. If the server's default makes a run `self_hosted`, the CLI tries to cancel it and exits 2. If cancellation fails, it names the run so you can cancel it through the API. `--max-steps` can only lower the budget. The control plane's own ceiling cannot be raised from a client. See [Runs](/agent/runs). ## Do not run two control planes over one device set Worth stating because CI is where it happens. Two control plane processes over the same devices would each keep their own view of who holds a lease and could hand the same physical device to two callers. The receipt ledger is locked by a single process, so the second one refuses to start rather than racing the first. If a job needs its own control plane, give it its own devices, or its own ledger path. # Commands Source: https://docs.phoneuse.com/cli/commands Every CLI command, its arguments and its options. The `@phoneuse/cli` npm package installs the `phoneuse` command. See [installation](/cli/installation) for the release target, availability check, login and optional source instructions. The CLI is a thin client over the same control plane the agent surface uses, with 20 commands. The same program also runs from an existing checkout: `corepack pnpm cli ` during development, or `node dist/cli/main.js ` after `corepack pnpm build`. See [installation](/cli/installation) for the details. Bad input never crashes the CLI: it prints the usage block and exits 2, and that includes a flag used on a command that does not read it. `phoneuse --help` lists every command; `phoneuse --help` prints that one command's arguments, flags and an example. Both come from the same table this page is generated from, so the terminal and this page cannot disagree. ## Commands | Command | What it does | | - | - | | [`apps`](#phoneuse-apps) | Inspect phone app inventory, refresh it, and recover an original request. To install an app, use the Apps page in the Console ([https://console.phoneuse.com/apps](https://console.phoneuse.com/apps)). | | [`login`](#phoneuse-login) | Log in from this terminal: approve the request in the console and the CLI stores a new API key for your organization in the system keychain. Run it again whenever you need a new key. | | [`whoami`](#phoneuse-whoami) | Show the organization, key id, scopes and expiry of the key this CLI sends, and where that key came from. | | [`logout`](#phoneuse-logout) | Revoke the key phoneuse login stored and remove it from this machine. A key in PHONEUSE_API_KEY is left alone. Keys can also be deleted on the console's Keys page. | | [`devices`](#phoneuse-devices) | List every device your org can see, with its status and capabilities. | | [`acquire`](#phoneuse-acquire) | Claim exclusive use of a device and print the lease it returns. | | [`renew`](#phoneuse-renew) | Push a lease's expiry back before it runs out, keeping the same lease id. A lease that expires mid-session strands whatever you were doing, so renew it rather than acquiring again. | | [`release`](#phoneuse-release) | Give a device back by the lease id acquire returned. | | [`tap`](#phoneuse-tap) | Tap one point on a device. | | [`swipe`](#phoneuse-swipe) | Drag from one point to another on a device: scroll a list, pull a sheet down, page sideways. | | [`long-press`](#phoneuse-long-press) | Press and hold one point on a device, for the context menus and drag handles a tap never opens. | | [`type`](#phoneuse-type) | Type text into whatever input the device has focused. Focus it first: this types, it does not aim. | | [`key`](#phoneuse-key) | Press one of the phone's own keys on a device: home, back, enter, delete, app_switch, power, volume_up, volume_down. | | [`open`](#phoneuse-open) | Launch an app on a device by its OS-level id, instead of tapping through a home screen to find it. | | [`screenshot`](#phoneuse-screenshot) | Capture a device's screen and write the image to a file. | | [`ui`](#phoneuse-ui) | Print the device's UI tree, the text-and-elements view a screenshot cannot give you. The tree goes to stdout and its metadata to stderr, so redirecting the output leaves a clean file. Cloud phones do not provide a UI tree; use screenshot there. | | [`doctor`](#phoneuse-doctor) | Check this machine: node version, the credential in use and control-plane reachability. | | [`mcp`](#phoneuse-mcp) | Give a stdio-only MCP client (Claude Desktop, Cursor) your cloud phones: it relays to the hosted MCP with the key phoneuse login stored. | | [`run`](#phoneuse-run) | Start an agent run on a device for one natural-language goal. PhoneUse drives it for you; with --executor self_hosted nothing happens on the device until your own worker connects to the run's VisualRemote base url. | | [`runs`](#phoneuse-runs) | Check, continue or stop a run by its id. A run that stops at needs_user_control waits for a person: do what it asks on the phone, then resume it, or cancel it to free the phone for another run. | ## Global options These apply wherever they make sense rather than to one command. | Option | Description | | - | - | | `--server ` | Control-plane base URL. Default: PHONEUSE_SERVER if set, else `https://mcp.phoneuse.com`. A control plane on this machine is [http://127.0.0.1:8788](http://127.0.0.1:8788) | | `-h, --help` | Print the usage block and exit 0. | | `--version` | Print the CLI version and exit 0. | Authentication: run `phoneuse login` once and the CLI stores an API key for that `--server` in the system keychain, or a private credentials file when a keychain is unavailable. `PHONEUSE_API_KEY` overrides the stored key, which is what CI and scripts use; `PHONEUSE_DEV_TOKEN` is sent only to a control plane on your own machine (a loopback `--server`). ## phoneuse apps Inspect phone app inventory, refresh it, and recover an original request. To install an app, use the Apps page in the Console ([https://console.phoneuse.com/apps](https://console.phoneuse.com/apps)). ```bash theme={null} phoneuse apps library capabilities [--json] [--cursor ] [--limit ] phoneuse apps library check [packageName] [--json] [--cursor ] [--limit ] [--device-id ] [--scope ] phoneuse apps library refresh [packageName] [--json] [--request-id ] --targets phoneuse apps library refresh-status [--json] phoneuse apps library refresh-results [--json] [--cursor ] [--limit ] phoneuse apps library request [--json] ``` **`phoneuse apps library capabilities`** | Option | Required | Description | | - | - | - | | `--json` | no | Print the machine-readable structuredContent instead of a summary | | `--cursor ` | no | Opaque page cursor from the same query. | | `--limit ` | no | Page size, 1 to 100. | ```bash theme={null} phoneuse apps library capabilities --json ``` **`phoneuse apps library check`** | Argument | Description | | - | - | | `[packageName]` | Optional package filter; omit to inspect all user apps in the selected scope. | | Option | Required | Description | | - | - | - | | `--json` | no | Print the machine-readable structuredContent instead of a summary | | `--cursor ` | no | Opaque page cursor from the same query. | | `--limit ` | no | Page size, 1 to 100. | | `--device-id ` | no | Filter inventory by this visible device. | | `--scope ` | no | Actual scope ID from device capabilities. | ```bash theme={null} phoneuse apps library check --json ``` **`phoneuse apps library refresh`** | Argument | Description | | - | - | | `[packageName]` | Optional package filter; omit to inspect all user apps in the selected scope. | | Option | Required | Description | | - | - | - | | `--json` | no | Print the machine-readable structuredContent instead of a summary | | `--request-id ` | no | Stable inventory refresh key. After a lost response, query the original request instead of resubmitting | | `--targets ` | yes | Explicit comma-separated deviceId:scopeId pairs. | ```bash theme={null} phoneuse apps library refresh --targets cloud-phone-01:user_0 --request-id inventory-42 --json ``` **`phoneuse apps library refresh-status`** | Argument | Description | | - | - | | `` | Original refresh or request identifier. | | Option | Required | Description | | - | - | - | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse apps library refresh-status original_01 --json ``` **`phoneuse apps library refresh-results`** | Argument | Description | | - | - | | `` | Original refresh or request identifier. | | Option | Required | Description | | - | - | - | | `--json` | no | Print the machine-readable structuredContent instead of a summary | | `--cursor ` | no | Opaque page cursor from the same query. | | `--limit ` | no | Page size, 1 to 100. | ```bash theme={null} phoneuse apps library refresh-results original_01 --json ``` **`phoneuse apps library request`** | Argument | Description | | - | - | | `` | Original refresh or request identifier. | | Option | Required | Description | | - | - | - | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse apps library request original_01 --json ``` ## phoneuse login Log in from this terminal: approve the request in the console and the CLI stores a new API key for your organization in the system keychain. Run it again whenever you need a new key. ```bash theme={null} phoneuse login [--no-browser] [--with-key] ``` | Option | Required | Description | | - | - | - | | `--no-browser` | no | Print the login page and code without trying to open a browser (also skipped over SSH, in CI and without a terminal) | | `--with-key` | no | Store an existing API key read from stdin instead of pairing with the console. The server checks it first | ```bash theme={null} phoneuse login ``` ## phoneuse whoami Show the organization, key id, scopes and expiry of the key this CLI sends, and where that key came from. ```bash theme={null} phoneuse whoami [--json] ``` | Option | Required | Description | | - | - | - | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse whoami ``` ## phoneuse logout Revoke the key phoneuse login stored and remove it from this machine. A key in PHONEUSE_API_KEY is left alone. Keys can also be deleted on the console's Keys page. ```bash theme={null} phoneuse logout ``` Takes no arguments or options. ```bash theme={null} phoneuse logout ``` ## phoneuse devices List every device your org can see, with its status and capabilities. ```bash theme={null} phoneuse devices [--json] ``` | Option | Required | Description | | - | - | - | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse devices --json ``` ## phoneuse acquire Claim exclusive use of a device and print the lease it returns. ```bash theme={null} phoneuse acquire [--json] ``` | Argument | Description | | - | - | | `` | Device id, as printed by `phoneuse devices`. | | Option | Required | Description | | - | - | - | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse acquire cloud-phone-01 ``` ## phoneuse renew Push a lease's expiry back before it runs out, keeping the same lease id. A lease that expires mid-session strands whatever you were doing, so renew it rather than acquiring again. ```bash theme={null} phoneuse renew [leaseId] [--json] ``` | Argument | Description | | - | - | | `` | Device id, as printed by `phoneuse devices`. | | `[leaseId]` | Optional: the lease your organization holds is the one renewed. The renewal returns the same id with a later expiry. | | Option | Required | Description | | - | - | - | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse renew cloud-phone-01 ``` ## phoneuse release Give a device back by the lease id acquire returned. ```bash theme={null} phoneuse release [--json] ``` | Argument | Description | | - | - | | `` | Device id, as printed by `phoneuse devices`. | | `` | The lease id acquire printed. | | Option | Required | Description | | - | - | - | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse release cloud-phone-01 lease_9f2c8d14 ``` ## phoneuse tap Tap one point on a device. ```bash theme={null} phoneuse tap [--lease ] [--json] ``` | Argument | Description | | - | - | | `` | Device id, as printed by `phoneuse devices`. | | `` | Horizontal position in the 0-1000 grid. | | `` | Vertical position in the 0-1000 grid. | | Option | Required | Description | | - | - | - | | `--lease ` | no | Optional lease id from acquire. Leave it out: the command acts under the lease your organization holds, and a gesture or run takes the device for you when it holds none | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse tap cloud-phone-01 500 620 ``` ## phoneuse swipe Drag from one point to another on a device: scroll a list, pull a sheet down, page sideways. ```bash theme={null} phoneuse swipe [--lease ] [--duration-ms ] [--json] ``` | Argument | Description | | - | - | | `` | Device id, as printed by `phoneuse devices`. | | `` | Horizontal position the gesture starts at, in the 0-1000 grid. | | `` | Vertical position the gesture starts at, in the 0-1000 grid. | | `` | Horizontal position the gesture ends at, in the 0-1000 grid. | | `` | Vertical position the gesture ends at, in the 0-1000 grid. | | Option | Required | Description | | - | - | - | | `--lease ` | no | Optional lease id from acquire. Leave it out: the command acts under the lease your organization holds, and a gesture or run takes the device for you when it holds none | | `--duration-ms ` | no | How long the gesture lasts, in milliseconds, both bounds inclusive: 1-10000 for a swipe, 200-10000 for a long press. Omitting it sends no duration at all, which lets the server pick: a long press holds for 800ms, and a swipe takes the default of whichever backend drives the device. A value outside the range is a usage error and exits 2 without touching the device | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse swipe cloud-phone-01 500 800 500 200 --duration-ms 400 ``` ## phoneuse long-press Press and hold one point on a device, for the context menus and drag handles a tap never opens. ```bash theme={null} phoneuse long-press [--lease ] [--duration-ms ] [--json] ``` | Argument | Description | | - | - | | `` | Device id, as printed by `phoneuse devices`. | | `` | Horizontal position in the 0-1000 grid. | | `` | Vertical position in the 0-1000 grid. | | Option | Required | Description | | - | - | - | | `--lease ` | no | Optional lease id from acquire. Leave it out: the command acts under the lease your organization holds, and a gesture or run takes the device for you when it holds none | | `--duration-ms ` | no | How long the gesture lasts, in milliseconds, both bounds inclusive: 1-10000 for a swipe, 200-10000 for a long press. Omitting it sends no duration at all, which lets the server pick: a long press holds for 800ms, and a swipe takes the default of whichever backend drives the device. A value outside the range is a usage error and exits 2 without touching the device | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse long-press cloud-phone-01 500 620 --duration-ms 1200 ``` ## phoneuse type Type text into whatever input the device has focused. Focus it first: this types, it does not aim. ```bash theme={null} phoneuse type [--lease ] [--json] ``` | Argument | Description | | - | - | | `` | Device id, as printed by `phoneuse devices`. | | `` | The text to type. The whole tail is the text, so a sentence needs no quoting, though the shell still eats its own metacharacters. A backend may refuse characters it cannot inject. | | Option | Required | Description | | - | - | - | | `--lease ` | no | Optional lease id from acquire. Leave it out: the command acts under the lease your organization holds, and a gesture or run takes the device for you when it holds none | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse type cloud-phone-01 tuesday at four ``` ## phoneuse key Press one of the phone's own keys on a device: home, back, enter, delete, app_switch, power, volume_up, volume_down. ```bash theme={null} phoneuse key [--lease ] [--json] ``` | Argument | Description | | - | - | | `` | Device id, as printed by `phoneuse devices`. | | `` | Which key to press, from the fixed set the whole fleet shares. An unknown name is a usage error naming the set; a known name the device does not support is refused by the device. | | Option | Required | Description | | - | - | - | | `--lease ` | no | Optional lease id from acquire. Leave it out: the command acts under the lease your organization holds, and a gesture or run takes the device for you when it holds none | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse key cloud-phone-01 back ``` ## phoneuse open Launch an app on a device by its OS-level id, instead of tapping through a home screen to find it. ```bash theme={null} phoneuse open [--lease ] [--json] ``` | Argument | Description | | - | - | | `` | Device id, as printed by `phoneuse devices`. | | `` | Android package name or iOS bundle id, e.g. com.android.settings. | | Option | Required | Description | | - | - | - | | `--lease ` | no | Optional lease id from acquire. Leave it out: the command acts under the lease your organization holds, and a gesture or run takes the device for you when it holds none | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse open cloud-phone-01 com.android.settings ``` ## phoneuse screenshot Capture a device's screen and write the image to a file. ```bash theme={null} phoneuse screenshot [--lease ] [-o ] [--json] ``` | Argument | Description | | - | - | | `` | Device id, as printed by `phoneuse devices`. | | Option | Required | Description | | - | - | - | | `--lease ` | no | Optional lease id from acquire. Leave it out: the command acts under the lease your organization holds, and a gesture or run takes the device for you when it holds none | | `-o, --out ` | no | Screenshot output path (default ./screenshot-\-\.\) | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse screenshot cloud-phone-01 -o screen.png ``` ## phoneuse ui Print the device's UI tree, the text-and-elements view a screenshot cannot give you. The tree goes to stdout and its metadata to stderr, so redirecting the output leaves a clean file. Cloud phones do not provide a UI tree; use screenshot there. ```bash theme={null} phoneuse ui [--lease ] [--json] ``` | Argument | Description | | - | - | | `` | Device id, as printed by `phoneuse devices`. | | Option | Required | Description | | - | - | - | | `--lease ` | no | Optional lease id from acquire. Leave it out: the command acts under the lease your organization holds, and a gesture or run takes the device for you when it holds none | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse ui cloud-phone-01 > tree.json ``` ## phoneuse doctor Check this machine: node version, the credential in use and control-plane reachability. ```bash theme={null} phoneuse doctor ``` Takes no arguments or options. ```bash theme={null} phoneuse doctor ``` ## phoneuse mcp Give a stdio-only MCP client (Claude Desktop, Cursor) your cloud phones: it relays to the hosted MCP with the key phoneuse login stored. ```bash theme={null} phoneuse mcp --stdio ``` | Option | Required | Description | | - | - | - | | `--stdio` | yes | Serve MCP over stdin/stdout. `phoneuse mcp` accepts nothing else. | ```bash theme={null} phoneuse mcp --stdio ``` ## phoneuse run Start an agent run on a device for one natural-language goal. PhoneUse drives it for you; with --executor self_hosted nothing happens on the device until your own worker connects to the run's VisualRemote base url. ```bash theme={null} phoneuse run [--lease ] [--max-steps N] [--executor phoneuse|self_hosted] [--watch] [--json] ``` | Argument | Description | | - | - | | `` | Device id, as printed by `phoneuse devices`. | | `` | What to accomplish, in plain words. The whole tail is the goal. | | Option | Required | Description | | - | - | - | | `--lease ` | no | Optional lease id from acquire. Leave it out: the command acts under the lease your organization holds, and a gesture or run takes the device for you when it holds none | | `--max-steps ` | no | Ceiling on metered steps for a run (capped by the server's own limit) | | `--executor ` | no | Who drives a run: phoneuse (PhoneUse runs it for you, no worker url) or self_hosted (your worker drives it through the url printed once). Default: phoneuse when you signed in with phoneuse login, self_hosted for PHONEUSE_API_KEY | | `--watch` | no | Poll a run to a terminal state instead of returning its id. From 0.3.0: a self_hosted run's worker url is printed once, and only to an interactive terminal; with --json or a non-terminal stderr a self_hosted run is refused or canceled, exit 2. On 0.2.1, an API key without --executor gets a self_hosted run that --watch leaves queued until its deadline | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse run cloud-phone-01 open settings and report the android version --max-steps 12 ``` ## phoneuse runs Check, continue or stop a run by its id. A run that stops at needs_user_control waits for a person: do what it asks on the phone, then resume it, or cancel it to free the phone for another run. ```bash theme={null} phoneuse runs show [--json] phoneuse runs resume [--json] phoneuse runs cancel [--json] ``` **`phoneuse runs show`** | Argument | Description | | - | - | | `` | The run id phoneuse run printed. | | Option | Required | Description | | - | - | - | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse runs show task_0123 ``` **`phoneuse runs resume`** | Argument | Description | | - | - | | `` | A run that is paused or waiting at needs_user_control. | | Option | Required | Description | | - | - | - | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse runs resume task_0123 ``` **`phoneuse runs cancel`** | Argument | Description | | - | - | | `` | The run to stop. The phone is free for another run afterwards. | | Option | Required | Description | | - | - | - | | `--json` | no | Print the machine-readable structuredContent instead of a summary | ```bash theme={null} phoneuse runs cancel task_0123 ``` # Installation Source: https://docs.phoneuse.com/cli/installation Install the PhoneUse CLI from npm, log in, and check your connection. ## Install from npm These instructions target version [`0.6.0`](https://www.npmjs.com/package/@phoneuse/cli/v/0.6.0) of [`@phoneuse/cli`](https://www.npmjs.com/package/@phoneuse/cli), the current release on npm. The package requires Node 22 or newer and installs the `phoneuse` command: ```bash theme={null} npm install -g @phoneuse/cli@0.6.0 phoneuse --version ``` The version command should print the version on the install line. CLI [0.5.0](https://www.npmjs.com/package/@phoneuse/cli/v/0.5.0) and later accept API keys that start with `pbk_` or `puk_`; the older [0.4.1](https://www.npmjs.com/package/@phoneuse/cli/v/0.4.1) accepts only `pbk_`. ## Use PhoneUse now You can sign in at [console.phoneuse.com](https://console.phoneuse.com/sign-in) and work in your organization without installing the CLI. For an integration, follow the [MCP quickstart](/quickstart) or use the REST API with an existing API key that has `devices:read`: ```bash theme={null} curl -sS https://mcp.phoneuse.com/v1/devices \ -H "Authorization: Bearer $PHONEUSE_API_KEY" ``` Set `PHONEUSE_API_KEY` to your key through your normal secret store. If you need a key, follow [Getting a key](/mcp/auth#getting-a-key). This request lists the devices your key can see; it does not acquire a lease or drive a device. ## Log in After installation, run: ```bash theme={null} phoneuse login ``` `phoneuse login` prints a link and a short code and opens your browser. Sign in to the console, check that the page shows the same code, and approve. The terminal then prints the organization you logged in to, the id of the key it received and when that key expires. No browser on this machine, or connected over SSH? Open the link on any other device where you are signed in; the terminal waits until the printed code expires. > [!NOTE] > > For a run that PhoneUse drives, pass `--executor phoneuse`. A `self_hosted` > run needs your own worker; scripts should pass `--executor phoneuse` with > `--watch --json`. > See [CLI in CI](/cli/ci-cd) for handling runs in scripts and the > [changelog](/changelog) for release history. > [!NOTE] > > Running the CLI gives you the client, not access. `phoneuse login` needs > a console account in an organization. Create one yourself at > [console.phoneuse.com/sign-up](https://console.phoneuse.com/sign-up); your > organization is created during sign-up. Nothing on this surface requires the > CLI, so if you are integrating rather than operating, start at > [Quickstart](/quickstart) and treat this page as optional. ## Logging in What `phoneuse login` gives you is an ordinary API key for your organization, the same kind the console's `/keys` screen mints, named after this computer so you can find it there. It is stored in the system keychain: the macOS Keychain, or the Secret Service through `secret-tool` on Linux. Where neither is available it goes to `~/.config/phoneuse/credentials.json`, readable only by you. The CLI never prints it. ```bash theme={null} phoneuse whoami # organization, key id, scopes, expiry, and where the key came from phoneuse logout # revoke the key on the server and forget it here ``` Need a new key, say after it expired or on a new machine? Run `phoneuse login` again. You can also delete any key from the [console's Keys page](https://console.phoneuse.com/keys); `logout` does both halves for the key this machine holds, and if the server cannot be reached it still forgets the key here and tells you it is still live, so you can delete it in the console. Already have a key? `phoneuse login --with-key < key.txt` checks it with the server and stores it without the browser step. ## Prerequisites * **Node 22 or newer.** The package declares `engines: { "node": ">=22" }`. On an older runtime, `doctor` reports a failure with the fix. The source instructions below are optional and require access to the private repository and an existing checkout. ```bash theme={null} corepack enable corepack pnpm install --frozen-lockfile ``` ## Running from source `pnpm cli` runs the CLI straight from TypeScript with no build step. This is the right mode while you are working on the repository, because an edit takes effect on the next command. ```bash theme={null} corepack pnpm cli --help corepack pnpm cli doctor ``` Everything after `cli` is passed through, so flags work as documented: ```bash theme={null} corepack pnpm cli devices --json corepack pnpm cli devices --server https:// ``` ## Running the built entry point Building compiles the repository into `dist`. ```bash theme={null} corepack pnpm build node dist/cli/main.js doctor ``` `dist/cli/main.js` is the same entry point the release package includes: inside the package it sits at `cli/main.js`, which is what the manifest declares as the `phoneuse` binary. Both entry points use the same parser, client and control plane. ## Configuring it Two things. **Which control plane.** Defaults to the hosted one, `https://mcp.phoneuse.com`. A control plane running on your own machine is `--server http://127.0.0.1:8788`; to make that the default for a shell, set `PHONEUSE_SERVER=http://127.0.0.1:8788`. A `--server` flag always beats the variable. Each server keeps its own login, so logging in to a local one does not replace your hosted key. **Which credential.** In order: `PHONEUSE_API_KEY` from the environment, then the key `phoneuse login` stored for that server, then `PHONEUSE_DEV_TOKEN` (a local control plane's dev token). The dev token is only ever sent to a loopback server: aimed at any other, the command refuses rather than send it. Use the variable in CI and scripts, where nobody is there to approve a login: ```bash theme={null} export PHONEUSE_API_KEY="pbk_..." phoneuse devices ``` `phoneuse whoami` names which of the three it is using. Stored credentials keep their existing keychain identity and file path. Set `PHONEUSE_CONFIG_DIR` to choose another credentials directory. > [!NOTE] > > From a checkout, `corepack pnpm cli` substitutes for `phoneuse` in every > command below. It is the same program either way. Sending a credential in the clear to a non loopback server is refused. Remote authenticated calls require `https`; a local loopback server can use `http`. ## Checking the install `doctor` runs the checks that catch the setup problems people actually hit, and exits non zero if any of them fail. ```bash theme={null} phoneuse doctor ``` It reports on your Node version, whether the control plane answers on `/healthz`, and whether the credential in use is accepted and where it came from. Each failing check prints its own fix. Start there before anything else. # CLI Source: https://docs.phoneuse.com/cli/overview An operator client over the same control plane, with no behaviour of its own. These instructions target version [`0.6.0`](https://www.npmjs.com/package/@phoneuse/cli/v/0.6.0) of [`@phoneuse/cli`](https://www.npmjs.com/package/@phoneuse/cli), the current release on npm. It installs the `phoneuse` command and requires Node 22 or newer. `phoneuse` is a command line client for the PhoneUse control plane. It is useful for setting a device up, checking that one works, and driving one by hand while you are debugging something an agent did. `phoneuse login` pairs the terminal with your console session and stores an API key for your organization. See [Installation](/cli/installation) for prerequisites, optional source instructions and a REST API alternative. ```bash theme={null} npm install -g @phoneuse/cli@0.6.0 phoneuse login phoneuse devices ``` It is deliberately thin. Every device command it offers is a call to the same `/mcp` endpoint an agent uses, and it holds no device logic of its own. That has a practical consequence worth knowing: if a command works in the CLI but not from your agent, the difference is in your client or your credential, not in the control plane. > [card] [Command reference](/cli/commands) > > Every command, its arguments, and its flags, generated from the parser > itself. ## What it is for | You want to | Use | | - | - | | Log in, check which key you are using, or log out | `login`, `whoami`, `logout` | | Check your environment before looking further | `doctor` | | See what the control plane can reach | `devices` | | Drive a device by hand | `acquire`, `screenshot`, `tap`, `release` | | Hand a device to an autonomous run | `run` | | Check, continue or stop a run | `runs show`, `runs resume`, `runs cancel` | | Give a stdio-only MCP client (Claude Desktop, Cursor) your cloud phones | `mcp --stdio` | ## Talking to a control plane Device commands talk to a control plane over HTTP. By default that is the hosted one, `https://mcp.phoneuse.com`; `--server ` points it somewhere else, such as a control plane on your own machine, and `PHONEUSE_SERVER` sets the same thing for a whole shell. ```bash theme={null} phoneuse devices phoneuse devices --server http://127.0.0.1:8788 ``` Credentials never come from a flag, so they do not land in your shell history or in a process listing. The CLI sends the first of: * `PHONEUSE_API_KEY` from the environment, for CI and scripts. * The key `phoneuse login` stored for that server. * `PHONEUSE_DEV_TOKEN`, for a control plane on your own machine. It is never sent to a server that is not loopback. Whichever it is goes as a bearer token through the same authentication pipeline every other caller uses. `phoneuse whoami` tells you which one. > [!WARNING] > > The CLI refuses to send a credential in the clear to a non loopback server. > A remote `--server` has to be `https`. `phoneuse login` does not hold an OAuth session. It mints an ordinary API key through a console approval, so everything that is true of API keys is true of it: it has scopes and an expiry, it shows on the console's `/keys` screen, and you can delete it there. When you need a new one, run `phoneuse login` again. ## You do not have to carry a lease `--lease` is optional, for the same reason `leaseId` is optional in the tool schemas: your key already says which organization you are, and a device your organization holds is one you may act on. A gesture on a device your organization does not hold takes it for you, and the lease expires on its own ten minutes after the last renewal. `release` is the one command that needs the id, so take it explicitly when you want to give the device back early. ```bash theme={null} phoneuse tap cloud-phone-01 500 500 phoneuse screenshot cloud-phone-01 -o shot.jpg phoneuse acquire cloud-phone-01 --json phoneuse release cloud-phone-01 ``` Coordinates are on the same normalized grid the tools use: both axes run 0 to 1000 whatever the real screen size is. ## Human output and machine output By default a command prints a short human summary. Pass `--json` and it prints the `structuredContent` the tool returned, unmodified. Use `--json` in anything you script. The summary is written for a person and is free to change; the structured shape is published in the [tool reference](/mcp/reference). ```bash theme={null} phoneuse acquire cloud-phone-01 --json ``` ## Release status The current release is [`@phoneuse/cli@0.6.0`](https://www.npmjs.com/package/@phoneuse/cli/v/0.6.0), published on npm on 2026-10-22. See the [changelog](/changelog) for what changed. See [Installation](/cli/installation) for setup and [CLI in CI](/cli/ci-cd) for pipeline instructions. From an authorized repository checkout, `corepack pnpm cli` runs the program from source. # Chat with the copilot Source: https://docs.phoneuse.com/copilot/chat The chat protocol behind the console's copilot: threads on the server, a streamed UI message protocol, approvals that ride the stream, and the limits a turn runs under. The copilot is the console's main way to drive a phone: you type what you want, and it takes the same tools an agent takes, as you, while you watch. This page is for somebody building a chat client against it, or reading the console's transport to see what it depends on. Everything here is served by one route, `POST /v1/copilot`, and four routes for the threads it writes. All five need a signed in person: a copilot acts as somebody, and an API key has nobody behind it. ## Threads live on the server A conversation is a thread, owned by the person who opened it, inside their organisation. The server keeps it: every message you send, every message the copilot writes, every tool it called and what came back, and the screenshots it took along the way. Three things follow from that. * **The copilot remembers.** Each turn is shown the thread so far, within a budget (see [Limits](#limits)), so you can say "now open the second one" without repeating yourself. * **Your client's history is not trusted.** A request carries the client's copy of the transcript, and only its last message is read. What the copilot is shown is the stored thread. Two browsers open on one thread see the same past, and nobody can put words in the copilot's mouth by editing a payload. * **A thread is private.** Another person in your organisation cannot list it, open it, rename it or delete it. To them it answers 404, the same as a thread that never existed. There is no sharing yet. The four thread routes: | Route | What it does | | - | - | | `GET /v1/copilot/threads` | Your threads, newest activity first, titles and message counts only. `q` searches titles; `limit` and `before` page. | | `GET /v1/copilot/threads/{id}` | One thread with a page of its messages, newest last, as UI messages. `limit` and `before` page back; `files=none` leaves screenshots out. | | `PATCH /v1/copilot/threads/{id}` | Rename it. The title is the one field you edit. | | `DELETE /v1/copilot/threads/{id}` | Delete it. It leaves every listing and read; the id cannot be reused. | A new thread takes its title from the first message you send, cut to the length `THREAD_TITLE_MAX_CHARS` allows. ### Reopening a thread `GET /v1/copilot/threads/{id}` answers with the thread and its newest messages, oldest first, so the page ends where the conversation stands. It is paged because a thread is heavy: every tool result carries its full text and every screenshot its bytes. The response also carries `mode`: the mode saved on this thread, or `null` if none was chosen. A second browser can show the same choice when it reopens the thread. * `limit` is how many messages, `DEFAULT_THREAD_MESSAGE_ROWS` when omitted and at most `MAX_THREAD_MESSAGE_ROWS`. * `nextBefore` in the response is the oldest message on the page, when older ones exist. Send it back as `before` to get the page before it. * Inline screenshots are carried within `MAX_INLINE_PAGE_BYTES` of decoded image data per response (about a third more on the wire, as base64 inside JSON). The fit is greedy, newest first: each screenshot is kept if it fits what is left, so a large one that does not fit is left out while a smaller older one may still be carried. `files=none` leaves every one out. Either way `omittedFiles` says how many were left out, and the `frameId` on the tool output beside each one still names the picture for the frames API. Hand `messages` to your chat state as they are. A tool part in state `approval-requested` on the last message is a question still waiting. ## The protocol `POST /v1/copilot` answers in the UI message stream when your request lists `application/vnd.phoneuse.ui-message-stream` in `Accept`. The body is the one the AI SDK's default chat transport sends: ```json theme={null} { "id": "thread_8f2c", "trigger": "submit-message", "messages": [ { "id": "u_1", "role": "user", "parts": [{ "type": "text", "text": "Open the camera on pixel-1" }] } ] } ``` `id` is the thread. A new id opens a new thread owned by you. `messages` is your transcript; only the last message is read, and only its text parts. User file attachments are rejected with `invalid_argument`. The copilot still returns screenshots it observes on the phone. ## Which phone the turn is about A person on the page of one phone who types "open Settings" has already named the phone. Send what you know beside the message and the copilot will not ask them to say it again: ```json theme={null} { "id": "thread_8f2c", "messages": [{ "id": "u_1", "role": "user", "parts": [{ "type": "text", "text": "Open the camera" }] }], "context": { "route": "/devices/pixel-1", "device": { "id": "pixel-1" }, "pinned": { "deviceId": "pixel-1" } }, "mentions": ["pixel-2"] } ``` Both `context` and `mentions` are optional, and both go on either body shape. `mentions` carries device **ids**, not the names in the sentence, so renaming a phone can never re-point a message somebody already sent. The copilot picks the phone in this order and stops at the first hit: 1. `context.pinned.deviceId`, a phone the person pinned to this chat. 2. `mentions`, when it names exactly one. 3. `context.device.id`, the page they are on. 4. The device this thread last acted on, read from its own tool calls. 5. The only device you have, if you have one. 6. Otherwise a `data-device-choice` card. Three things follow. * **The copilot is told, and it acts.** A tool call that needs a device and names none is given the one the context decided, so a sentence with no phone in it still reaches the right phone, and the call you see carries the id. * **`context` is never replayed.** It describes where somebody is *now*, so only this request's copy is read. The stored thread keeps none of it. What survives between turns is which device the thread actually touched, which is a fact rather than a claim about a page. * **An id you cannot address is a 400**, naming the field. Every field that is wrong is named in the one answer, so you never fix them one round trip at a time. `context.device` is `{"id": ...}`, an object; a bare string is refused rather than ignored. `context.device` and the rest may carry more than the id, such as a name, a tier and an online flag, and extra keys are accepted. Only the ids are read. The name, tier and online state the copilot works from are this service's own, so a page that has gone stale cannot tell it a phone is up. The response is `text/event-stream`, with the header `x-vercel-ai-ui-message-stream: v1` so a transport can tell it apart from the older event stream without reading the body. Each frame is `data:` followed by one JSON chunk, and the stream ends with `data: [DONE]`. The chunks, in the order a turn produces them: | Chunk | Meaning | | - | - | | `start` | First. `messageId` names the assistant message this stream writes, which is the message a later approval answer continues. `messageMetadata.createdAt` is when it began. | | `start-step`, `finish-step` | One model step. A step is one answer from the model, with the tools it asked for. | | `text-start`, `text-delta`, `text-end` | The copilot's prose, as it is written. | | `reasoning-start`, `reasoning-delta`, `reasoning-end` | The model's reasoning, when the model provides it. | | `tool-input-start`, `tool-input-delta`, `tool-input-available` | A tool call is being formed, then its arguments are complete. Nothing has run yet. | | `tool-approval-request` | The call needs your yes. See [Approvals](#approvals). | | `tool-output-available` | The tool finished. `output` is `{summary, text, frameId?}`: a bounded line, the tool's full answer, and the frame id when a screenshot produced one. | | `tool-output-error` | The tool's own verdict was an error, or nobody answered an approval in time. `errorText` says which, and is always present because the AI SDK requires it. When the tool itself failed, four more fields ride beside it: `message`, the error's own sentence; `code`, its code (`tool_failed` when the tool's answer was not a readable error); `retryable`, whether the same call may succeed if sent again unchanged; and `retryAfterMs`, how long to wait first, only when the tool said (for example `device_busy`). They are on the stream only: the SDK's `useChat` does not copy them onto the message part, and a replayed thread does not carry them, so read them in your transport if you need them. | | `tool-output-denied` | You said no. | | `file` | A screenshot, as a `data:` URL with its media type, when it is small enough to carry inline (`MAX_INLINE_FILE_BYTES`). Larger ones send the `frameId` on the tool output instead, for the frames API. | | `data-device-choice` | More than one phone could have been meant and none was named. `{reason, devices: [{id, label}]}`: `reason` is the tool that needed a phone. Show the list; the person's pick comes back as the next message, or as `context.device`. The call that raised it is answered `tool-output-error`, and nothing touched a phone. This **is** a part, so it is still there when the thread is reopened. | | `data-suggestions` | Up to three follow-ups, `{items: [{text, deviceId}]}`, each naming a device. Sent before `finish` on a turn that completed. Fill them into the composer; do not send them. Also a part. | | `finish` | Last. `finishReason` is `stop`, `tool-calls` (an approval is waiting), `length` (the step budget), or `other`. `messageMetadata.stopReason` is the copilot's own closed set, finer than that. | | `error` | The turn ended badly. Nothing follows it, `finish` included. | Between chunks the stream may carry SSE comment lines as keep-alives. An event-source parser ignores them. Closing the request stops the turn. The copilot finishes the tool call it is on, if one is running, and stops before its next step or tool call. What it wrote so far is kept, and the stored message ends with `finishReason: "stop"`. ## Approvals In the default `auto` mode, one thing asks you first: **starting an agent run** that goes on acting by itself after the turn ends. Apps are installed from the console's Apps page, not by the copilot. Apart from the calls under [What is never turned off](#what-is-never-turned-off), which no mode turns off, everything else in `auto` mode, looking, taking and letting go of a device, and every gesture, simply happens because you asked for it. A card in front of every tap is not consent; it is a clickthrough, and it teaches people to approve without reading. The `ask` and `manual` modes ask before every action that is not read-only (see [How much it does on its own](#how-much-it-does-on-its-own)). Every one of these questions arrives the same way, as `tool-approval-request`. The question rides the stream and ends the turn: 1. The copilot sends `tool-input-available` for the call, then `tool-approval-request` with an `approvalId` and a descriptor: the tool, its arguments, one sentence to show, and `expiresAt`. The sentence is built from the tool and its arguments, never from anything the model wrote, so a card cannot describe a tap as a screenshot. 2. The stream ends with `finish{finishReason: "tool-calls"}`. The stored assistant message holds the pending question, so the answer may arrive on any machine, minutes later. 3. You answer by sending the same thread again, with that assistant message last and its tool part in state `approval-responded`, carrying `approval: {id, approved, reason?, input?, descriptor?}`. This is what the AI SDK's `addToolApprovalResponse` produces, plus the two fields below. 4. The next stream continues the same assistant message: its `start` names the same `messageId`. On a yes the copilot looks at the screen first, then runs the call, then the calls the model had queued behind it, then decides again. On a no it sends `tool-output-denied` and the turn ends: a copilot that carried on after a refusal, working around it, would make its approvals meaningless. ### What the card says The descriptor decides which card to draw and why, so the client never has to work it out from the tool name: | Field | Meaning | | - | - | | `kind` | `light` for one line and one row, `plan` for a goal with a budget. A run gets the plan card; it is the one call whose effects outlive the conversation. | | `reason.code` | `start_run`, `dangerous_operation` or `boundary`. What a receipt records and what you branch on. `install_app` appears only on old cards; app installs are retired from the copilot. | | `summary` | A line under the prompt, in the product's words. Absent when the call declares no ceiling; it never claims one. | | `budget` | `{maxSteps?, deadlineMs?}`: what the plan card shows and lets somebody edit. | | `calls` | Present only when one question covers several phones: `[{toolCallId, tool, input}]`. | | `expiresAt` | Only on the older wire. Absent here, and an absent value never expires. | A descriptor written before these fields existed carries neither `kind` nor `reason`. Read a missing `kind` as `light`. ### One card, several phones When the copilot has to ask about the same thing on three phones, you get one question, not three. The descriptor's `calls` lists every call it covers, one yes runs all of them, and each still runs as its own call and leaves its own receipt. A dangerous operation is never folded into that list: it always gets its own card, so a yes to three of something can never have been a yes to something else standing beside them. ### Editing before you agree On a plan card somebody may change the goal, the step ceiling or the time limit before saying yes. Send the changed fields as `approval.input`. ```json theme={null} { "id": "ap_1", "approved": true, "input": { "maxSteps": 4, "goal": "log in and stop" } } ``` It is **merged** over the arguments you were shown, so sending only what changed does not delete the rest, and it is re-checked against the tool's own published input schema. An edit the schema refuses is a 400 naming the field, in the words of the field rather than a schema path, and nothing runs. The stored tool part keeps `approval.input` after the call has run, so a thread read back later still shows the edit the call ran with. If you echo `approval.descriptor.reason` back, it has to be the code the question was asked with, or the answer is refused: consent shown for one reason is not consent for another. Echoing nothing is accepted. A question that nobody answers within `APPROVAL_TIMEOUT_MS` expires: the answer is refused with `tool-output-error` on the call. Sending a new message while a question is pending closes the question the same way. Only the person the question was asked of can answer it, because the thread is theirs. An answer to a question that is not pending, or that this thread never asked, is 404. ## How much it does on its own Every chat runs in one of three modes. The product default is `auto`, and that is a deliberate choice rather than a convenience: a card in front of every action is not consent, it is a clickthrough. | Mode | What it means | | - | - | | `auto` | The default. Direct device actions run; each approval-required plan still asks. | | `ask` | Every action in the ask tier raises a card. | | `manual` | Accepted and saved as `ask`: every action that is not read-only raises a card. | Send `mode` on a chat request to change that chat's mode. It takes effect on the turn that sets it and is saved with the thread. An approval authorizes only the pending action. There are no remembered grants or organisation-wide automation defaults. ### What is never turned off No mode bypasses any of these. * A tool that declares `requiresUserInteraction` in its own MCP metadata. This is enforced at every call. Historical `install_app` approval cards remain readable, but approving one cannot restore retired installation. * Lifting a hold that a person or another client put on a phone. * Money, API keys and team membership, which are never done on your behalf at all. Those are not cards; they are refusals with a link. There is no classifier reading what the copilot is trying to do, and no threshold that stops it after N similar actions. A goal it set itself does not widen anything, and neither does text it read off a screen. ## Picking a cut stream back up A phone that went to the background, a tab switched away from, a network that dropped. Reconnect to `GET /v1/copilot/threads/{id}/stream` and the rest of the message arrives as the same chunks, under the same header, ending with the same `data: [DONE]`. * `since` is the `messageId` from the `start` chunk you were reading. * `afterPart` is how many of its parts you already hold. `0`, the default, replays the whole message; a number past its end sends the frame and nothing inside it, which is how you learn you are caught up. * Omit `since` and the newest assistant message is replayed from the beginning, which is what a client that lost its place entirely needs. * A `since` naming no message of this thread replays nothing rather than restarting from the top. Restarting would repeat what you already have and hide that your cursor is stale. No model is asked anything and nothing is written, so this costs no tokens and answers the same on a deployment with no copilot configured. **What it does not do.** It does not rejoin a turn that is still running, because after a disconnect there is not one: closing the request aborts the turn, the copilot stops before its next step or tool call, and what it had is stored. A reconnect therefore gives you everything you missed up to the moment the connection died. The turn does not carry on in the background. ## Commands: one tool, no model Sometimes there is nothing to work out. `POST /v1/copilot/commands` runs a single tool you name, as you, with no model involved and no tokens spent. It is what the console's `/screenshot` and `/press_key home` become. ```json theme={null} { "tool": "press_key", "input": { "key": "home" }, "context": { "device": { "id": "pixel-1" } }, "threadId": "thread_8f2c" } ``` It reaches the same tool surface a chat turn drives, under the same permissions and the same approval table, so a command cannot do what the conversation would refuse. Two things differ, and both follow from your having typed the tool yourself. * **It works with no copilot configured.** A deployment with no model answers 503 on `POST /v1/copilot` and still runs commands. Pressing Home should not need a language model. * **The receipt is not marked `via copilot`.** You did this. `context` and `mentions` work exactly as they do on the chat route, so a command typed on a phone's page needs no `deviceId`. What you may drive this way: every read, plus `open_app`, `press_key`, `release_device`, `list_runs`, `cancel_run` and `resume_run`. Those are the tools whose arguments you can write out in full. `tap`, `swipe`, `type_text` and `long_press` are not, because the useful form of "tap the login button" is a sentence and the coordinates are the copilot's job; nor is `start_run`, which takes a goal and a budget. Asking for one of those here is a 400 telling you to use the conversation. A tool your session has no scope for is a different answer, 403, and the message names the scope, because that remedy is an administrator rather than a rephrasing. A 200 carries `{tool, isError, output: {summary, text, frameId?}}` and optionally `files`. `isError` is the tool's own verdict, not the HTTP status: a device refusing a gesture is a 200 with `isError` true, exactly as `tool-output-error` is on the stream. Send `threadId` and the result is appended to that thread as a tool part. That is what makes a command followed by a sentence work: the next turn sees what the command did rather than a gap where it happened. Leave it out and the command still runs, in no conversation. If a tool asks before it runs, the answer is 202 with an `approval` descriptor and an `approvalId`, and nothing has run. Show the card, then send the same `tool` and `input` again with that `approvalId`. The question is stored on the thread, so it can be answered minutes later and on another machine, which is why a command that asks needs a `threadId`. The tool and arguments are checked against what was asked: a yes to one command cannot be spent on another. ## When it fails A turn that ends badly sends `error` and nothing after it, with a code from a closed set. The three you will want to tell apart: | Code | What it means, and what to show | | - | - | | `copilot_unfunded` | The copilot has no credit on our side. The message is the one to show: "The copilot is out of credit on our side. Your phone and / commands still work. We've been told." Nothing the person did caused it and nothing they can do fixes it, so do not send them looking. Their phone, their commands and everything outside the chat are unaffected. We are alerted. | | `rate_limited` | The model provider is throttling. Worth retrying in a moment. | | `model_unavailable` | The model could not be reached. Different from both of the above, which is why they are no longer the same code. | `model_refused`, `tool_failed` and `internal` complete the set. The first three used to be one code, so a client could only ever say the vaguest of the three. ## Limits * A turn takes at most `MAX_TURN_STEPS` model steps, across the requests an approval splits it into. Reaching the budget is not an error: the work done is done, and its receipts exist. A job that genuinely needs more is an agent run. * One message carries at most `MAX_COPILOT_PROMPT_CHARS` characters of text. * The history the model is shown is the most recent messages that fit within `HISTORY_BUDGET_CHARS` characters of transcript, cut at a message of yours so the transcript never opens with the copilot's reply. Your newest message is always included. What the cut removes is **not forgotten**: it is folded into a short summary the copilot writes once and keeps with the thread, shown in front of the recent messages on every turn after that. A long conversation therefore still knows what it was started for and which phone it was about. The summary is regenerated only when the cut reaches past what it already covers, so it costs one extra model call when a thread first crosses the budget and nothing on the turns after. Nothing that can be rebuilt from the server goes into it: the mode, what has been remembered and which phone the chat is about are regenerated fresh every turn, so a summary of them would be a second and stale copy. * Screenshots travel inline up to `MAX_INLINE_FILE_BYTES`; above that you get the frame id. * The listing returns at most `MAX_THREAD_ROWS` threads per page, a thread read at most `MAX_THREAD_MESSAGE_ROWS` messages, and both refuse a larger `limit` rather than quietly reducing it. * The copilot gives up on a model that stays silent for `MODEL_TIMEOUT_MS` within one step, and says so as an error of its own; a model that keeps answering slowly is never cut off. The named limits are constants in the control plane's source, and the OpenAPI document under [API](/api) carries their current values. ## The older event stream Until the console has switched, the same route also answers requests that do not ask for the UI message stream, with `{prompt}` in and named SSE events out (`session.start`, `message.delta`, `tool.call`, `tool.result`, `approval.request`, `tool.denied`, `ping`, `done`, `error`). Approvals on that wire are answered on `POST /v1/copilot/approvals` while the stream stays open. It goes in the release after the switch; build against the protocol above. # Capabilities Source: https://docs.phoneuse.com/devices/capabilities What a given device can and cannot do, declared rather than discovered. Devices differ. Two phones can take the same tap and still differ in what they can observe, which keys they can press and whether they can install an app. Rather than making you probe for that, every device declares it. Call `list_devices`, or `get_device` when you already know the id, and read the `capabilities` block before you plan anything. ## What a device declares ```json theme={null} { "fidelityTier": "software", "actions": { "tap": true, "swipe": true, "typeText": "native", "pressKey": ["home", "back", "enter"], "openApp": "intent", "installApp": "managed_store" }, "observations": { "screenshot": "framebuffer", "uiTree": "uiautomator", "framesAreReferenceable": true, "freshnessMs": null }, "os": "android", "coordSpace": { "width": 1000, "height": 1000 } } ``` The values above are one device's answer, not a template. Read your own. ## Actions Each action field says **whether** the device supports something and, where it matters, **by which mechanism**. The mechanism changes how you should use it. | Field | Values | What the value tells you | | - | - | - | | `tap` | boolean | Whether a point can be pressed | | `swipe` | boolean | Whether a gesture between two points is possible | | `typeText` | `native`, `per_key_visual`, `false` | `native` injects text into the focused input. `per_key_visual` presses one key at a time on the on screen keyboard, so it is slower and needs a visible keyboard | | `pressKey` | a list of keys, or `false` | The exact keys this device can press, not merely whether it can press any | | `openApp` | `intent`, `visual`, `false` | `intent` launches by app id through the operating system. `visual` finds the icon on screen and taps it, so the device has to be somewhere the icon is visible | | `installApp` | `managed_store`, `false` | `managed_store` means apps are installed only from the Apps page in the Console, and the device refuses any package or URL you send it. `false` means the device cannot install apps at all. Older saved descriptions may still say `apk`, a retired value that is no longer reported | | `stop` | boolean | Whether the device can be halted by a stop request. `false` on every device you can buy: none has motion of its own to stop, and there is no stop route. The field stays so every device description has the same shape | `pressKey` is a list rather than a boolean for a reason. The tool's parameter enumerates every key the platform has a meaningful equivalent for, and that is an upper bound across all backends. A given device supports a subset and refuses the rest. ## Observations | Field | Values | What the value tells you | | - | - | - | | `screenshot` | `framebuffer`, `camera`, `false` | `framebuffer` is a pixel exact capture from the operating system. `camera` is a photograph of the screen, and no device you can reach today reports it | | `uiTree` | `uiautomator`, `a11y`, `false` | Where the structured element tree comes from, or `false` when there is none. Do not call `ui_snapshot` on a device that says `false` | | `framesAreReferenceable` | boolean | Whether screenshots carry a `frameId` that a later action can bind to with `observedFrame` | | `freshnessMs` | number or `null` | How old an observed frame may be when an action binds to it, or `null` for no age bound. The control plane puts no clock on a frame of its own, and every device you can reach today reports `null`. A frame past a non-`null` limit would be refused with reason `expired`. Meaningful only when frames are referenceable | | `stream` | `webrtc`, `false` | Whether the screen can be watched as live video through `POST /v1/devices/{deviceId}/stream`. It describes the device, so read that route's `transport` for what you actually get | A device with no visual observation at all, such as a hardware input dongle, declares `framesAreReferenceable: false` and is never forced into frame discipline. Passing `observedFrame` to one is refused as `capability_unsupported` rather than quietly ignored. ## Fidelity tier `fidelityTier` says how input reaches the device. The MCP tools list two values, `software` and `hid`. Every device you can reach today reports `software`, and no device reports `hid`. See [Device tiers](/devices/tiers) for what each one means. The HTTP API reference still lists a third value, `physical`, with an extra `physical` block. It belonged to the robot hand + iPhone, which is not part of the API, MCP or CLI, and no device reports it. ## Coordinates Every device speaks the same grid: both axes run 0 to 1000 whatever the real screen size is, with the origin at the top left, in the current orientation. `coordSpace` states it explicitly. Backends convert to device pixels internally. You never see pixels, except as the informational `pixelSize` on a screenshot, which is there to describe the image rather than to aim with. Bounds inside a `ui_snapshot` tree are already normalized, so a coordinate you read there can be tapped directly. ## Backend kinds `backendKind` names the mechanism that reaches a device. It is a closed set: | Kind | What it is | `fidelityTier` | Adapter | Reachable today | | - | - | - | - | - | | `emulator` | A virtual Android device on your own machine | `software` | None | No | | `adb_real` | Real Android hardware over the debug bridge | `software` | None | No | | `adb_cloud` | A hosted cloud Android device, reached over the cloud phone platform's HTTPS API | `software` | Live | Yes, once a device is provisioned to you | | `robot_hand` | The name for the robot hand + iPhone, which is bought in the console and prepared by our team; it is not part of the API, MCP or CLI | Not declared | None | No | | `esp32_hid` | A hardware input dongle, actions only, no observation | `hid` | None | No | | `byod_portal` | Devices an org enrols itself | Not declared yet | None | No | Every kind except `adb_cloud` is declared with no adapter behind it. A device row naming one of them is accepted, and a call against it is refused with `backend_not_implemented` rather than failing in some less obvious way. `adb_cloud` is not one of them: its adapter is live. A cloud row is reached over the cloud phone platform's HTTPS API, and its capability block is narrower than the kind's bound, so read `capabilities` on the device rather than assuming it from the kind. This is how the cloud phones you can **buy on the spot** from the `/devices/add` screen are reached. The frame is captured inside the guest OS (`screenshot: "framebuffer"`), live video comes from the cloud phone platform's own channel (`stream: "webrtc"`, handed out by `POST .../stream` as `transport: "provider-rtc"`), and `wake` is supported. There is no element tree (`uiTree: false`), so `ui_snapshot` is refused with `capability_unsupported`; read the screen from screenshots instead. Every key in `pressKey` is available, and a key press is reported once the cloud phone platform accepts it, without waiting for a confirmation from the device. A cloud row reports its reachability in `status`, which is an answer about that device and not a statement about the adapter. It reports `offline` when the cloud phone platform named it and said it was not running, and `unknown` when the platform's fleet listing failed or never mentioned it at all, or when the row names no cloud phone instance. Three separate vocabularies describe a device and it is worth keeping them apart. `backendKind`, in this table, is the mechanism. `fidelityTier` is how input reaches the screen, and it is the coarser of the two: three backend kinds collapse into `software`. The phone names on [Billing modes](/billing/modes#rates) are a third vocabulary, for what a device costs, and that page carries the crosswalk between them and `backendKind`. Use `backendKind` to understand what you are talking to. Do not use it to infer abilities: the capability block is the authoritative answer, and a backend narrows it per device rather than widening it. A device's backend is resolved from that device's own record. There is no global switch, because a fleet mixes backends and a process wide setting would always be wrong for somebody's device. ## Refusal, never silence An adapter that claims an ability it does not implement, or implements one it did not declare, fails at startup rather than at your call site. At your call site, an unsupported ability is refused with `capability_unsupported`. It is never accepted and quietly dropped, which would leave you believing something happened on a real device when nothing did. ## What the device says it is The capability block says what the control plane can DO to a device. The optional `info` block beside it says what the device IS: the four facts a person reads off Settings, About phone. ```json theme={null} { "model": "Pixel 4 XL", "androidVersion": "13", "resolution": { "width": 1440, "height": 3040 }, "carrier": "StarHub" } ``` It is read once and cached, not probed to answer your call. A reading is taken the first time you acquire the device, and retried on each later acquire while it is still missing, so nothing you call pays a round trip to the device for it. A device you own but have never acquired has no reading, and will not get one until you take it. The consequence worth knowing: `info` can be absent on a device that will report it a minute later, and the acquire that triggers the reading can itself answer before the reading lands. `resolution` is the screen in device pixels. It is **not** the grid you aim actions at. Taps and swipes are sent in `capabilities.coordSpace`, a normalised 1000 by 1000 space, and converting a coordinate through the pixel rectangle instead will land it somewhere else. It is also not a screenshot's `pixelSize`, which is one observation's dimensions in whatever orientation it was taken in. ### Three absences, three meanings Missing is not one state here, and code that treats it as one will describe a phone wrongly. | What you see | What it means | What to render | | - | - | - | | no `info` at all | Nothing has read this device yet | `Not reported yet`, never a blank model | | `info` present, a field missing | It was asked and did not report that one | `Not declared` | | `"carrier": null` | It answered, and it has no operator | `None`. A phone with no SIM is a working phone | Which fields arrive depends on how the device is reached, not on what the hardware has. A cloud phone driven over the cloud phone platform's HTTPS API has no route that returns a shell command's output, so nothing here comes from `getprop` or `wm size`: the model, the Android version and the operator are read from the cloud phone platform's own property API, and the screen comes from the same framebuffer measurement the tap path already uses to place a coordinate. A field is absent when that particular device did not report it, not because of the transport. The reading is taken the first time the device is acquired, and a reading that is missing a field is retaken once after a deployment, so a field can appear later without anything being asked of you. Every field is optional and the block only ever grows, so read it defensively: branch on the field you want being present, never on `info` having a particular shape. # Device tiers Source: https://docs.phoneuse.com/devices/tiers How input reaches a device, and which tier the devices you can use are on. Every device declares how an input actually reaches its screen. The control plane calls that the **fidelity tier**, and you read it as `fidelityTier` in the device's `capabilities`. **Every device is driven through the same [MCP surface](/mcp/overview).** There is no separate path for one kind of device: you call the same tools, against the same normalized coordinate grid, whatever tier a device is on. ## The tiers today > [card] Software > > Input is sent inside the operating system, or through the cloud > phone platform's channel. Every device you can reach today is on this tier. > [card] HID > > Input would arrive as hardware keyboard and pointer events from an > external dongle. The value is declared, but no device reports it. The HTTP API reference still lists a third value, `physical`. It belonged to the robot hand + iPhone, which you buy in the console and our team prepares; it is not part of the API, MCP or CLI. No device reports it. > [!NOTE] > > A tier is not a price. Fidelity describes how input reaches the screen, and > price tracks the phone behind it, so the `software` tier spans several > prices: a monthly cloud phone, a Real phone identity cloud phone and a per > minute phone are all on it. See [Billing modes](/billing/modes#rates) for the > crosswalk between phones, backend kinds and rates. ## Capabilities are per device, not per tier Do not infer what a device can do from its tier alone. Call `list_devices` and read the `capabilities` block on each one. Capabilities describe both directions: * **Actions**: whether the device supports tapping, swiping, typing, key presses, and opening apps, and by which mechanism. Typing, for instance, may be native or may be performed key by key against the visible keyboard. * **Observations**: whether the device can take screenshots, whether a UI tree is available, and whether captured frames can be referenced by later actions. An action a device cannot perform is refused. It is never accepted and quietly dropped, which would leave you believing something happened. See [Capabilities](/devices/capabilities) for every field. ## Coordinates are the same everywhere Every device uses the same normalized grid: both axes run 0 to 1000 regardless of the real screen size. Bounds in the `ui_snapshot` tree are already on that grid. This is what lets the same tap work across devices, and it is why moving a task from one device to another changes the device you name and nothing else. ## Regions A cloud phone comes up on the mobile network of one country, and that country is its **region**. It decides which app stores and services see the phone as local, so a task that needs a phone in Japan needs a phone whose region is Japan, not a phone somewhere else pointed at a Japanese site. You choose the region when you buy. Each model on the price list (`GET /v1/skus`) that can be placed in more than one country carries a `regions` list, each entry an upper-case ISO 3166-1 alpha-2 code (`US`, `JP`, `GB`) with its own `shipsNow`. Send the code you want as `region` beside the `model` on `POST /v1/checkout-sessions`, and the purchase records it: the device is provisioned in that region or the order waits until it can be, and `GET /v1/fulfilments` shows the code on the purchase. A code the model does not list is refused before anything is charged. Three things to know: * **Stock is per model per region.** A model can be available in one country and sold out in another, which is why each region carries its own flag rather than the model carrying one for all of them. A region listed with `shipsNow: false` is still shown so you can see it exists, and a purchase naming it is refused until stock returns. * **The list is the deployment's, not the world's.** Which countries a deployment places phones in is a decision its operator makes; the list you see is that decision. A model with no `regions` has one place it can be, and there is nothing to choose. * **If you send no region, you get the deployment's default** for that model. The default is one of the listed regions, and the purchase records no region of its own, so it can later be fulfilled from any available unit of the model. Price does not vary by region. The region is where the phone is, not what it costs. ## Which models are on sale Which models are on sale changes over time, so this site does not list them. Read the live list instead: `GET /v1/skus` for monthly phones, each model with its price and whether it can be bought now, and `GET /v1/minute/catalog` for per minute phones. **Add a phone** in the console shows the same list. # The console Source: https://docs.phoneuse.com/getting-started/console The browser face of the control plane: which screens exist, what each one does, and what has no screen at all. 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](https://console.phoneuse.com/sign-in), 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](#two-kinds-of-credential). ## The screens that exist | Screen | What you do there | The same thing over the API | | - | - | - | | `/devices/add` (**Add a phone**) | Buy a monthly phone, start per minute phones, or buy the robot hand (\$149 a month per robot, prepared within 24 hours after payment) | `GET /v1/skus`, then `POST /v1/checkout-sessions`; per minute: `GET /v1/minute/catalog`, then `POST /v1/minute/starts`; robot hand: `GET /v1/robot-purchases/offer`, then `POST /v1/robot-purchases/checkout` | | `/devices` | Your phones | `GET /v1/devices` | | `/devices/robot-orders/:orderId` | One robot hand + iPhone order: what you paid and its delivery status | `GET /v1/robot-purchases/{orderId}`. A signed-in session only | | `/devices/:id` | Watch the screen live, act on it (beside an agent's run if one is driving), pause or stop the run | `POST /v1/devices/{deviceId}/stream`, `GET /v1/devices/{deviceId}/screenshot`, `POST /v1/devices/{deviceId}/actions`, `GET /v1/devices/{deviceId}/driving`, `POST /v1/runs/{runId}/pause` | | `/usage` (**Billing**) | Your usage and your orders. On a monthly phone, **Cancel order** stops the next charge and keeps the paid period | `GET /v1/usage`, `GET /v1/fulfilments`; **Cancel order**: `POST /v1/fulfilments/{id}/cancel-renewal`, then `GET /v1/fulfilments/{id}/renewal-status`. A signed-in org admin only: an API key is refused | | `/runs` | Agent runs: what each was asked to do and how it ended | `GET /v1/runs` | | `/apps` | Install apps on your phones | [Apps](/guides/upload-app-package) | | `/webhooks` | Create and manage webhooks | [Webhooks](/guides/webhooks) | | `/keys` | Mint, rename, rotate and revoke API keys | `/v1/api-keys` | | `/connect` | The MCP connection details for your org | [MCP config](/getting-started/mcp-config) | | `/quickstart` | The first steps for connecting an agent | [Quickstart](/quickstart) | | `/team` | Invite people and set their role | None: console only | | `/activity` | What happened in your org | `GET /v1/receipts` | | `/settings` | Your organization and your role, and deleting the organization | None: console only | | `/proxy` | Proxies for your phones. Managed proxies are on the roadmap and not offered yet | `GET /v1/proxy-orders`, `POST /v1/proxy-operations` (connect or disconnect), `GET /v1/devices/{deviceId}/proxy`. A signed-in session only: an API key gets `403`. Managed proxies are not offered yet, so these answer `422 capability_unavailable` while they are off | 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](/guides/first-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](/help/what-phoneuse-is-not#it-does-not-video-record-a-session). * **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: ```json theme={null} { "tap": true, "swipe": true, "typeText": "native", "openApp": "intent", "installApp": "managed_store", "pressKey": ["home", "back", "enter", "delete", "app_switch", "power", "volume_up", "volume_down"] } ``` 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](/devices/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. | Surface | Where it is documented | | - | - | | A run's archived frames | [Frame retention](/security/frame-retention) | | Putting a run on hold, and letting it continue | [Runs](/agent/runs#driving-alongside-a-run) | ## Two kinds of credential | | Session | API key | | - | - | - | | Who holds it | A person, in a browser | A server you run | | Looks like | A cookie you never see | `pbk__` | | Buy a monthly phone | Yes, if you are an admin | Only with `orders:place`, which an admin grants | | Start a per minute phone | Yes, if you are an admin | **No** | | Drive a device | Yes | Yes | | Manage keys | Yes, either role | No | **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](/mcp/auth). 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 > [card] [Buy and drive a device](/guides/first-device) > > The whole loop, in the console and over the API, with real readings. > [card] [Authentication](/mcp/auth#scopes) > > The eight scopes, and how a key is narrowed to a subset of your devices. # First session Source: https://docs.phoneuse.com/getting-started/first-session Acquire a device, observe it, act on it, release it, one call at a time. A session is always the same four beats: acquire a lease, observe, act under that lease, release. This page walks one session end to end and shows what each call returns. Every example is a tool call. Your client decides how you phrase it; the parameters and the results below are what travels on the wire. **1. See what is reachable** `list_devices` needs no lease and takes no parameters. Call it first, every time. ```json theme={null} { "name": "list_devices", "arguments": {} } ``` Each entry carries an id, a status, and a `capabilities` block: ```json theme={null} { "devices": [ { "deviceId": "cloud-phone-01", "backendKind": "adb_cloud", "status": "online", "capabilities": { "fidelityTier": "software", "actions": { "tap": true, "swipe": true, "typeText": "native", "openApp": "intent", "pressKey": ["home", "back", "enter", "delete", "app_switch", "power", "volume_up", "volume_down"] }, "observations": { "screenshot": "framebuffer", "uiTree": false, "framesAreReferenceable": true, "freshnessMs": null }, "os": "android", "coordSpace": { "width": 1000, "height": 1000 } }, "metadata": {} } ] } ``` > [!NOTE] > > Every payload on this page is illustrative. Ids, timestamps, screen > geometry and freshness windows come from your own devices, so read them > out of the response rather than copying them from here. Read `capabilities` before you plan anything. A device with `uiTree: false` has no element tree to query, and a device whose `pressKey` list omits a key refuses that key. See [Capabilities](/devices/capabilities). If you already know the id, `get_device` answers the same shape for one device without enumerating the fleet. **2. Take a lease** A device holds one lease at a time, across every org. While you hold one, no other agent can acquire the device. Keep the `leaseId` it returned: actions and observations may carry it, and `release_device` needs it. A signed-in person in your org may still act on the device from the console beside you; when they do, your results say so in `others`. ```json theme={null} { "name": "acquire_device", "arguments": { "deviceId": "cloud-phone-01" } } ``` ```json theme={null} { "orgId": "org_local", "deviceId": "cloud-phone-01", "leaseId": "lease_9f2c...", "fencingToken": 41, "acquiredAt": "2026-08-29T10:14:02.113Z", "expiresAt": "2026-08-29T10:24:02.113Z" } ``` Keep `leaseId`. Read `expiresAt` rather than assuming a duration: a lease expires on its own, so a client that crashes cannot strand a device. You never pass `fencingToken` anywhere; the control plane uses it to make a resumed or duplicated caller lose to the current lease holder. Acquiring a device that is already leased fails. That is the point of a lease, and it is why repeating `acquire_device` is not idempotent. **3. Observe** ```json theme={null} { "name": "screenshot", "arguments": { "deviceId": "cloud-phone-01", "leaseId": "lease_9f2c..." } } ``` The result carries the image itself plus the metadata you need next: ```json theme={null} { "format": "jpeg", "source": "framebuffer", "pixelSize": { "width": 720, "height": 1280 }, "frameId": "frm_5b81...", "sequence": 12, "capturedAt": "2026-08-29T10:14:06.902Z" } ``` `pixelSize` is informational. Do not aim with it. Aim on the normalized grid, where both axes run 0 to 1000 whatever the real screen size is. Keep `frameId`. It is how the next step proves it was decided on this picture of the screen. On a device with a UI tree, `ui_snapshot` gives you the same screen as structured elements, and every bound inside that tree is already on the 0 to 1000 grid, so a coordinate you read there can be tapped directly. **4. Act** ```json theme={null} { "name": "tap", "arguments": { "deviceId": "cloud-phone-01", "x": 500, "y": 820, "leaseId": "lease_9f2c...", "idempotencyKey": "signin-button-1", "observedFrame": "frm_5b81..." } } ``` Two optional parameters are worth passing on every action. `observedFrame` binds the action to the frame you decided on. If the screen has moved on since that frame, the tap is refused with `stale_frame` rather than landing somewhere you did not intend. Observe again and decide again. A frame does **not** age out on our side, and a newer screenshot does not replace it. Take as long as you need between observing and acting, including time spent reading a large `ui_snapshot` or waiting for a person to approve the step, and observe again in between if that helps. What the frame is for is the `others` report that comes back on every action: how many actions another principal took on this device since you looked, when the newest was, and whether the hands were a person's or an agent's. With a frame named, an agent's action is refused rather than taken on a screen somebody else has touched; pass `refuseIfOthersActed: false` to act anyway and decide from `others`. A device whose own resource expires frames can still answer `expired`; a non-`null` `freshnessMs` in its capabilities is how you know to expect it. Nothing is lost when a frame is refused for any reason: the action never began and your `idempotencyKey` was not consumed, so re-observe and act under the same key. `idempotencyKey` is your own request id. Reuse the same value when retrying the same intended action, and the recorded outcome is replayed instead of the gesture happening twice. The result tells you the device applied it: ```json theme={null} { "status": "committed", "committedAt": "2026-08-29T10:14:08.377Z", "idempotencyKey": "signin-button-1" } ``` `committed` means the device confirmed the action, not that the request was accepted. Because you passed an `idempotencyKey`, this outcome is also on the ledger: `get_receipt` with the same key returns it later, which is how you confirm an action whose response you never received. See [Reading a trace](/getting-started/trace). The other action tools take the same shape: `swipe`, `long_press`, `type_text`, `press_key`, and `open_app`. Every one of them is destructive by design, because a gesture on a real device cannot be undone. **5. Release** ```json theme={null} { "name": "release_device", "arguments": { "deviceId": "cloud-phone-01", "leaseId": "lease_9f2c..." } } ``` ```json theme={null} { "ok": true, "deviceId": "cloud-phone-01" } ``` `leaseId` is required here, unlike on the action tools where it is optional: giving a device back is about one particular lease, so the id has to be the one you were given. Releasing a device you no longer hold is a no op, so a release in a `finally` block is safe. ## What happens if you skip a step | Mistake | What you get | | - | - | | Acting without `leaseId` | Nothing to fix: the action runs under the lease your organization holds, or takes the device for you | | Acting on a device another organization holds | `device_unavailable`, the same answer as a device you cannot see | | Releasing with an id that is not the current lease | `lease_mismatch` | | Acting on a stale `observedFrame` | `stale_frame`, telling you to observe again | | Asking for an ability the device lacks | `capability_unsupported`, never a silent no op | | Misspelling a parameter | The call is refused. Unknown keys are rejected rather than dropped | Read [Reading a trace](/getting-started/trace) next for how to confirm an action whose response you never received. # For agents Source: https://docs.phoneuse.com/getting-started/for-agents Machine readable entry points, and which MCP server is which. If you are an agent reading this site rather than a person browsing it, this page is the one to read first. It tells you where the machine readable copies live, and how to tell this site's MCP server apart from the one that drives real devices. ## Two MCP servers, one brand There are two. They are not variants of each other, and connecting to the wrong one is not a small mistake. | | Control plane MCP | Docs MCP | | - | - | - | | What it does | Drives a real device | Searches and reads this documentation | | Side effects | Physical and irreversible | None | | Annotations | The run tools declare `destructiveHint: true`; every tool carries a title and the other hints | Read only | | Authentication | OAuth 2.1 or an org scoped API key | None, the docs are public | | Served by | The PhoneUse control plane | The documentation host | The control plane server is the product. Its tools act on a real phone. The docs server returns text. Documentation search is deliberately **not** a tool on the control plane. Its tool surface is a frozen contract organised around device permissions, and a search tool fits none of those scopes. Keeping them apart means a list of tools never mixes "read a page" with "tap a phone". > [!WARNING] > > Name the two servers differently in your client configuration. Convention on > this site is `phoneuse` for the control plane and a clearly distinct name > such as `phoneuse-docs` for the documentation server. The test is simple: > looking only at the name, you should be able to say which one touches > hardware. To connect the control plane, see [MCP config](/getting-started/mcp-config). The documentation server is offered by the documentation host and is advertised on this site, alongside the copy and open in client actions on each page. ## llms.txt and llms-full.txt This site serves two plain text views for machine consumers: * `/llms.txt` is an index: a short description of the site plus a linked map of its pages. * `/llms-full.txt` is the whole site's prose concatenated into one file, for when you would rather read everything once than crawl page by page. Both are generated and hosted by the documentation host from this site's pages. Cached copies can temporarily lag behind a documentation update. The host also provides the official aliases [`/.well-known/llms.txt`](https://docs.phoneuse.com/.well-known/llms.txt) and [`/.well-known/llms-full.txt`](https://docs.phoneuse.com/.well-known/llms-full.txt). If a full text copy still shows the former brand or older instructions after an update, compare the relevant rendered page and this official alias before using it as the source for an integration. > [!NOTE] > > This site's `/llms.txt` covers the technical documentation. Read > [phoneuse.com](https://phoneuse.com) for positioning, pricing and > contact, and this site for anything you intend to call. ## What not to invent The main site's agent instructions say it plainly, and it applies here too: do not guess endpoint paths, do not guess tool names, and do not fabricate documentation URLs. Everything callable is published: * The [tool reference](/mcp/reference) is generated from the schemas the server actually registers, so a tool that is not there does not exist. * The [error reference](/mcp/errors) is generated from the error code union, so a code that is not there cannot reach you. * The [API overview](/api/index) states which HTTP surfaces exist and which credential each one reads. If a tool you expected is absent from `listTools`, that is authorization, not absence: a tool outside your credential's scopes is never registered. See [Authentication](/mcp/auth). ## What is live, and what is not Be accurate about this when you report to a person. * The PhoneUse hosted MCP endpoint is `https://mcp.phoneuse.com/mcp`. It requires a credential. Any signed in member of the org mints keys from the `/keys` screen in the console; you do not need an admin for this. See [Getting a key](/mcp/auth#getting-a-key). * A person can sign in, buy a device and drive it without writing any code. Devices are not returned online; on a Cloud phone, **Cancel order** on the Billing page stops the next charge. If you are reporting to somebody who has no device yet, that is the path to send them down: [The console](/getting-started/console). * Interactive OAuth sign-in from a generic MCP client is not verified to work. The endpoint's metadata names the configured Clerk issuer as its authorization server, but that server offers no dynamic client registration and does not advertise this endpoint's scopes, so a client that expects to register itself and sign in through a browser has nothing to register with. Use an API key. See [Authentication](/mcp/auth). * Local mode works today, needs no credential beyond an optional development token, and speaks the same tool surface as the hosted deployment. See [MCP config](/getting-started/mcp-config). # MCP config Source: https://docs.phoneuse.com/getting-started/mcp-config The exact config block for each transport, and what changes between them. PhoneUse speaks MCP over two transports. Both publish the same tool surface, so the config block is the only thing that differs. * **HTTP** talks to a control plane over the network, at `POST /mcp`. Your cloud phones are at `https://mcp.phoneuse.com/mcp`. * **stdio** is for a client that can only spawn a process. The PhoneUse CLI gives it your cloud phones by relaying to the hosted endpoint. Pick HTTP unless your client can only spawn processes. See [Transports](/mcp/transports) for the behavioural differences that follow from this choice. There is no separate MCP package to install. The stdio option below runs the PhoneUse CLI, `@phoneuse/cli`, with `npx`. ## Your cloud phones over HTTP The hosted control plane lives at `https://mcp.phoneuse.com/mcp`. Sign up at [console.phoneuse.com/sign-up](https://console.phoneuse.com/sign-up) and mint a key yourself at [console.phoneuse.com/keys](https://console.phoneuse.com/keys). See [Getting a key](/mcp/auth#getting-a-key). ```json theme={null} { "mcpServers": { "phoneuse": { "type": "http", "url": "https://mcp.phoneuse.com/mcp", "headers": { "Authorization": "Bearer pbk__" } } } } ``` Most clients cannot expand an environment variable inside a config file, so paste the key value itself. With Claude Code, one command does it: ```bash theme={null} export PHONEUSE_API_KEY="pbk__" claude mcp add --transport http phoneuse https://mcp.phoneuse.com/mcp \ --header "Authorization: Bearer $PHONEUSE_API_KEY" ``` The endpoint's protected resource metadata names the configured Clerk issuer as its authorization server. That server offers no dynamic client registration, so a client that tries to register itself and open a browser sign in has nothing to register with, and a browser flow from a generic MCP client has not been verified end to end. Use an API key. See [Authentication](/mcp/auth). Keep the client entry named `phoneuse`. This site's docs MCP server is a different server with a different name, and you want to be able to tell them apart in a client list. See [For agents](/getting-started/for-agents). ## Your cloud phones over stdio For a client that can only spawn a process (Claude Desktop, Cursor and others), run the PhoneUse CLI as a stdio server. It relays to `https://mcp.phoneuse.com/mcp`, so your client sees the same cloud phones and the same tools as over HTTP. First sign in once on that machine, which stores a key for the CLI: ```bash theme={null} npx -y @phoneuse/cli login ``` Then give your client this block: ```json theme={null} { "mcpServers": { "phoneuse": { "command": "npx", "args": ["-y", "@phoneuse/cli", "mcp", "--stdio"] } } } ``` The relay uses the key in `PHONEUSE_API_KEY` if it is set, and otherwise the key `phoneuse login` stored. With neither, it stops and tells you to sign in. See [CLI installation](/cli/installation). ## HTTP against a local control plane Start the control plane first. It listens on loopback and reads its device rows from the `PHONEBASE_DEVICE_ROWS` environment variable, a JSON array of rows. ```bash theme={null} PHONEBASE_DEV_TOKEN=dev corepack pnpm dev ``` ```text theme={null} The local MCP endpoint is http://127.0.0.1:8788/mcp. ``` Then give your client the endpoint: ```json theme={null} { "mcpServers": { "phoneuse": { "type": "http", "url": "http://127.0.0.1:8788/mcp", "headers": { "Authorization": "Bearer dev" } } } } ``` `PHONEBASE_DEV_TOKEN` is the local development credential. Set it, and the endpoint requires that exact value as a bearer token. Leave it unset, and the endpoint accepts unauthenticated requests, which is safe only because local mode refuses to bind anywhere but loopback. > [!WARNING] > > Local mode grants every scope. It is a single operator on a single machine, > not a permission model. Do not expose that port. ## Checking the connection The MCP Inspector talks to the endpoint without a client in the way: ```bash theme={null} npx @modelcontextprotocol/inspector --transport http \ --server-url http://127.0.0.1:8788/mcp \ --header "Authorization: Bearer dev" ``` Call `list_devices` first. It needs no lease, so it answers immediately, and what it returns tells you whether the control plane can see your hardware. If the tool list looks shorter than you expect, that is authentication rather than a fault: a tool your credential is not scoped for is never registered, so it does not appear at all. ## Two things clients get wrong **Host and origin are checked.** The HTTP transport refuses requests carrying a browser `Origin` header, and accepts only the host it was configured for. Without those checks any web page could rebind its own hostname to loopback and drive your device. A client that sets a browser style origin will be refused. **`GET` and `DELETE` on `/mcp` return 405.** The endpoint is stateless: there is no stream to resume and no session to tear down. Post your requests. # Reading a trace Source: https://docs.phoneuse.com/getting-started/trace What the control plane hands back, and how to confirm an action later. An agent driving a real device has to answer one question after every call: did that actually happen? PhoneUse answers it with a recorded outcome rather than with an acknowledgement, and gives you a way to look the answer up again after the fact. Three things carry that guarantee: the typed result, the idempotency key, and the observed frame. ## The typed result Every successful call returns typed `structuredContent`, shaped by the output schema that tool publishes. The same value is also written into a text block for older consumers, so a client that reads either one sees the same data. For an action, that value is an outcome: ```json theme={null} { "status": "committed", "committedAt": "2026-08-29T10:14:08.377Z", "idempotencyKey": "signin-button-1", "deduplicated": false } ``` Read it precisely. * `status: "committed"` means the **device** applied the action. It is not an acknowledgement that the request arrived. * `committedAt` is when the backend confirmed the commit, on the control plane's clock. * `deduplicated: true` means this response was replayed from the ledger and the gesture did not happen again. Failures never appear in this shape. A failed action is an error result, and errors have their own envelope. ## The idempotency key `idempotencyKey` is a short printable ASCII request id that you generate and pass with an action. Its exact length and character bounds are published in the [tool reference](/mcp/reference). It is optional, and it is worth passing every time. With a key of your own, a retry of a request whose response you lost replays what was recorded instead of pressing the glass a second time. Without one the control plane generates a key so the action is still recorded, but it cannot recognise **your** retry as a retry, because it never saw your first attempt's key. Two limits are worth knowing before you build a retry loop: * **A key that failed terminally will not replay into a fresh attempt.** Reusing it replays the recorded failure, and the error tells you to retry under a new key. Idempotency protects you from double execution; it is not a way to make a failed action run again. * **Some outcomes are genuinely unknown.** The error set includes a case for an action whose result the control plane could not establish. Treat it as neither done nor not done, and resolve it by reading the receipt rather than by retrying blind. > [!WARNING] > > Keys beginning with `agent:` are refused. That prefix belongs to the control > plane's own runs, and a caller able to write there could pre create receipts > for a run's future actions and have every one of them replay instead of > execute. Reuse a key only for the **same intended action**. A different tap under the same key is a conflict, not a retry. ## Looking an outcome up later When a response is lost, do not retry blind. Ask what happened: ```json theme={null} { "name": "get_receipt", "arguments": { "deviceId": "cloud-phone-01", "idempotencyKey": "signin-button-1" } } ``` ```json theme={null} { "found": true, "receipt": { "orgId": "org_local", "deviceId": "cloud-phone-01", "idempotencyKey": "signin-button-1", "backendKind": "adb_cloud", "action": "tap", "argsSummary": { "x": 500, "y": 820 }, "observedFrame": "frm_5b81...", "status": "committed", "requestedAt": "2026-08-29T10:14:07.905Z", "committedAt": "2026-08-29T10:14:08.377Z" } } ``` `found: false` is a normal answer, not an error. It means no receipt exists under that key, so the action never began, and the **same** key is safe to retry. Two fields deserve attention when a receipt is not simply committed: * `reason: "interrupted_by_restart"` means the control plane restarted while the action was in flight, so the request was closed as failed rather than guessed either way. * `reason: "outcome_unknown"` means the transport to the device was lost after dispatch. Whether the device acted is genuinely unknown. Both arrive with `requiresManualReview: true`. That flag exists because guessing is worse than admitting the gap: a person has to reconcile what the device actually did. `get_receipt` reads receipts, so it is available to a read only credential. A lease id and fencing token are never projected into it, because they are bearer credentials rather than audit fields. ## The observed frame `observedFrame` is the other half of the trace, and it works forwards rather than backwards. A screenshot issues a `frameId`. Pass that id back on the next action and the action is refused unless the frame is still the device's latest. A refusal comes back as `stale_frame`, telling you the screen moved between deciding and acting. There is no clock on it: a frame does not age out, so however long you spend deciding does not matter. This is what answers the classic worry of a vision driven loop: deciding on a picture and then tapping a screen somebody else has changed. It answers it by telling you: every action comes back with `others`, which says how many actions another principal took since the frame you named, when, and whether by a person or an agent. An agent that names a frame is also refused when that count is above zero, by default; pass `refuseIfOthersActed: false` to be told without being stopped. Naming a frame that was never issued is still an error, and so is naming one so far back that the control plane no longer holds it. Not every device supports it. A device whose capabilities report `framesAreReferenceable: false` has no visual observation to bind to, and passing `observedFrame` there is refused as `capability_unsupported`. ## How to consume an error Errors arrive with `isError: true` and come in exactly two shapes, so there is no ambiguity about how to parse one. 1. **A device or control plane error.** The text block is a JSON envelope with a stable `code`, a `message`, and `retryable`, plus any fields specific to that error. Branch on `code`. 2. **A schema rejection.** The text block is prose, and it will not parse as JSON. Your parameters were wrong. Fix them before resending. So: try to parse the text block. If it parses, branch on the code. If it does not, you have an argument problem. Errors never carry `structuredContent`. That is deliberate, because a standard MCP client validates any `structuredContent` it sees against the tool's output schema with no exemption for errors, and an envelope there would break it. The full list of codes is in the [error reference](/mcp/errors), and the common ones are explained in [Troubleshooting](/help/troubleshooting). ## Why usage and evidence agree The receipt ledger is the system of record. Usage is derived from it rather than counted separately, so what you are billed for and what you can look up with `get_receipt` are the same events. See [Metering units](/billing/units). # Buy and drive a device Source: https://docs.phoneuse.com/guides/first-device The whole loop, end to end, in the console and over the API, with the readings from a real run. This is the shortest complete thing you can do with PhoneUse: get a device and make it do something. Everything below was run end to end with a real card on a real device. The numbers are readings, not illustrations, except where a block says it is an example. > [!NOTE] > > **What it costs.** One cloud phone, billed monthly at the rate published on > [Billing modes](/billing/modes#rates): Cloud phone from $20 a month, Real phone > identity $39 a month. Payments are not refunded: a Cloud phone keeps its paid period, > and you stop the next charge with **Cancel order** on the Billing page. To rent by the minute > instead, see [Billing modes](/billing/modes#per-minute). > > **What you need.** A browser, an org **admin** sign in, and a card. Nothing > installed. About fifteen minutes. > > **What you do not need.** An API key, unless you want to do step 3. ## Step 1: Buy a device Go to **Add a phone** (`/devices/add`). The screen draws itself from `GET /v1/skus`, which is the deployment's actual price list. One entry per pair of thing and billing mode, and each Cloud phone model carries its own `price` and `quoteId`. A model whose price could not be read just now is still listed, but without `price` or `quoteId`, and it cannot be bought until a later read shows both; a purchase screen should offer a model only when it has both. An abridged example, not a reading: ```json theme={null} { "sku": "cloud_phone", "billing": "subscription", "models": [ { "id": "standard", "name": "...", "kind": "standard", "price": { "amountMinor": 2000, "currency": "usd" }, "quoteId": "price_...", "shipsNow": true } ], "shipsNow": true, "stock": "in_stock" } ``` Three things to read off that. `amountMinor` is the **minor unit**: `2000` with `currency: "usd"` means twenty dollars, not two thousand. Cloud phone prices include tax: any tax is inside the amount, not added on top. They come from the payment provider's own price objects, carried through unaltered; this service does no arithmetic on a charge. The current rate card is on [Billing modes](/billing/modes#rates), and [phoneuse.com](https://phoneuse.com/#pricing) is canonical if the two disagree. A pair this deployment holds no price for is **absent from the list** rather than shown without a number. So the list is exactly what can be bought here today, and a card you cannot see is not a card you are missing. `stock` says whether a free unit of that kind exists right now, and it has three answers: | `stock` | What it means for the buyer | | - | - | | `in_stock` | It can be bought now. Paying starts setting up your phone. | | `out_of_stock` | It is sold out right now. A checkout for it is refused before you pay. | | `unknown` | This deployment could not read its shelf just now. The price is real; how soon is not known. | `shipsNow` is the older field for the same answer: `true` exactly when `stock` is `in_stock`, so it cannot tell `out_of_stock` from `unknown`. > [!NOTE] > > On the hosted service, a model that is sold out in the region you chose is > refused with `409` `out_of_stock` **before** any payment, so you are never > charged for a phone that cannot be set up. Pick another model or region, or > try again later. `stock` is a verdict, never a count: how much stock is left > is not published. Press the buy button and the console starts a checkout with `POST /v1/checkout-sessions`, which hands back somewhere to send the browser: ```json theme={null} { "checkoutUrl": "https://...", "orderId": "...", "expiresAt": "..." } ``` The checkout is hosted by the payment provider. **Promotion codes are accepted** on it, so a code you were given goes in there rather than anywhere in this product. Pay, and the order settles on its own. You do not have to do anything to claim the device: the payment provider tells the control plane, your phone is prepared only after your payment and set up for you, and the device then appears in `GET /v1/devices` and on `/devices`. If you would rather be told than poll, the `fulfilment.changed` [webhook](/guides/webhooks) is the event for exactly this. > [!WARNING] > > Buying needs an org **admin**, signed in, or an API key that holds > `orders:place`. Only an admin can mint or approve such a key, and a person > still pays on the Checkout page, so a program cannot spend money while nobody > is watching. A member, and a key without that scope, answer `403`. An org can > buy as many phones as it needs; there is no "already subscribed" refusal. > Send an `Idempotency-Key` header and a retried checkout gets the first > answer back instead of opening a second one. ## Step 2: Drive it from the console Open **`/devices/:id`** for the device that appeared. 1. **Click the screen.** The picture is the tap target. The console turns where you clicked into a coordinate on the normalized grid and sends the tap. Your first tap takes a lease on the device for **ten minutes** if your org holds none; if an agent's run already holds one, your tap runs under it and the run keeps going. 2. **Keep clicking.** A lease you took yourself stays alive while you drive. 3. **Release the lease** when you are done, or let it expire. Read a disabled control as information rather than as breakage. A control the device cannot perform is drawn disabled and says `Action not supported on this device`. That is its `capabilities` block speaking. A cloud phone reports `tap`, `swipe`, `typeText: "native"`, `openApp: "intent"`, `installApp: "managed_store"` and every key in `pressKey`, and it has no element tree (`uiTree: false`). `installApp: "managed_store"` means apps are installed from the Apps page in the Console, not by sending a package to the phone. Release the lease before you wander off. Nothing pauses the clock while a lease is held, and nothing watches for idleness. A lease expires ten minutes after it was granted and can be renewed, and no lease lives longer than sixty minutes from when it was acquired, so the worst case is bounded but it is not free. ## Step 3: Drive it from the API Everything the console just did is three routes. Mint an API key at **`/keys`** with three of the eight scopes: `devices:read` to see it, `devices:lease` to take it, `devices:act` to touch it. Keys are for servers: an API key sent from a browser origin is refused with `api_key_from_browser_origin` whatever its scopes are. ```bash theme={null} export PHONEUSE_API_KEY="pbk__" export DEVICE= export BASE=https://mcp.phoneuse.com ``` ### Take the device ```bash theme={null} curl -sS -X POST "$BASE/v1/devices/$DEVICE/lease" \ -H "Authorization: Bearer $PHONEUSE_API_KEY" ``` ```json theme={null} { "deviceId": "...", "leaseId": "...", "acquiredAt": "...", "expiresAt": "..." } ``` `201`, and the request takes no body at all. Keep the `leaseId` (`export LEASE=...`): it is a credential, it is returned by this call and by no other, and every gesture and the release need it. A refusal does not say why, and that is deliberate. Somebody else holding the device, a spent quota and an unreachable device all answer the same way. ### Look at the screen ```bash theme={null} curl -sS "$BASE/v1/devices/$DEVICE/screenshot" \ -H "Authorization: Bearer $PHONEUSE_API_KEY" -o screen.jpg ``` `200`, `image/jpeg`. The measured run returned a 720 by 1280 frame of 52428 bytes. **You do not need the lease for this one.** Any credential in the org that can see the device can watch it, whoever is holding it, which is the point: a person should be able to see what a device is doing before deciding whether to interrupt it. Watching writes no receipt and returns no `frameId`. If you intend to bind an action to the exact frame you decided on, take the screenshot through the MCP `screenshot` tool instead, which issues one. See [Reading a trace](/getting-started/trace). ### Act ```bash theme={null} curl -sS -X POST "$BASE/v1/devices/$DEVICE/actions" \ -H "Authorization: Bearer $PHONEUSE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action":"tap","x":500,"y":500,"leaseId":"'"$LEASE"'"}' ``` ```json theme={null} { "deviceId": "...", "status": "committed", "committedAt": "...", "idempotencyKey": "..." } ``` `200`. `status` has exactly one value: an action that did not commit is an error, not a different status. The response resolves only once the **device** applied the gesture, which is why it is not instant. One tap measured today took 5076 ms from request to committed. Six gestures are available on this route, discriminated by `action`: | `action` | Fields it takes beyond `leaseId` | | - | - | | `tap` | `x`, `y` | | `long_press` | `x`, `y`, optional `durationMs` | | `swipe` | `fromX`, `fromY`, `toX`, `toY`, optional `durationMs` | | `type_text` | `text` | | `press_key` | `key` | | `open_app` | `appId` | `press_key` takes one of `home`, `back`, `enter`, `delete`, `app_switch`, `power`, `volume_up`, `volume_down`. Any of them can still be refused by a device that declared `pressKey: false`, which is the whole reason to read `capabilities` first rather than to assume a set. Every attempt is written to the receipt ledger **before** it is dispatched, so `GET /v1/receipts` can tell you what happened even if you lost this response. Send your own `idempotencyKey` and a retry replays that outcome instead of touching the phone twice. On this route it is a **field in the body**, not a header. (Checkout and some other routes take an `Idempotency-Key` header instead.) When you do not send one the service generates it and returns it, which is why the response above carries one you never chose. ### Give it back ```bash theme={null} curl -sS -X DELETE "$BASE/v1/devices/$DEVICE/lease" \ -H "Authorization: Bearer $PHONEUSE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"leaseId":"'"$LEASE"'"}' ``` The lease id goes in the **body of a DELETE**, which is unusual and deliberate: the id is a credential, and a query string is written to access logs, browser history and `Referer` headers. Releasing a device you do not hold does nothing, so a retry is safe. Working longer than ten minutes? `PATCH /v1/devices/{deviceId}/lease` with the same `leaseId` slides the expiry to ten minutes from now. It does not add ten minutes to the old one, and the `leaseId` does not change. Renew **before** it expires: an expired lease cannot be renewed, because by then the device belongs to whoever takes it next. ## When you are done with a device Devices are not returned online. A **Cloud phone** keeps its paid period: stop the next charge with **Cancel order** on the console's Billing page (`POST /v1/fulfilments/{id}/cancel-renewal`) and it stays yours until the paid period ends. For any other device, or a question about an order or a payment, contact support at [abdulla@phoneuse.com](mailto:abdulla@phoneuse.com) and we'll help. `POST /v1/fulfilments/{id}/return` and `POST /v1/fulfilments/{id}/cancel` both answer `409` `wrong_state` with that support address, and nothing is changed or refunded. > [!NOTE] > > **Robot hand + iPhone: buy it in the console.** In **Add a phone**, choose > **Robot hand + iPhone** and pay \$149 a month per robot at checkout. We prepare > it within **24 hours after payment**. It is not part of the API, MCP or CLI > today. ## What you were charged * **The device**, every 30 days, at the published rate. The first charge covers a slightly shorter first period (about 28 days), so that every later charge lands two days before the phone's 30-day term ends. Payments are not refunded. * **Active time is not a separate line on a monthly device.** A monthly device has no meter: run it all the time and the invoice reads the same. Per minute phones are the other way to pay, from a prepaid balance. See [Billing modes](/billing/modes). * **Agent steps are metered but not separately priced.** Steps are included in the device price today, and no separate step rate is published. There is **no dollar limit you can set**. The limits that actually stop something are a per minute phone's prepaid balance, the lease expiry and a run's own step budget. See [Spending controls](/billing/spending-controls). ## Where to go next > [card] [Webhooks](/guides/webhooks) > > Be told when a run ends instead of polling for it. > [card] [Agent tier](/agent/overview) > > Hand a goal to a worker instead of driving each step yourself. > [card] [The console](/getting-started/console) > > Every screen, and the surfaces that have no screen. # Install apps from the App Store Source: https://docs.phoneuse.com/guides/upload-app-package Choose an approved app for your phone and follow its installation result. Install apps from the **Apps** page in the Console (`https://console.phoneuse.com/apps`). Choose your phone, then select **Install** on an available app. The App Store selects an approved build and saves the request. You can close the page while the server continues checking the installation. The result becomes **Installed** after a fresh phone inventory confirms that build. An unconfirmed result holds further installation on that phone while the server checks the original request. Reopening Apps shows the same saved result. The CLI and the MCP tools do not install apps. They can read and refresh the apps currently installed on a phone, and each points you to the Apps page. Inventory can include apps installed through other routes; it does not require an App Store request to exist. Customer APK uploads, custom app libraries, and arbitrary URL installation are retired, including public custom APK job history. Original request recovery and accepted App Store results remain available. Availability depends on the phone's current installation capability and the approved build being enabled. A phone reports `installApp: "managed_store"` in its capabilities when apps can only be installed from the App Store. ## The REST API The Console uses the managed App Store REST operations, and they are available to other callers with the same permissions. They are described under **Apps** in the API reference. Installing is a write that must carry an `Idempotency-Key` header in one exact form, because the server uses it to recognise the same request again: ```text theme={null} store.v2.<24 hex characters>. ``` The 24 hex characters are the first 24 characters of a SHA-256 over the account, phone, profile, app and build, worked out like this: 1. `who = JSON.stringify([orgId, subject])`, where `subject` is the signed-in person's `userId`, or the `apiKeyId` when an API key makes the call. The `apiKeyId` is the `id` field of `GET /v1/api-keys/current` (not its `keyId`, which is the public half of the token). 2. `payload = JSON.stringify([who, deviceId, scopeId, appId, buildId])`. `scopeId` is `user_0`. 3. Take the SHA-256 of `payload` as lowercase hex and keep the first 24 characters. 4. Join them as `store.v2..`. For example, `orgId` `org_example`, `apiKeyId` `key_example`, `deviceId` `device_example`, `scopeId` `user_0`, `appId` `telegram`, `buildId` `v12.10.1` and UUID `6f1c2a52-3b6e-4d0c-9a57-0d3c8f0b1e11` give: ```text theme={null} store.v2.e22bfe7f226ee0e308ab9fe3.6f1c2a52-3b6e-4d0c-9a57-0d3c8f0b1e11 ``` A key built for another account, phone, app or build is refused with `400`. If an answer is lost, send the same body with the same key to get the same installation back, or read it with `GET /v1/app-store/installations/by-request/{requestKey}`. A second key is a new request and is refused while the phone is held. # Webhooks Source: https://docs.phoneuse.com/guides/webhooks Be told when a run ends, when it needs a person, and when an order changes. Polling a run to find out when it finished works, and it is the wrong shape for anything that runs unattended. A webhook subscription turns those moments into requests against an endpoint you own. > [!NOTE] > > **What it costs.** Nothing. Subscriptions are not metered, and a delivery is not > a step. > > **What you need.** An API key with `devices:read`, and an **https endpoint > reachable from the public internet**. Your laptop behind a private address will > be refused at subscribe time, not at delivery time; use a tunnel or a deployed > endpoint. > > **You can also do this in the console**, on the **Webhooks** page under > **Developers** (`/webhooks`). ## Subscribe ```bash theme={null} curl -sS -X POST "$BASE/v1/webhooks" \ -H "Authorization: Bearer $PHONEUSE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com/hooks/phoneuse","events":["run.ended"]}' ``` `201`, and the response carries the signing secret **once**: ```json theme={null} { "webhook": { "webhookId": "...", "url": "https://example.com/hooks/phoneuse", "events": ["run.ended"], "enabled": true, "secretHint": "...", "createdAt": "...", "secretRotatedAt": null }, "secret": "whsec_..." } ``` Store the secret now. To get another you have to rotate, and rotating stops the old one working. `secretHint` is its last four characters, which is there so you can tell which secret you configured without holding the secret to compare. An org may hold up to **20** subscriptions. ### What the destination must be The url is checked when you subscribe, and a refusal names which rule you hit: `not_a_url`, `scheme_not_https`, `has_credentials`, `private_address`, `too_long`. It must be `https`, must carry no credentials in it, must be at most 2000 characters, and must not be a private, loopback or link local address. That last one is not a style preference: this service would be the one making the request, so an address inside a private network is an instruction to probe somebody's network from ours. ### The events | Event | When | `data` carries | | - | - | - | | `run.ended` | A run reached a terminal state, however it got there | `agentRunId`, `runId`, `deviceId`, `state`, `goal`, `stepSeq`, `reason`, `detail` | | `run.needs_user_control` | A worker parked a run because it needs a person | `agentRunId`, `deviceId`, `goal`, `deadlineAt` | | `fulfilment.changed` | An order became `provisioned` or `awaiting_provisioning`, or ended as `cancelled` with `deviceId` `null`. `cancelled` is sent when the payment provider ends the subscription or refunds or disputes it (including a refund our team makes by hand). Orders cannot be cancelled or returned online, so the `cancel` and `return` routes end nothing and send nothing. It is not sent for an owner refund from the operator surface, the undelivered-order sweep or a Cloud undelivered resolution; reconcile those with `GET /v1/fulfilments` | `fulfilmentId`, `state`, `deviceId` | An unknown event name is **refused** rather than ignored, so a typo fails at subscribe time instead of producing a subscription that never fires. `reason` and `detail` on `run.ended` are present and `null` rather than absent when there is nothing to say. A receiver branching on why a run ended needs to tell "no reason" apart from "not told". ## The body ```json theme={null} { "deliveryId": "...", "event": "run.ended", "occurredAt": "2026-09-13T10:24:12.004Z", "data": { "agentRunId": "run_...", "state": "succeeded", "...": "..." } } ``` `occurredAt` is when the **event** happened, not when this attempt was made. `data` is deliberately shallow and carries ids rather than nested records. A receiver that needs the run reads `GET /v1/runs/{agentRunId}`, which is the one definition of what a run is. Embedding a copy here would publish a second one that drifts. Three headers come with it: | Header | What it is | | - | - | | `PhoneUse-Event` | The event name, so a router does not have to parse the body first | | `PhoneUse-Delivery` | The delivery id, **the same on every retry**. Deduplicate on it | | `PhoneUse-Signature` | `t=,v1=` | ## Verify the signature The hex is **HMAC-SHA256** of `.` under your secret. ```js theme={null} import { createHmac, timingSafeEqual } from "node:crypto"; function verify(rawBody, header, secret, toleranceSeconds = 300) { const parts = Object.fromEntries( header.split(",").map((p) => p.split("=", 2)) ); const t = Number(parts.t); if (!Number.isFinite(t)) return false; if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false; const expected = createHmac("sha256", secret) .update(`${t}.${rawBody}`) .digest("hex"); const a = Buffer.from(expected, "hex"); const b = Buffer.from(parts.v1 ?? "", "hex"); return a.length === b.length && timingSafeEqual(a, b); } ``` Three things that are easy to get wrong: 1. **Compute over the raw bytes you received**, before any JSON parsing. A body that has been through `JSON.parse` and back is not the body that was signed. 2. **Compare in constant time.** A byte at a time comparison leaks the answer. 3. **Check `t` against your own clock.** The timestamp is inside the signed material precisely so that a captured delivery cannot be replayed at you a year later. The reference verifier uses a 300 second tolerance. ## Delivery is at least once Plan for a duplicate. Deduplicate on `PhoneUse-Delivery`. * A non 2xx answer is retried, **5 attempts in all**, with gaps of 30 seconds, 2 minutes, 5 minutes and 18 minutes, so about twenty five minutes from first to last. Then it is given up on. * Each attempt gets **10 seconds** before it times out. * **Redirects are not followed.** A `30x` is recorded as the answer it is, because following one would send your payload to a url nobody checked. * Answer `2xx` fast and do the work afterwards. An endpoint that does its processing before replying will be retried while it is still working. ## Test it before you trust it ```bash theme={null} curl -sS -X POST "$BASE/v1/webhooks/$WEBHOOK_ID/test" \ -H "Authorization: Bearer $PHONEUSE_API_KEY" ``` `202` with `{ "deliveryId": "...", "status": "pending" }`. It queues one delivery on the **same path a real event takes**: same signature, same headers, same retries. It answers as soon as the delivery is queued rather than waiting for your endpoint, so read the outcome from the deliveries listing. It arrives as `run.ended` with `test: true` in the `data`, because a test that came in as something your router does not recognise would exercise the transport and nothing else. ## Read what happened ```bash theme={null} curl -sS "$BASE/v1/webhooks/$WEBHOOK_ID/deliveries?limit=20" \ -H "Authorization: Bearer $PHONEUSE_API_KEY" ``` Newest first, `limit` between 1 and 100 and 50 by default, paged with the `nextBefore` cursor the response hands back. Each row says what was tried and what came of it: `status`, `attempts`, `responseStatus`, `error`, `payloadPreview` (the delivered body, truncated), `lastAttemptAt` and `nextAttemptAt`. Read `status` carefully. `pending` covers both never tried and waiting to retry. `failed` means **every attempt is spent**, not that your endpoint said no. `responseStatus` is `null` when the attempt never got one, and `error` then says why: a timeout, a refused connection, a name that did not resolve. > [!NOTE] > > `payloadPreview` is the fastest way to see the exact shape of an event you > have not handled before. Subscribe, fire one, read the preview. ## Turning one off, and rotating its secret | | Route | What it does | | - | - | - | | Disable | `PATCH /v1/webhooks/{webhookId}` with `{"enabled": false}` | Receives nothing. Deliveries already queued for it are **not** retried either | | Rotate | `POST /v1/webhooks/{webhookId}/rotate` | New secret returned once, and the old one stops working **immediately** | | Delete | `DELETE /v1/webhooks/{webhookId}` | Removes it and its delivery records with it | > [!WARNING] > > Rotation has **no overlap window**. A receiver still verifying with the old > secret will reject every delivery from that moment. Put the new secret in > place first, or accept a gap. Disable rather than delete when you want to keep the history: a delivery log for a subscription nobody can see is a log nobody can interpret, so deleting takes it too. ## Scope and tenancy Every webhook route needs **`devices:read`** and nothing else. There is no role gate: a member with that scope can manage subscriptions. A `webhookId` belonging to another org answers `404`, the same `404` an id that names nothing gets. This is not an existence oracle. ## Where to go next > [card] [Runs](/agent/runs) > > What `state`, `reason` and `detail` on `run.ended` mean. # Help Source: https://docs.phoneuse.com/help/overview Where to look, in the order that usually works. Most questions land in one of a few places. Start with the one that matches what you are actually holding. ## Start by what you have > [card] [An error you do not recognise](/help/troubleshooting) > > Symptoms, what each one means, and what to do about it. > [card] [A client that will not connect](/getting-started/mcp-config) > > The exact config block for each transport, and the two checks that refuse > a request. > [card] [A tool that is missing from the list](/mcp/auth) > > Scopes are enforced at registration, so an out of scope tool is absent > rather than refused. > [card] [A device that will not do something](/devices/capabilities) > > Abilities are declared per device. Read the capability block first. > [card] [An action whose response you lost](/getting-started/trace) > > Look the outcome up by its idempotency key instead of retrying blind. > [card] [A question about what you are charged for](/billing/units) > > What is counted, on which axis, and what is deliberately not. > [card] [A key or token that leaked](/security/leaked-credentials) > > Revoke rather than rotate, and what the ledger can and cannot tell you. > [card] [A worry about the size of the bill](/billing/spending-controls) > > What bounds your spend today, including the cap that does not exist. > [card] [A capability you are not sure exists](/help/what-phoneuse-is-not) > > The boundaries of this surface, so you can rule it in or out quickly. ## Reference material Three pages are generated from the source rather than written by hand, so they are the ones to trust when prose and behaviour disagree: * [Tool reference](/mcp/reference), generated from the registered schemas. * [Error reference](/mcp/errors), generated from the error code set. * [Command reference](/cli/commands), generated from the CLI parser. If any of those disagrees with a page written in prose, the generated page is right. Tell us, and we will fix the prose one. ## Reading the site as an agent See [For agents](/getting-started/for-agents) for the machine readable views this site publishes, and for how to tell the documentation MCP server apart from the one that drives devices. > [!NOTE] > > Frames are stored. Since 2026 09 08 every frame a run captures is kept in > private object storage. Read one back with `GET /v1/frames/{frameId}`, which > returns a short-lived signed link. See > [Frame retention](/security/frame-retention). ## What is not live yet * Interactive OAuth sign-in from a generic MCP client. The authorization server is the configured Clerk issuer, which offers no dynamic client registration, and no third party client has been verified to complete the flow. The hosted endpoint (`https://mcp.phoneuse.com/mcp`) is reached with an API key. See [Getting a key](/mcp/auth#getting-a-key). * Some backend kinds are declared but have no adapter behind them yet. See [Capabilities](/devices/capabilities) for which ones you can reach. ## Getting in touch Rates live on [phoneuse.com](https://phoneuse.com), which is the canonical price list. Sign up yourself at [console.phoneuse.com/sign-up](https://console.phoneuse.com/sign-up). Buy the robot hand in the console's **Add a phone**: \$149 a month per robot, prepared within 24 hours after payment. For a demo or Enterprise, [book a call with our team](https://cal.com/abdulla-ababakre-wubx6e/phoneuse?overlayCalendar=true). For anything else, write to [abdulla@phoneuse.com](mailto:abdulla@phoneuse.com). This documentation restates the rates on [Billing modes](/billing/modes) so you can read them next to what they meter, and if the two ever disagree, the site wins. **There is a self serve path.** You can sign in, buy a device, drive it from a browser and mint an API key, without talking to anybody. See [The console](/getting-started/console) for the screens and [Buy and drive a device](/guides/first-device) for the whole loop. The console and this API are the same control plane: every screen calls the routes these docs describe. A few surfaces have no screen at all and are API only, which [The console](/getting-started/console#what-has-no-screen) lists. # Troubleshooting Source: https://docs.phoneuse.com/help/troubleshooting Symptoms, what each one is telling you, and what to do next. Work in this order: recognise the shape of the failure, then read its code, then act. Guessing from the message text is the slow path. ## First, know which shape you have An error result arrives with `isError: true` and comes in exactly two shapes. 1. **A JSON envelope** in the text block, carrying a stable `code`, a `message`, and `retryable`. This is a device or control plane error. 2. **Prose** in the text block, which will not parse as JSON. This is a schema rejection: your parameters were wrong. So: try to parse the text block. If it parses, branch on `code`. If it does not, fix your arguments and do not resend the same call. Errors never carry `structuredContent`. Every code is listed in the [error reference](/mcp/errors). ## Signing up **I submitted the sign-up form and nothing happened.** Sign-up runs a short human check in the background. A browser slows down background work in a tab that is not in front, so if you switched to another window while it ran, the check may not have finished and the form waits without saying so. Bring the tab to the front, wait a few seconds, and submit again. What you typed is still in the form. ## Connection and authentication **A tool I expect is missing from `listTools`.** That is authorization, not a fault. Scopes are enforced when tools are registered, so a tool outside your credential's scopes is never registered and genuinely does not exist on your connection. Check your key's scopes. If the missing tools are the run tools, note they need `runs:start` **and** `devices:act`. See [Authentication](/mcp/auth). **`401`, with a reason in the body.** Read the reason. `missing_credentials` means no `Authorization` header arrived. `malformed_credentials` means the header was not a usable bearer value. `invalid_token`, `token_expired` and `wrong_audience` are about a JWT. `unknown_key`, `revoked_key` and `expired_key` are about an API key. `unknown_key` deliberately covers both "no such key" and "wrong secret". There is no way to tell them apart, and that is on purpose. **`503` from the authentication path.** The credential store or the authorization server could not be reached. This is fail closed by design: an outage refuses requests rather than letting them through. Retry. **My client is refused before it authenticates.** Two checks run first. The endpoint accepts only the host it was configured for, and it refuses any request carrying a browser `Origin` header. A client that sets a browser style origin will be refused no matter what credential it has. See [Transports](/mcp/transports). **`405` on `/mcp`.** You sent `GET` or `DELETE`. The endpoint is stateless, so there is no stream to resume and no session to end. Post your requests. **`429`, with `rate_limited` in the body.** You are over your request budget. Note the shape: this is a transport level `429` carrying the HTTP error envelope, **not** a tool result with `isError`, because the limiter runs before the MCP endpoint is reached. So a client that only inspects tool errors will see a transport failure here. Wait the number of seconds in `Retry-After` and retry the same request. The refusal happens before any work, so nothing was half applied. Do not retry in a tight loop; the allowance refills on a clock and retrying faster cannot speed it up. `RateLimit-Remaining` on your earlier responses would have told you this was coming. See [Rate limits](/api/rate-limits). ## Leases **`lease_required`.** Your organization does not hold that device right now, and this call could not take it for you. Either you named a `leaseId` that is gone (naming one is a claim that you hold the device, so it is answered rather than quietly turned into a new take), or your credential has no `devices:lease` and so may act only on a device your organization already holds, or the lease ended while your action waited its turn behind others. Take the device and try again: a gesture sent with no `leaseId` takes it for you when your credential may. **`lease_mismatch`.** The `leaseId` you supplied does not match the current lease. Actions, run starts, renewals, and releases refuse it before changing the phone. Refresh the lease view, then use its current id, or omit the id where the operation allows that. Authentication and your organization's possession are still required; knowing an id alone grants no access. **`acquire_device` fails on a device that looks idle.** A device holds one lease at a time, across every org. Somebody else holds it, or a previous run of yours did not release. Leases expire on their own, so waiting works, and reading `expiresAt` from the holder's acquire response is better than guessing. A person in your org who wants to act on the device does not need to acquire: the console acts under the lease your org holds. **An action answered `stale_frame` with reason `others_acted`.** Somebody else acted on the device after the frame you decided on, and your action was bound to that frame. This is the default for an API key, a copilot or a run that sends `observedFrame`, and what `refuseIfOthersActed: true` asks for. Nothing physical happened and your idempotency key was not consumed: take a new screenshot, decide again, act again. Send `refuseIfOthersActed: false` to be told through `others` without being refused. **An action answered `stale_frame` with reason `look_first`.** A person looked at the phone and said it looks right after one of your run's own actions that could not be confirmed. Nothing physical happened: take a new screenshot, decide on it, and act again. The first screenshot your run is served after that clears it. **Looks right is not offered yet for an action that could not be confirmed.** An action a signed-in person did not make directly waits 30 seconds after it ended before anyone can confirm it, so a late result has time to show on the screen first. That covers agent tasks, Copilot, API keys and every other caller that is not a person. `GET /v1/devices/{deviceId}/unclear-actions` gives `retryAfterMs` for each one still waiting. A person's own action has no wait. **An action answered `device_busy`.** Nothing was sent. Either too many actions were already waiting on that device, or an earlier action on it has not finished or is still being confirmed (for example an app install). Actions run one at a time per device in arrival order, and a bounded number may wait. Nothing you already sent was dropped. Retry after `retryAfterMs` (when present) with a new `idempotencyKey`: the refusal may already have recorded the old one as failed, and a same-key retry would replay that. **A run ended with `lease_lost`.** The device moved to another holder while the run was going. The run is ended immediately on purpose, so a worker does not spin against refusals for the rest of its deadline while occupying one of your concurrency slots. ## Actions and observations **`stale_frame`.** The frame you passed as `observedFrame` is no longer the device's current screen. This is the guard working: the screen changed between your decision and your action. Observe again, decide again, act again. A frame does **not** age out, so this is never about how long you took. Take as long as you need between observing and acting. The exception is a device whose own resource expires frames, which answers reason `expired`; a non-`null` `freshnessMs` in its capabilities is how you know to expect that. Nothing physical was attempted, and your idempotency key was not consumed, so you can retry the same intent under the same key. **`capability_unsupported`.** The device cannot do what you asked. Read its capability block: the key you pressed may not be in its `pressKey` list, it may have no UI tree, or you may have passed `observedFrame` to a device whose frames are not referenceable. See [Capabilities](/devices/capabilities). **`backend_not_implemented`.** The device's `backendKind` is a declared kind with no adapter behind it yet. The device row is valid; the mechanism does not exist. See [Capabilities](/devices/capabilities) for which kinds you can reach today. **`device_unavailable` or `device_disconnected`.** The device is not reachable right now. Both are retryable. `get_device` will tell you its current status without enumerating the fleet. **`invalid_argument`, or a prose rejection.** Your parameters. Unknown keys are rejected rather than dropped, so a misspelling fails here rather than reaching the device with a missing value. Coordinates must be on the 0 to 1000 grid. ## Retries and outcomes **I never got a response to an action.** Do not retry blind. Call `get_receipt` with the same `idempotencyKey`. * `found: false` means the action never began. The same key is safe to retry. * A committed receipt means it happened. Do not do it again. * A failed receipt tells you why it failed. **`idempotency_conflict`.** You reused a key for a different action. A key identifies one intended action, not a session. Use a new key. **A receipt says `outcome_unknown` with `requiresManualReview`.** The transport to the device was lost after the action was dispatched. Whether the device acted is genuinely unknown, and the control plane refuses to guess in either direction. A person has to check the device. **A receipt says `interrupted_by_restart`.** The control plane restarted while the action was in flight, and the request was closed as failed rather than left pending. Same treatment: check before repeating anything that matters. **`action_outcome_unknown`.** The live form of the same situation. Treat it as "check, do not repeat". ## Agent tier **`run_not_found`.** No run under that id for your org. A run belonging to another org reports identically, so this never tells you a foreign run exists. Run records are stored, so a restart does not lose them: `GET /v1/runs` lists your org's runs. **A run ended `canceled` after the API restarted.** A run PhoneUse was driving when the API restarted is not picked back up. It ends `canceled` by itself once the earlier of its saved time and 10 minutes has passed, sends `run.ended` and frees the phone. Start a new run. The one exception: if an action from before the restart has an unclear outcome, that action still holds the phone after the run ends, and a new run can still be refused. See [Runs](/agent/runs). **My worker got `409` with "no further steps".** The run reached its step budget, or its deadline passed. The step budget refuses the next frame; it does not by itself end the run. Raise `maxSteps` on the next run, within the deployment's own ceiling, which a caller cannot raise. **My worker got `503` on `screenshot`.** A frame is metered before it is served, and a frame that cannot be counted is not served. Treat it as retryable, and specifically do **not** read it as the device being unreachable. See [Device surface codes](/mcp/errors#device-surface-codes). **A run is stuck in `needs_user_control`.** It is parked, waiting for a person, and it stays parked until one acts. No frames are served and no actions accepted meanwhile. A worker cannot lift its own handoff: resume it with `resume_run` or the equivalent REST call. See [Runs](/agent/runs). On a run PhoneUse drives, a goal that needs a person from the start (paying, buying, erasing, changing a password and the like) is different: it ends as `succeeded` only when a person signed in to the console presses **Done** on the phone. A resume from an API key, the CLI, a third-party app or Copilot leaves it waiting. To stop it instead, cancel it with `cancel_run`, `POST /v1/runs/{runId}/cancel` or `phoneuse runs cancel `; it then ends `canceled`. **An org cannot start any more runs.** There is a concurrency ceiling per org. Runs that are terminal or past their deadline do not count against it, and a run past its deadline is reclaimed the next time anything looks at it, so monitoring a stale run can free the slot. ## Local setup **Run `doctor` before anything else.** ```bash theme={null} phoneuse doctor ``` From a source checkout of the control plane, the same check is `corepack pnpm cli doctor`. It checks the setup problems people actually hit: an old Node version, a control plane that is not answering, and a key that is missing or refused. Each failing check prints its own fix, and any failure exits non zero. **The control plane refuses to start, saying the receipt ledger is held.** Another control plane process is already running over the same devices. Two of them would each keep their own view of who holds a lease and could hand one physical device to two callers, so the second refuses at boot. Stop the first, or give this one its own ledger path. ## Still stuck Write to [abdulla@phoneuse.com](mailto:abdulla@phoneuse.com). A person reads it. Include what you called, what came back, and the time. If the failure was an HTTP response, the `fly-request-id` header on it lets us find the request itself. If a generated reference page disagrees with a page written in prose, the generated one is right. Everything else, including access and rates, is on [phoneuse.com](https://phoneuse.com). # What PhoneUse is not Source: https://docs.phoneuse.com/help/what-phoneuse-is-not The boundaries of this surface, so you can rule it in or out quickly. Most of this site describes what the control plane does. This page describes what it does not, because finding that out three days into an integration is expensive and finding it out here is free. Nothing below is a soft no with a roadmap behind it unless it says so. ## Driving a phone does not change its network or identity This surface drives a device. The tools that drive it do not change how that device appears to the software running on it. * **A proxy is not set by a device tool.** You cannot select an exit address or a network route through the device or MCP tools. Managed proxies are on the roadmap and not offered yet. The console keeps its **Proxy** page, and while proxies are off the proxy routes (`POST /v1/proxy-operations`, `GET /v1/devices/{deviceId}/proxy`) answer `422 capability_unavailable`. See [The console](/getting-started/console). * **Phone identity is chosen when you buy.** A **Real phone identity** cloud phone is a named phone model (a Pixel, a Galaxy) that you pick when you buy it. No tool on this surface writes a phone's identifiers or changes its model after that. * **No account isolation features.** Nothing here is built to keep separate accounts from being associated with each other. These are deliberate boundaries rather than gaps. Network and identity are chosen when you buy a phone or set up its proxy, not by the tools that drive the phone. ## It runs your tests on cloud phones PhoneUse can do test automation. Your test runner or CI takes a phone, acts on it and reads back what happened, and every action comes back as a receipt, so a test can check what the device actually did. A few pieces come from your own tooling rather than from PhoneUse: * **Your test code makes the pass or fail call.** A run reports `succeeded`, `failed` or `needs_user_control`, and `succeeded` means the worker reported the goal reached. For a strict verdict, check the screen or the receipts in your own test code. * **Your CI decides when and where tests run.** One call addresses one device, and there is no built-in schedule. Start sessions or runs from your CI or cron, one per phone, to cover several phones. See [CLI in CI](/cli/ci-cd). Two limits to know: * **Managed apps only.** Install approved builds from the Console [App Store](/guides/upload-app-package). Customer APK uploads, custom app libraries and arbitrary URL installation are retired. Installation history and the apps currently on a phone remain readable. * **No run that survives a restart.** See [Agent tier](/agent/overview#what-version-1-does-not-do). For a managed setup for a larger team, [book a call with our team](https://cal.com/abdulla-ababakre-wubx6e/phoneuse?overlayCalendar=true) about the Enterprise plan. ## It does have a self serve entry You can sign in, buy a device, drive it from a browser and mint an API key, without talking to anybody. See [The console](/getting-started/console) and [Buy and drive a device](/guides/first-device). Two things are genuinely narrower than "self serve" suggests, and both are boundaries rather than gaps: * **Buying needs an org admin.** An admin buys from a signed in session, or grants an API key `orders:place`, and a person still pays on the Checkout page. A member cannot commit the org to a purchase and gets `403`. * **Nothing is returned online.** Devices are not returned and payments are not refunded online. On a monthly phone, **Cancel order** on the console's Billing page stops the next charge. For anything else, write to [abdulla@phoneuse.com](mailto:abdulla@phoneuse.com). There are two ways to pay: **monthly**, billed every 30 days, and **per minute**, from a prepaid balance. See [Billing modes](/billing/modes). ## It has no spend cap you can set There is no dollar limit you can set. The limits that do stop something are a per minute phone's prepaid balance, the lease expiry and a run's own budget, and they are collected on [Spending controls](/billing/spending-controls). ## It does not video record a session Frames **can be archived** when the deployment has frame storage configured. The default archive policy has no automatic expiry; an organisation can have a different configured policy. Read one available frame with `GET /v1/frames/{frameId}`, using a frame id from a run or action receipt. See [Frame retention](/security/frame-retention) for storage, access and retention limits. The archive holds individual captured frames. It is not a video or a scrubbable timeline, and it does not record anything the agent did not look at: a frame exists because something asked for one. Continuous screen capture is not what this is. ## What it is Worth restating after all of that. One interface to a cloud Android phone, with the same tool calls and the same normalized coordinates on every phone. Every action comes back as a receipt you can look up, every observation can be bound to the frame you decided on, that frame is still there when you go looking for it, and a retry under the same key replays its recorded outcome instead of acting twice. See [Quickstart](/quickstart) to start. # PhoneUse docs Source: https://docs.phoneuse.com/index The mobile execution layer for AI agents. PhoneUse is a control plane that gives an agent one interface to a phone. Today that is a cloud Android phone you buy or rent in the console. Every phone takes the same tool calls, so when a task needs a different phone, the device you name changes and your code does not. Every run comes back as evidence. Actions report when the device committed them, observations are bound to the frame you decided on, and a retry that reuses its key replays the recorded outcome instead of acting twice. ## Start here > [card] [Open the console](https://console.phoneuse.com/sign-up) > > Make an account and an organization, then mint the key every page below > assumes you already have. Start here if you have never signed in. > [card] [Chat with your phone](/copilot/chat) > > Say what the phone should do and watch it happen, without writing a client > first. > [card] [Quickstart](/quickstart) > > Paste a config, run a session, read the trace. Three steps. > [card] [MCP config](/getting-started/mcp-config) > > The exact config block for each transport. > [card] [First session](/getting-started/first-session) > > Acquire, observe, act, release, one call at a time. > [card] [Reading a trace](/getting-started/trace) > > What the control plane hands back, and how to confirm it later. ## Go deeper > [card] [MCP surface](/mcp/overview) > > The tool surface an agent drives, and the contract that keeps it stable. > [card] [Device tiers](/devices/tiers) > > How input reaches a device, and which tier your devices are on. > [card] [Agent tier](/agent/overview) > > Hand a goal to a worker instead of driving each step yourself. > [card] [CLI](/cli/overview) > > The same control plane from a terminal. > [card] [Security and tenancy](/security/org-isolation) > > Where the org boundary runs, and who enforces it. > [card] [Billing and metering](/billing/units) > > What is counted, and what is deliberately not. ## Reading this site as an agent This site publishes machine readable entry points, and a docs MCP server that is separate from the one that drives devices. See [For agents](/getting-started/for-agents) before you connect either. > [!NOTE] > > The PhoneUse hosted MCP endpoint is `https://mcp.phoneuse.com/mcp`. It is > reached with an API key rather than an interactive sign in. Where a page > describes something you cannot reach yet, it says so, and > [What is not live yet](/help/overview#what-is-not-live-yet) keeps the list. > Rates live on [phoneuse.com](https://phoneuse.com), and **Add a phone** in > the console shows the phones on sale. # Authentication Source: https://docs.phoneuse.com/mcp/auth Two credential channels, eight scopes, one authorization context. Two credential channels reach the control plane. A JWT from the authorization server is how the PhoneUse console calls it for a signed in person. An API key is how everything else calls it, and it is the channel to use from an MCP client today. Both go through one pipeline. Both channels resolve into the same authorization context, so nothing downstream ever branches on which credential you used. ## The two channels | | OAuth 2.1 | API key | | - | - | - | | For | The console, for a signed in person | MCP clients, the CLI, and headless callers | | Token | A JWT from the authorization server | A `pbk_` prefixed key. The API and CLI [0.5.0](https://www.npmjs.com/package/@phoneuse/cli/v/0.5.0) and later also accept `puk_`; CLI [0.4.1](https://www.npmjs.com/package/@phoneuse/cli/v/0.4.1) does not | | Scopes | Device and run scopes for either org role; admins also hold `orders:place` | Exactly the scopes the key was issued with | | Device access | The org's devices | The org's devices, optionally narrowed to a subset | Routing between them is by shape, not by configuration. A bearer value starting with `pbk_` or `puk_` goes to the API key channel and anything else is treated as a JWT. The two cannot be confused: a JWT contains dots and a key token never does. ## OAuth 2.1 The control plane is a **resource server only**. It does not issue tokens, run an authorization endpoint, or register clients. Those belong to an external authorization server. Discovery follows RFC 9728. A client fetches protected resource metadata from the endpoint and learns which authorization server to talk to: ```text theme={null} GET /.well-known/oauth-protected-resource GET /.well-known/oauth-protected-resource/mcp ``` Both paths are served, because clients try both. ### What is verified about the flow Check the endpoint's protected resource metadata and its configured issuer's discovery document when setting up an integration. The earlier discovery check found: * The hosted endpoint's metadata names one authorization server, the configured Clerk issuer, and lists the [scopes](#scopes) below. * That server's own metadata (`/.well-known/oauth-authorization-server`) has `registration_endpoint: null`, so dynamic client registration is not available. It advertises the authorization code grant with PKCE (`S256`), and the scopes it advertises do not include `devices:read`, `devices:act`, `devices:lease`, `runs:start` or `orders:place`. So a generic MCP client cannot register itself and finish a browser sign in against this endpoint. A client would need a client id registered in advance with that Clerk instance, and access tokens whose audience matches the deployment's configured resource and which carry your org as a claim. The PhoneUse resource target is `https://mcp.phoneuse.com/mcp`; changing a domain does not itself update the issuer or token audience. A pre-registered app completed this flow before the domain change. If you cannot register an app in advance, use an [API key](#api-keys). Tokens are verified offline against the authorization server's published keys. Verification checks the audience as well as the signature, so a token minted for something else is refused even when it is validly signed. The `resource` value advertised in the metadata is the same value the verifier checks, which means a client can never be sent to fetch a token this server would then reject. The org comes out of a claim on the token, using the same claim name the database's row level policies read. There is no such thing as an authenticated caller without an org. ### Tokens issued to an OAuth app The console's tokens carry your org role as a claim. A token Clerk issues to an OAuth app through the authorization code flow (for example a third party MCP client) carries the org and never a role: Clerk puts no custom claims on those tokens. For that token shape, and only that one, this server asks the issuing Clerk instance which role you hold in the named org, and caches the answer for up to 90 seconds. Removing someone from an org, or changing their role, therefore reaches this path within about a minute and a half. Three outcomes are specific to it. They use reasons that already exist, and the `hint` in the body says which case you hit: * `invalid_token` (`401`) with a hint saying you are not a member of this organization: the account is not a member of the org the token names, for example because it was removed after signing in. Sign in again and pick an org you belong to. * `missing_org_role` (`401`) with a hint naming an OAuth app: this deployment cannot ask the Clerk instance that issued the token. That is our configuration, not your credential, so retrying and signing in again both fail the same way. * `503` when Clerk does not answer in time or answers with an error. It is never turned into a `401`, so a client keeps its token and retries. The consent screen of such an app lists Clerk's own scopes (such as `user:org:read`), not this server's scopes. The server grants the app the device and run scopes for your org role. An admin's app also holds `orders:place`. The app is limited to the routes listed below. It may: * list devices, read one, take a screenshot or UI snapshot, see who is driving one, and take a pay as you go device; * acquire, renew and release a lease, act on a device (tap, swipe, type, keys, open or install an app) and wake it; * read the org's leases, and read one receipt by the idempotency key it chose; * start, list, read, pause, resume and cancel runs, and read a run's frames; * create webhooks, and list, read, update, rotate, test and delete the ones it created, and read their deliveries. Webhooks created in the console, with an API key or by another app are invisible to it: they answer `404`. Two limits follow from sharing one org: the cap on webhooks per org counts every webhook, so an app can use up the org's allowance, and an app refused at the cap learns that other webhooks exist. A webhook that was switched off because the person who authorized the app left can be turned back on only by that person; * read the price list and place an order for a prepaid plan. Placing an order only creates a Stripe Checkout page; nothing is bought until you pay on that page yourself. Only an org admin's app can place one, as in the console. Pay as you go answers `403` `permission_denied`: start it in the console; * call `/mcp`, where it sees the device and run tools. Everything else answers `403` with `permission_denied` and a message naming where to do it instead ("This app may use devices, runs, webhooks and orders only; manage API keys in the PhoneUse console."). That covers API keys, team management, the copilot, reading, cancelling or returning orders, billing and the billing portal, usage, onboarding status, notifications, the org's receipt feed, renaming a device and live video sessions. An app is never staff on the operator surface. Within the device surface your org role applies exactly as it does in the console. Authorize only apps you would let drive your devices. When you leave an org, the webhooks apps created on your behalf there are switched off (this needs the deployment's identity webhook to receive `organizationMembership.deleted`). Clerk sends no event when you revoke an app's access or an app is deleted, so revoking an app does not by itself stop its webhooks: delete them in the console. A deployment can name OAuth clients that are its own (`PHONEBASE_FIRST_PARTY_OAUTH_CLIENTS`, each tied to the issuer that registered it). Their tokens are not apps and get the console's surface; the role is still looked up the same way. The console's own session is not an app: its token carries `azp`, and it keeps everything below. Which kind a token is comes from the verified token itself (`client_id` present and no `azp`), never from anything the app sends. A console session gets the device and run scopes, whichever org role it holds. An admin's session also holds `orders:place`. A session can list devices, read one, read the org's leases, receipts, usage and run history, and it can also acquire a lease, tap, swipe, type and start a run. The ordering scope is admin-only; route level role checks also distinguish admins from members. For a period ending on 2026-09-11 an OAuth principal got `devices:read` alone and could drive nothing. That is no longer true. If you built around the narrower grant, nothing you were doing has broken, but a session can now do more than it could. Acting from a browser session is bounded by the session itself. A key is the credential that outlives one. Minting, rotating and renewing a key need a signed-in session, and they do not ask you to verify your identity again. Managing keys is not gated on a scope, and it is no longer gated on **org role** either: either role creates, rotates and revokes keys. What gates it is the **principal kind** (only an OAuth session, never an API key) and, on an existing key, **who minted it**: a member manages the keys they created, an admin manages any of them. ## API keys A key is a single bearer string with a fixed shape: a `pbk_` prefix, a key id, and a secret. New keys start with `pbk_` today. The API also accepts keys that start with `puk_`, and so does the current CLI, `@phoneuse/cli` [0.6.0](https://www.npmjs.com/package/@phoneuse/cli/v/0.6.0). The older CLI [0.4.1](https://www.npmjs.com/package/@phoneuse/cli/v/0.4.1) accepts only `pbk_`. ```bash theme={null} export PHONEUSE_API_KEY="pbk__" curl -sS https://mcp.phoneuse.com/mcp \ -H "Authorization: Bearer $PHONEUSE_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` What matters about them: * **Shown once.** The full token appears exactly once, in the creation response. Only a hash of the secret is stored, so no database read can yield a usable token. Lose it and you issue a new one. * **Scoped.** A key carries the scopes it was issued with, and no more. * **Optionally narrowed to devices.** A key can be restricted to a subset of the org's devices. The subset narrows visibility and addressing together, so a device outside it is not merely refused, it is not found. * **Revocable immediately, on the bearer channel.** Verification runs against the store on every request, and the transport is stateless, so a revoked or expired key is refused from its next request onwards. Revoking does not recall what the key already started. An agent run it started keeps its `vrxBaseUrl`, which is a credential of its own and is not checked against the key, until the run ends: cancel it with `POST /v1/runs/{runId}/cancel` or the `cancel_run` tool. A lease the key took stays until it is released or expires. Keys are managed over `/v1/api-keys`, and that surface requires an **OAuth session**: either org role, but never an API key. That closes the obvious self escalation path, and a second rule closes the other one: the scopes a mint requests have to be a subset of the scopes the calling session already holds, so nobody grants themselves authority they do not have. Each row records who minted it, and that is what rotate, renew and revoke check: a member acts on their own keys, an admin on any key in the org. ## Getting a key **Mint one yourself**, from the `/keys` screen in the console. It is the same `/v1/api-keys` surface described above (create, rename, renew, narrow, rotate, revoke), driven by any **signed in member** of your org, admin or not. Pick the scopes you need, say whether the key should be narrowed to specific devices, and the `pbk_` token is shown to you once. You mint keys yourself rather than requesting one, and a key you already hold keeps working unchanged. Rotation, renewal and revocation are on the same screen. A rotated key keeps working through a short grace window (24 hours by default) while you swap in the new token, and a revoked key is refused from the next request onwards. If a request fails with `expired_key` or `revoked_key`, the error carries a hint that points back to this page: rotation or a fresh key is the way back, because an expired key is never resurrected in place. See [The console](/getting-started/console) for the screen, and for why the key you just minted is refused if you send it from a browser. Either way the red line holds: issuance is never something an API key can do. Operator-side issuance runs as a privileged process against the credential store directly, and it does not pass through this HTTP surface, so there is no issuance endpoint an API key could reach, and no configuration in which a key mints keys. ## Scopes There are eight. The device and run scopes partition the MCP tool surface; the ordering scope applies to the REST checkout route; `apps:read` reads the apps on a phone. The customer app library is retired, so no route uses `apps:write` or `apps:delete` today. Apps are installed from the console's Apps page. | Scope | What it allows | Who can hold it | | - | - | - | | `devices:read` | Enumerating devices, observing a screen, reading a recorded outcome | Console session of either role, API key, authorized app | | `devices:act` | Gestures and input on a leased device | Console session of either role, API key, authorized app | | `devices:lease` | Taking and returning exclusive use of a device | Console session of either role, API key, authorized app | | `runs:start` | Handing a device to an autonomous run, and watching or ending it | Console session of either role, API key | | `orders:place` | Starting a prepaid Checkout order over REST (`POST /v1/checkout-sessions`) | Admin only: an admin's session, or an API key an admin minted or approved. A member's session and a member's keys cannot hold it | | `apps:read` | Reading the apps installed on a phone, and earlier install requests | Console session of either role, and keys minted from one | | `apps:write` | Not used by any route today (the customer app library is retired) | Console session of either role, and keys minted from one | | `apps:delete` | Not used by any route today (the customer app library is retired) | Admin only: an admin's session, or a key an admin minted | A key never carries more than the session that minted it. The copilot has no scope of its own: its routes are person-only, so an API key cannot reach them. Which tool needs which scope is published per tool in the [tool reference](/mcp/reference). `runs:start` is not a way around `devices:act`. Starting a run hands back a credential that drives the device, so a key holding `devices:lease` and `runs:start` but **not** `devices:act` could start a run and then act as its own worker, exercising power its scope set never granted. The run tools therefore require `runs:start` **and** `devices:act`, and the same rule is applied on the REST run surface so the two cannot disagree. ## Your scopes decide which tools exist This is the part that surprises people. Scopes are enforced when tools are **registered**, not when they are called. A tool your credential cannot use is never registered on the server built for your request. So: * `listTools` shows your true surface, not a menu with locked items. * Calling a tool that exists but needs a scope your key lacks returns an error that names the scope, for example "This key needs devices:lease to call acquire_device". The tool still does not run. A name that is not a tool is a protocol level method not found. * The rule lives in exactly one place, so nothing re checks it later and nothing can drift. If a tool you expected is missing, look at your credential's scopes before you look for a bug. ## When authentication fails Authentication fails closed, always. * An unauthenticated or invalid request gets `401`, with a `WWW-Authenticate: Bearer` challenge pointing at the resource metadata so a client can discover where to authenticate, and a structured reason in the body. * An authenticated caller lacking a permission gets `permission_denied`. * If the authentication infrastructure itself is unavailable, the answer is `503`. It is never a pass. An outage refuses requests rather than letting them through. The set of failure reasons is closed, and two distinctions in it are deliberate. An unknown key id and a wrong secret produce the **same** reason. There is no oracle for enumerating which key ids exist, and a miss still performs the same work a hit does so the two do not differ in timing. A **revoked** or **expired** key is reported distinctly. Whoever holds that key owned it, and telling them why it stopped working costs nothing and saves an afternoon. ## Local development Local mode has one org and one operator, and folds into the same pipeline rather than bypassing it. * Set `PHONEBASE_DEV_TOKEN`, and the endpoint requires that exact bearer value. * Leave it unset, and requests resolve to the local org unauthenticated, which is tolerable only because local mode refuses to bind anywhere but loopback. Either way the caller gets every scope, and the shape of the resulting context is identical to a hosted one. > [!WARNING] > > The development branch exists only when no hosted channel is configured. That > is structural, not a convention: a development token sitting next to real > credentials must never become a master key that short circuits them. # Errors Source: https://docs.phoneuse.com/mcp/errors The error envelope a failed tool call carries, and every code it can name. A failed tool call comes back with `isError` set and the error envelope in the result's TEXT block, as JSON. It is deliberately not in `structuredContent`: a client validates any `structuredContent` it sees against the tool's output schema with no exemption for errors, so an envelope there would hard fail every standard client. Branch on `isError`, then parse the text block. **Two things arrive with `isError` set, and only one of them is this envelope.** A call that never reached the tool, because its arguments did not match the published `inputSchema`, is refused by the protocol layer, and its text block is a SENTENCE rather than JSON: ```text theme={null} MCP error -32602: Input validation error: Invalid arguments for tool tap: Number must be less than or equal to 1000 at x ``` So do not parse the text block unconditionally. Try JSON first and treat a parse failure as a malformed request on your side: there is no `code` to branch on, because nothing was attempted and no error in the table below occurred. This is the same refusal that catches a misspelled parameter name, and it is the most common one a new integration meets. On the REST surface the equivalent refusal DOES carry a code (`invalid_argument`, HTTP 400), so a client written against both surfaces cannot share one branch here. ## The envelope | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `name` | string | yes | - | - | | `code` | enum | yes | one of `backend_resolution_failed`, `backend_not_implemented`, `device_unavailable`, `device_disconnected`, `lease_mismatch`, `lease_required`, `capability_unsupported`, `invalid_argument`, `backend_command_failed`, `idempotency_conflict`, `action_outcome_unknown`, `stale_frame`, `internal_error`, `unauthorized`, `permission_denied`, `run_not_found`, `frame_not_found`, `device_busy` | - | | `message` | string | yes | - | - | | `retryable` | boolean | yes | - | - | The envelope also carries whatever fields the specific error adds, such as `deviceId`, `reason` or `capability`. Read the ones you branch on and ignore the rest. `retryable` means re-issuing the SAME call unchanged is meaningful, not that you should loop. It is a property of the occurrence, not of the code: the same code can be retryable once and not the next time, so read the field rather than assuming from the code. ## Codes The `code` field is a closed set of 44 values across MCP tools and REST. Adding one is additive; changing or removing one is a breaking change. A tool call can only answer the 18 marked "MCP tools and REST"; the rest arrive only in the REST envelope. | Code | Where | When you get it | | - | - | - | | `backend_resolution_failed` | MCP tools and REST | The device's row does not name a valid backend. Correct that row: a backend is resolved per device and cannot be set anywhere else. | | `backend_not_implemented` | MCP tools and REST | The device names a backend kind that has no adapter behind it yet. The row itself is valid; nothing can drive it today. | | `device_unavailable` | MCP tools and REST | The device cannot be used right now. The `reason` field says which: not found, offline, unauthorized, already leased, or failed its authenticity probe. | | `device_disconnected` | MCP tools and REST | The device dropped off its transport while the call was running. | | `lease_mismatch` | MCP tools and REST | The lease id does not match the device's current lease. | | `lease_required` | MCP tools and REST | An action or observe call carried no lease. Acquire the device first, then pass its `leaseId`. | | `capability_unsupported` | MCP tools and REST | This device's backend cannot do this at all. Check its capabilities before calling. | | `invalid_argument` | MCP tools and REST | One of your arguments failed validation, so the call was refused before it reached the device. | | `backend_command_failed` | MCP tools and REST | The backend's own command transport failed or returned something unusable. The message names the command and stops there: whatever the transport reported is kept on our side, so do not expect to parse a device log out of this response. | | `idempotency_conflict` | MCP tools and REST | Another action with the same `idempotencyKey` on this device is still in flight. Wait for its outcome; a different intent needs a new key. | | `action_outcome_unknown` | MCP tools and REST | The action was dispatched but its outcome never came back, so the device may or may not have applied it. Re-observe before acting again, and use a NEW `idempotencyKey`. | | `stale_frame` | MCP tools and REST | The action named an `observedFrame` that no longer describes the screen, so it was refused before anything physical happened. Take a new screenshot and decide again. | | `internal_error` | MCP tools and REST | An unexpected failure. Reported by message only, with no internal detail. | | `unauthorized` | MCP tools and REST | The request credentials are missing or invalid. | | `permission_denied` | MCP tools and REST | The caller is authenticated but lacks the permission this call needs. | | `run_not_found` | MCP tools and REST | No run under this id that your org can see. A run owned by another org answers the same way. | | `frame_not_found` | MCP tools and REST | No frame under this id that you may read: it may belong to another organization, may never have finished being stored, may have passed its retention TTL, or may already have been deleted. These are deliberately indistinguishable. | | `device_busy` | MCP tools and REST | Nothing was sent. Either too many actions are already waiting on this device, or an earlier action on it has not finished or is still being confirmed (for example an app install). Actions on one device run one at a time in the order they arrived, a bounded number may wait, and this one was refused rather than queued; nothing already waiting was dropped. Retry after `retryAfterMs` (when present) with a new `idempotencyKey`: the refusal may already have recorded this one as failed, and a same-key retry would replay that. | | `admission_unavailable` | REST | HTTP 503 on the provisioning and billing routes when the provisioning store cannot be read right now. Retry after `Retry-After`. | | `checkout_unavailable` | REST | HTTP 503 on the provisioning and billing routes when this deployment has no payment provider configured, the provider did not answer, the billing portal is not set up, or nothing is configured for what you asked about (a price). Nothing was changed. Under an `Idempotency-Key`, a checkout the payment provider refused outright answers HTTP 409 with `retryable: true` instead: no session was created and that order is closed, so send the purchase again under a new key. A 503 there means the outcome is not known yet; retry with the same key. | | `checkout_customer_balance` | REST | HTTP 503 from `POST /v1/checkout-sessions` when your organization's billing account holds a credit or balance that blocks checkout, or its balance could not be verified. No payable session was opened. Retrying does not help; contact support and we will clear it. | | `checkout_in_progress` | REST | HTTP 409 from `POST /v1/checkout-sessions` when another checkout for your organization is open and could not be closed, usually a second tab or a second admin. Finish or abandon that one first. | | `quote_changed` | REST | HTTP 409 from `POST /v1/checkout-sessions` when the selected model's reviewed quote no longer matches its current server-side Price. Refresh the catalog, review the new price, and submit its quoteId. No order or payable session was created. | | `payment_in_progress` | REST | HTTP 409 from `POST /v1/checkout-sessions` when the previous checkout was already paid and that payment is still being confirmed, so it cannot be replaced. Wait for the order to appear instead of paying again. | | `out_of_stock` | REST | HTTP 409 from `POST /v1/checkout-sessions` when this deployment refuses sales it cannot ship today, or when the model or region you chose has sold out. Nothing was charged. | | `wrong_state` | REST | HTTP 409 from every attempt to return or cancel an order online: devices cannot be returned and orders cannot be cancelled online, and the message gives the support address. The body's `state` names where the order is. | | `instance_not_served` | REST | HTTP 403 from `POST /v1/checkout-sessions` when your organization signs in through an instance whose purchases this deployment does not handle. Nothing you send differently will change it; contact support. | | `reverification_required` | REST | HTTP 403 from `POST /v1/checkout-sessions`, where the deployment requires it, when the action needs you to have verified your identity recently. Creating, rotating and renewing API keys never ask. Verify again and repeat the same call; this is the one retryable 403. Carries `maxAgeMinutes`. | | `not_found` | REST | HTTP 404 on an addressed REST route when nothing at that id is yours to act on. Unknown, another organization's and already gone are one answer, so the code says nothing about whether the id exists. | | `receipt_not_found` | REST | HTTP 404 from the single-receipt read when no receipt under that idempotency key belongs to your organization. | | `rate_limited` | REST | HTTP 429 when your credential is over its per-minute budget. Wait for `Retry-After` seconds; the `RateLimit-*` headers show the budget. | | `payload_too_large` | REST | HTTP 413 when the request body is over the size limit. The message names the limit in bytes. Answered the same way on every surface. | | `origin_not_allowed` | REST | HTTP 403 to a browser preflight from a web origin that is not on this deployment's allow-list. Call the API from your server, or from the console. | | `api_key_from_browser_origin` | REST | HTTP 403 when an API key (`pbk_...` or `puk_...`) arrives from a web page, which is detected by the `Origin` header. Keys are for servers; a key used in a browser is exposed to everyone who opens the page. | | `key_predates_instance_attribution` | REST | HTTP 403 for an API key minted before its organization's sign-in instance was recorded. Rotate the key; the new one works. | | `org_not_served_by_instance` | REST | HTTP 403 when your organization belongs to a different sign-in instance from the one that issued your credential. Sign in through the console you normally use, or mint a key there. | | `tenant_binding_unavailable` | REST | HTTP 503 when this deployment cannot check which organization your credential belongs to right now. Retry after `Retry-After` (30 seconds). | | `tenant_binding_unsettled` | REST | HTTP 503 on the first request for a new organization, while its binding is still being recorded. Retry after `Retry-After` (1 second). | | `fleet_at_capacity` | REST | HTTP 409 from taking a device out of the shared pool when your organization already holds its limit. The body carries `holding`, `limit` and `retryAfterMs`. | | `forbidden` | REST | HTTP 403 from taking a device out of the shared pool when your organization has no pay-as-you-go access to it. | | `service_unavailable` | REST | HTTP 503 when this deployment does not serve the surface at all (copilot, direct commands). Waiting does not help, so there is no `Retry-After`. | | `invalid_signature` | Stripe webhook | HTTP 400 from `POST /webhooks/stripe` when the payment provider's signature does not verify. Answered to the provider, never to a customer. | | `invalid_event` | Stripe webhook | HTTP 400 from `POST /webhooks/stripe` when a correctly signed event cannot be read. Answered to the provider, never to a customer. | | `not_settled` | Stripe webhook | HTTP 503 from `POST /webhooks/stripe` when an event cannot be applied yet, so the provider delivers it again later. Answered to the provider, never to a customer. | ## The other two surfaces The closed set above covers MCP tool calls and the REST envelope. This service answers in three envelopes, not one, and a client that branches on the table above everywhere will break on the other two. Each surface always answers in its own envelope. | Surface | Envelope | Codes | | - | - | - | | `POST /mcp` tool calls | `{ name, code, message, retryable }` in the result's text block | the 18 marked "MCP tools and REST" above | | REST, `/v1/*` | `{ error: { code, ... } }`, HTTP status carries the outcome | all 44 above, plus `reason` on a `401` | | Device surface, `/vrx/{runToken}/v1/*` | `{ ok: false, error: { code, message } }` | SCREAMING_SNAKE, the closed set below | The REST envelope carries `retryable` when the refusal knows the answer: it is a property of the occurrence rather than of the code, so read the field instead of inferring it from the code. The HTTP status still carries the outcome, and a `401` additionally carries a `reason` naming which credential problem it was. ### Device surface codes The device surface speaks the `visualremote/1` dialect, so it has its OWN closed set of 10 codes. The two sets are deliberately separate: the dialect stops at the device channel rather than spreading into the rest of this API. Branch on these when you are writing a worker. | Code | | - | | `DEVICE_NOT_FOUND` | | `INVALID_ACTION` | | `FRAME_VIEWPORT_MISMATCH` | | `COORDINATE_OUT_OF_REACH` | | `ACTION_UNAVAILABLE` | | `FENCING_TOKEN_STALE` | | `STALE_FRAME` | | `HARDWARE_OFFLINE` | | `FRAME_UNAVAILABLE` | | `ACTION_OUTCOME_UNKNOWN` | One of them is worth calling out. `DEVICE_NOT_FOUND` covers an unknown, expired, terminal or wrong-device run token, all answering identically so that a token holder cannot probe which it was. It is also what you get if you point an ORG API KEY at this surface, and in that case nothing is missing: this is the worker channel, its credential is the run token in the url, and no `Authorization` header is read at all. Drive devices yourself over `/mcp` instead. # MCP surface Source: https://docs.phoneuse.com/mcp/overview The tool surface an agent drives, and the contract that keeps it stable. PhoneUse is an MCP server. The unit of its public surface is a tool, not an endpoint, and driving a device means calling tools rather than posting to paths. This page describes the shape of that surface and the rules it evolves under. For the tools themselves, read the generated references: > [card] [Tool reference](/mcp/reference) > > Every tool, its input and output schema, its annotations, and the scope it > needs. > [card] [Error reference](/mcp/errors) > > The error envelope and every code that can reach you. Both are generated from the source the server actually registers, so they cannot describe a tool that does not exist or omit one that does. ## How the surface is organised Tools fall into five groups, and the groups are also the permission model. | Group | What it covers | | - | - | | Read | Enumerating devices, observing a screen, and looking up a recorded outcome | | Act | Gestures and input: tapping, swiping, typing, key presses, opening an app | | Lease | Taking and returning exclusive use of a device | | Runs | Handing a device to an autonomous run, and watching or ending it | | Apps | Reading the apps on a phone, refreshing that list, and reading an earlier install request | The first four groups map to `devices:read`, `devices:act`, `devices:lease` and `runs:start`; the run tools also need `devices:act`. The app tools need `apps:read`, and the ones that read a phone also need `devices:read`. Every tool declares the scopes it needs, so a new tool that forgot to declare them would be invisible to every credential. The [tool reference](/mcp/reference) lists the scopes for each tool. See [Authentication](/mcp/auth). ## What is not on this surface Billing, purchasing, returning an order, revoking a key and leaving an organisation are **not** on the MCP tool surface. The [REST API](/api/index) lets an API key with `orders:place` start a prepaid Checkout order; an admin must issue or approve that key. Checkout still requires a person to complete payment. Billing, returning an order, revoking a key and leaving an organisation remain outside the MCP tool surface. ## Every result is typed A successful call returns `structuredContent`, validated against the `outputSchema` that tool publishes. The same value is also written into a text block, which is what earlier consumers read. That duplication is transitional. `structuredContent` is the machine readable source of truth; the text block's promise to parse as JSON is on a deprecation track and will retire once the typed shape has been stable for at least one release cycle. Read `structuredContent` in new code. Errors are the exception, and deliberately so. An error result carries its envelope in the text block and **never** in `structuredContent`, because a standard MCP client validates any `structuredContent` it sees against the tool's output schema with no exemption for errors. See [Reading a trace](/getting-started/trace) for how to consume one. ## Every tool is annotated Each tool publishes all four MCP annotation hints explicitly, because an omitted hint is indistinguishable from an unconsidered one, and because the protocol's defaults are the wrong ones for a closed device surface. * `openWorldHint` is `false` everywhere. Tools reach the fleet you configured and nothing else. * `destructiveHint` marks the tools that can destroy state you did not create: the two run tools hand the device to an autonomous loop. A tap, a swipe, a hold, typing and a key press are not marked, because they do what a finger does and a client that prompts on the hint would prompt on every one of them. The flag that keeps a person in the loop is `_meta.requiresUserInteraction`, which is ours and which no "do not ask again" turns off. * `idempotentHint` on action tools reflects the idempotency key contract: a retry that reuses its key replays the recorded outcome rather than executing again. * `readOnlyHint` marks the tools that only observe. The exact values per tool are in the [tool reference](/mcp/reference). ## Inputs are strict Every tool's input schema rejects unknown keys rather than stripping them. A misspelled `leaseid`, or a parameter your model invented, fails loudly instead of travelling on to a real device with a silently missing argument. `leaseId` is optional on every action and observation tool. If you provide it, it must match the lease your organization currently holds; a stale id returns `lease_mismatch` without acting. Omit it to use the current lease, or to take a free device when your key has `devices:lease`. `release_device` still requires the id. When your organization does not hold the device and the tool will not take it for you, the refusal is `lease_required`. ## The surface is a frozen contract The tool surface is frozen from the launch on **2026-09-25** onward. The tool names and fields published on that date are the baseline, and from then on the surface evolves under a published program rather than at will. * **Additive changes** are allowed at any time: new tools, new optional parameters, new output fields, new error codes. Existing callers are unaffected. * **A change of meaning without a change of shape** is declared rather than versioned: the tool description carries an `@since` note and the [changelog](/changelog) records what changed. * **Renames and removals** are breaking. There is no `tap_v2` family and no parallel endpoint. A breaking change goes through the deprecation program in [Versioning and compatibility](/api/versioning#after-launch-additive-only), and it is announced in the [changelog](/changelog) before anything moves. Adding a tool is a release cycle event, and a release cycle is a version bump on the server info the client reads at connect time. That is how a client can tell one published surface from another instead of counting tools. > [!NOTE] > > Do not hard code a tool count. The count has changed more than once, and any > number written into prose ages badly. Ask the server: `listTools` reflects > your credential's true surface at that moment. ## The surface is stateless The HTTP transport builds a fresh server per request. There is no session affinity, and a lease is not session state: it travels as an explicit parameter on every call. That is what lets any process holding a `leaseId` continue a session, and what makes `GET` and `DELETE` on the endpoint meaningless. Some capabilities do depend on a live bidirectional connection. Progress notifications and human takeover both need one, and the stateless HTTP path cannot carry either. See [Transports](/mcp/transports) and [Progress and takeover](/mcp/progress-and-takeover). ## Where to go next > [card] [Transports](/mcp/transports) > > stdio and hosted HTTP, and what actually differs. > [card] [Authentication](/mcp/auth) > > Two credential channels and role-based scopes in one auth context. > [card] [First session](/getting-started/first-session) > > The four beats of a session, one call at a time. > [card] [Agent tier](/agent/overview) > > Hand a goal to a worker instead of driving each step. # Progress and takeover Source: https://docs.phoneuse.com/mcp/progress-and-takeover Long running actions, and the moments a person has to step in. Two facts about driving a real phone shape this page. An action takes real time, because the device has to apply it and confirm it. And some screens cannot be solved by an agent at all, because they are asking for a person. PhoneUse handles both, and how well it handles them depends on your transport. ## Progress on a long action An action call blocks until the **device** commits it. That is usually quick, but a caller waiting on the response is waiting on the device, not on the server. If your client sends a progress token with the request, the server reports the handoff as soon as the action is dispatched to the device: ```text theme={null} dispatched to cloud-phone-01; awaiting device commit ``` That notification says the request reached the device and the device is applying it. It does not say the action succeeded. The success answer is the result itself, and it arrives when the device confirms. Two conditions have to hold for any of this to reach you. 1. **You asked.** The protocol only sends progress against a token the request carried. A request with no progress token gets no notification. 2. **Your transport can carry it.** A mid request notification needs a live bidirectional session. The hosted HTTP endpoint is stateless, and `phoneuse mcp --stdio` relays to it, so neither carries one today. A transport that cannot deliver the notification does not fail your action over it. Progress is a transport capability, never a promise the tool surface makes. ## When progress is not available Do not build a loop that depends on notifications. Build it on the recorded outcome instead, which works everywhere: 1. Send the action with an `idempotencyKey` you generated. 2. If the response arrives, you are done. Read `status` and `committedAt`. 3. If it does not, call `get_receipt` with the same key. * `found: false` means the action never began. Retry with the **same** key. * A committed receipt means it happened. Do not retry. * A failed receipt carrying `outcome_unknown` means the transport to the device was lost after dispatch, so a person has to reconcile it. This path survives a lost response, a client restart, and a transport with no notification channel at all. See [Reading a trace](/getting-started/trace). ## When a person has to step in Some screens are designed to stop automation, and correctly so: a sign in, a one time code, a challenge. An agent should not be trying to defeat them. The mechanism is MCP elicitation. The server asks **your client's** operator to go and deal with the screen, and to confirm when they are done. The request carries the device id, a short machine stable reason, and an instruction of what to do. The person acts on the same device under the same lease; nothing is handed over and nothing is taken away. ```json theme={null} { "message": "[cloud-phone-01] Complete the sign in on the device (reason: login_required)", "requestedSchema": { "type": "object", "properties": { "done": { "type": "boolean", "title": "Done" } }, "required": ["done"] } } ``` > [!WARNING] > > No secret ever travels this channel. The person acts **on the device**, not > in a chat window. PhoneUse asks a human to go and type a password into the > phone in front of them; it never asks anyone to send it one. The wait is generous, because a person unlocking a device and solving a challenge takes minutes rather than the seconds a normal remote call is given. It is still bounded, because an elicitation that never resolves would hold a lease open behind it. Every non confirmation fails closed: | What happened | Outcome | | - | - | | The operator confirmed they finished | `completed` | | The client cannot do elicitation at all | `unavailable` | | Declined, cancelled, timed out, or the transport failed | `declined` | Only an explicit confirmation counts as completed. Like progress, elicitation needs a live bidirectional session, so the stateless HTTP path (and the CLI relay in front of it) cannot carry it: the caller sees a terminal outcome and re drives after the person is finished. ## A person's turn inside an autonomous run The agent tier has its own form of the same idea, and it is stronger. A worker that hits a screen needing a person reports the run as `needs_user_control`. The run **parks**: it does not end, and while it is parked the worker's channel is shut on every side. A tap or a swipe is refused; a screenshot is refused before the device is ever asked for one; and a second run cannot be started on the same device to observe it around the first. So what the person does while the agent waits is not served to the worker. The only way out is a person, through `resume_run` or the equivalent REST call. A worker cannot lift its own request, not by asking to resume and not by reporting the run finished out from under the person; a worker report on a parked run is refused until someone resumes it. Two exceptions: * **A run still stops at its deadline**, so a wait that runs long can expire. Give the run enough wall-clock when you start it. * **A run parked by an API restart ends by itself.** A run PhoneUse was driving when the API restarted ends `canceled` once the earlier of its saved time and 10 minutes has passed, and frees the phone, unless an action from before the restart has an unclear outcome: that action still holds the phone. One rule is stricter, for runs PhoneUse drives. On such a run, a goal that needs a person from the start (paying, buying, erasing, changing a password and the like) is parked before anything drives it, and it ends as `succeeded` only when a person signed in to the console presses **Done**. A resume from an API key, the CLI, a third-party app or Copilot leaves it waiting. To stop it instead, cancel it with `cancel_run`, `POST /v1/runs/{runId}/cancel` or `phoneuse runs cancel `; it then ends `canceled`. See [Runs](/agent/runs). A person does not have to wait to be asked. They may act on the device while the run is driving, and the run is informed through `others` on its next result rather than stopped. See [Runs](/agent/runs#driving-alongside-a-run) for how the two hands share one phone, and for the full lifecycle. # Tool reference Source: https://docs.phoneuse.com/mcp/reference Every tool on the MCP surface, with its scope, annotations and fields. The surface is 27 tools across 8 scopes. 10 of them are the frozen baseline: they were there from the first release and only leave through a deprecation programme. The rest are additions, marked with the version that introduced them. Additions never change an existing tool, so a client written against the baseline keeps working. Every tool rejects unknown parameters instead of dropping them, so a misspelled field fails loudly rather than acting without it. **Billing, purchasing, returning an order, revoking a key and leaving an organisation are not here, and there is no scope for them.** They are on the REST API, and the ones that spend or unwind money also require a signed-in administrator rather than an API key. A tool you cannot find in the table below is not missing from your credential's scopes; it does not exist on this surface. ## Surface at a glance | Tool | Shown as | Scope | Added in | `readOnlyHint` | `destructiveHint` | `idempotentHint` | `openWorldHint` | | - | - | - | - | - | - | - | - | | [`list_app_device_capabilities`](#list_app_device_capabilities) | list app device capabilities | `apps:read + devices:read` | 0.8.0 | true | false | true | false | | [`get_app_inventory`](#get_app_inventory) | get app inventory | `apps:read + devices:read` | 0.8.0 | true | false | true | false | | [`refresh_app_inventory`](#refresh_app_inventory) | refresh app inventory | `apps:read + devices:read` | 0.8.0 | false | false | true | false | | [`get_app_inventory_refresh`](#get_app_inventory_refresh) | get app inventory refresh | `apps:read + devices:read` | 0.8.0 | true | false | true | false | | [`list_app_inventory_refresh_results`](#list_app_inventory_refresh_results) | list app inventory refresh results | `apps:read + devices:read` | 0.8.0 | true | false | true | false | | [`get_app_request`](#get_app_request) | get app request | `apps:read` | 0.8.0 | true | false | true | false | | [`list_devices`](#list_devices) | List your phones | `devices:read` | baseline | true | false | true | false | | [`acquire_device`](#acquire_device) | Take a phone | `devices:lease` | baseline | false | false | false | false | | [`renew_lease`](#renew_lease) | Keep the phone longer | `devices:lease` | 0.4.0 | false | false | false | false | | [`release_device`](#release_device) | Give the phone back | `devices:lease` | baseline | false | false | true | false | | [`screenshot`](#screenshot) | See the screen | `devices:read` | baseline | true | false | true | false | | [`ui_snapshot`](#ui_snapshot) | Read the screen's elements | `devices:read` | baseline | true | false | true | false | | [`tap`](#tap) | Tap | `devices:act` | baseline | false | false | true | false | | [`swipe`](#swipe) | Swipe | `devices:act` | baseline | false | false | true | false | | [`type_text`](#type_text) | Type | `devices:act` | baseline | false | false | true | false | | [`press_key`](#press_key) | Press a key | `devices:act` | baseline | false | false | true | false | | [`open_app`](#open_app) | Open an app | `devices:act` | baseline | false | false | true | false | | [`long_press`](#long_press) | Press and hold | `devices:act` | 0.2.0 | false | false | true | false | | [`wake`](#wake) | Wake the screen | `devices:act` | 0.6.0 | false | false | true | false | | [`get_device`](#get_device) | Look at one phone | `devices:read` | 0.2.0 | true | false | true | false | | [`get_receipt`](#get_receipt) | Look up what an action did | `devices:read` | 0.2.0 | true | false | true | false | | [`start_run`](#start_run) | Start a run | `runs:start` | 0.7.0 | false | true | false | false | | [`get_run`](#get_run) | Watch a run | `runs:start` | 0.7.0 | true | false | true | false | | [`list_runs`](#list_runs) | List your runs | `runs:start` | 0.7.0 | true | false | true | false | | [`cancel_run`](#cancel_run) | Stop a run | `runs:start` | 0.7.0 | false | false | true | false | | [`resume_run`](#resume_run) | Let a run carry on | `runs:start` | 0.7.0 | false | true | true | false | | [`pause_run`](#pause_run) | Hold a run | `runs:start` | 0.7.0 | false | false | false | false | ## Scopes Your API key carries scopes, and a tool outside them is never registered on your session. That means `tools/list` shows exactly what you can call. Calling a tool that exists but needs a scope your key lacks returns an error that names the scope, such as `permission_denied` with "This key needs devices:lease to call acquire_device". A name that is not a tool is a protocol-level method not found. | Scope | Tools | | - | - | | `devices:read` | `list_app_device_capabilities`, `get_app_inventory`, `refresh_app_inventory`, `get_app_inventory_refresh`, `list_app_inventory_refresh_results`, `list_devices`, `screenshot`, `ui_snapshot`, `get_device`, `get_receipt` | | `devices:act` | `tap`, `swipe`, `type_text`, `press_key`, `open_app`, `long_press`, `wake` | | `devices:lease` | `acquire_device`, `renew_lease`, `release_device` | | `runs:start` | `start_run`, `get_run`, `list_runs`, `cancel_run`, `resume_run`, `pause_run` | | `orders:place` | | | `apps:read` | `list_app_device_capabilities`, `get_app_inventory`, `refresh_app_inventory`, `get_app_inventory_refresh`, `list_app_inventory_refresh_results`, `get_app_request` | | `apps:write` | | | `apps:delete` | | `runs:start` also needs `devices:act`. Handing a device to a run is permission to let a loop act for you, not permission to act without saying so, so a key without `devices:act` gets no run tools at all. ## What the annotations mean Every hint is set explicitly on every tool. Read them literally: * `title` is the name a client shows a person. The tool name is the protocol handle; this is the product's own word for it, and the table above prints both. * `destructiveHint` marks the tools that can destroy state you did not create: the run tools hand the device to an autonomous loop. A tap, a swipe, a hold, typing and a key press are NOT marked, because they do what a finger does and a client that prompts on the hint would prompt on every one of them. What keeps a person in the loop is `_meta.requiresUserInteraction`, which no "do not ask again" turns off. * `idempotentHint` on an action tool reflects the `idempotencyKey` contract: a retry that reuses the key replays the recorded outcome instead of executing twice. * `openWorldHint` is `false` everywhere. Tools act on your own configured fleet, nothing beyond it. ## Tools ### list_app_device_capabilities Apps library list app device capabilities. Uses the same permissions and durable request key as REST. A pending or unconfirmed result is not success; query the original key. Never send APK bytes. These tools do not install apps: to install one, use the Apps page in the Console ([https://console.phoneuse.com/apps](https://console.phoneuse.com/apps)). **Required scope:** `apps:read + devices:read` · **Added in:** 0.8.0 **Annotations:** `title` "list app device capabilities", `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `cursor` | string | no | - | - | | `limit` | integer | no | min 1, max 100 | - | | `q` | string | no | max length 200 | - | | `deviceId` | string | no | pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$` | - | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `items` | object\[] | yes | - | - | | `items[].deviceId` | string | yes | pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$` | - | | `items[].deviceName` | string | yes | - | - | | `items[].platform` | enum | yes | one of `android`, `ios`, `unknown` | - | | `items[].scope` | object or null | yes | - | - | | `items[].inventoryRead` | object | yes | - | Authoritative independent operation support. Registration/read metadata only; unknown never permits writes. | | `items[].install` | object | yes | - | Authoritative independent operation support. Registration/read metadata only; unknown never permits writes. | | `items[].update` | object | yes | - | Authoritative independent operation support. Registration/read metadata only; unknown never permits writes. | | `items[].uninstall` | object | yes | - | Authoritative independent operation support. Registration/read metadata only; unknown never permits writes. | | `items[].updatedAt` | string or null | yes | - | - | | `nextCursor` | string or null | yes | - | - | | `snapshotId` | string | yes | - | - | | `snapshotExpiresAt` | string | yes | - | - | ### get_app_inventory Apps library get app inventory. Uses the same permissions and durable request key as REST. A pending or unconfirmed result is not success; query the original key. Never send APK bytes. These tools do not install apps: to install one, use the Apps page in the Console ([https://console.phoneuse.com/apps](https://console.phoneuse.com/apps)). **Required scope:** `apps:read + devices:read` · **Added in:** 0.8.0 **Annotations:** `title` "get app inventory", `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `cursor` | string | no | - | - | | `limit` | integer | no | min 1, max 100 | - | | `packageName` | string | no | min length 1, max length 255, pattern `^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$` | - | | `deviceId` | string | no | pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$` | - | | `scopeId` | string | no | pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$` | - | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `items` | object\[] | yes | - | - | | `items[].inventoryId` | string | yes | pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$` | - | | `items[].deviceId` | string | yes | pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$` | - | | `items[].scope` | object | yes | - | A stable adapter-verified read/write and actual effect scope. false or absent proof never permits writes. No implicit user 0/current/all. | | `items[].packageName` | string | yes | min length 1, max length 255, pattern `^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$` | - | | `items[].presence` | enum | yes | one of `present`, `absent`, `unknown` | - | | `items[].absenceBasis` | enum or null | yes | - | - | | `items[].app` | object or null | yes | - | - | | `items[].requestedAt` | string | yes | - | - | | `items[].receivedAt` | string | yes | - | - | | `items[].observedAt` | string or null | yes | - | - | | `items[].completeness` | enum | yes | one of `complete`, `partial`, `unknown` | - | | `items[].source` | enum | yes | one of `device_package_manager`, `managed_device_service` | - | | `items[].freshness` | object | yes | - | receivedAt is not observedAt. adapter_guaranteed_live requires documented adapter guarantees and bounded acquisition latency; a fast HTTP response is insufficient. | | `items[].lastRefresh` | object or null | yes | - | - | | `nextCursor` | string or null | yes | - | - | | `snapshotId` | string | yes | - | - | | `snapshotExpiresAt` | string | yes | - | - | ### refresh_app_inventory Apps library refresh app inventory. Uses the same permissions and durable request key as REST. A pending or unconfirmed result is not success; query the original key. Never send APK bytes. These tools do not install apps: to install one, use the Apps page in the Console ([https://console.phoneuse.com/apps](https://console.phoneuse.com/apps)). **Required scope:** `apps:read + devices:read` · **Added in:** 0.8.0 **Annotations:** `title` "refresh app inventory", `readOnlyHint` false, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `requestKey` | string | yes | min length 1, max length 128, pattern `^(?!\.{1,2}$)[A-Za-z0-9._:-]+$` | Caller-generated unique intent key, retained by client before sending. New library restriction, not a change to the legacy visible-ASCII key contract. | | `body` | object | yes | - | Explicit finite scope. Omit packageName to collect the full installed-app inventory. Pure read only: never acquire/renew leases, wake/boot devices or run a substitute app action. Unsupported read-only transport returns a per-target reason. | | `body.packageName` | string | no | min length 1, max length 255, pattern `^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$` | - | | `body.targets` | object\[] | yes | - | - | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `refreshId` | string | yes | pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$` | - | | `state` | enum | yes | one of `processing`, `completed`, `partially_completed`, `not_completed` | - | | `requestedAt` | string | yes | - | - | | `finishedAt` | string or null | yes | - | - | | `targetCount` | integer | yes | min 1 | - | | `completedCount` | integer | yes | min 0 | - | | `notCompletedCount` | integer | yes | min 0 | - | | `nextPollAfterSeconds` | integer | yes | min 1 | - | | `servicePromise` | object | yes | - | Original promisedBy never resets on retry/poll. nextUpdateAt must correspond to a real scheduled update and accountable service; null does not authorize indefinite waiting. | | `servicePromise.promisedBy` | string or null | yes | - | - | | `servicePromise.estimatedCompletionAt` | string or null | yes | - | - | | `servicePromise.nextUpdateAt` | string or null | yes | - | - | | `servicePromise.delayed` | boolean | yes | - | - | ### get_app_inventory_refresh Apps library get app inventory refresh. Uses the same permissions and durable request key as REST. A pending or unconfirmed result is not success; query the original key. Never send APK bytes. These tools do not install apps: to install one, use the Apps page in the Console ([https://console.phoneuse.com/apps](https://console.phoneuse.com/apps)). **Required scope:** `apps:read + devices:read` · **Added in:** 0.8.0 **Annotations:** `title` "get app inventory refresh", `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `refreshId` | string | yes | pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$` | - | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `refreshId` | string | yes | pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$` | - | | `state` | enum | yes | one of `processing`, `completed`, `partially_completed`, `not_completed` | - | | `requestedAt` | string | yes | - | - | | `finishedAt` | string or null | yes | - | - | | `targetCount` | integer | yes | min 1 | - | | `completedCount` | integer | yes | min 0 | - | | `notCompletedCount` | integer | yes | min 0 | - | | `nextPollAfterSeconds` | integer | yes | min 1 | - | | `servicePromise` | object | yes | - | Original promisedBy never resets on retry/poll. nextUpdateAt must correspond to a real scheduled update and accountable service; null does not authorize indefinite waiting. | | `servicePromise.promisedBy` | string or null | yes | - | - | | `servicePromise.estimatedCompletionAt` | string or null | yes | - | - | | `servicePromise.nextUpdateAt` | string or null | yes | - | - | | `servicePromise.delayed` | boolean | yes | - | - | ### list_app_inventory_refresh_results Apps library list app inventory refresh results. Uses the same permissions and durable request key as REST. A pending or unconfirmed result is not success; query the original key. Never send APK bytes. These tools do not install apps: to install one, use the Apps page in the Console ([https://console.phoneuse.com/apps](https://console.phoneuse.com/apps)). **Required scope:** `apps:read + devices:read` · **Added in:** 0.8.0 **Annotations:** `title` "list app inventory refresh results", `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `refreshId` | string | yes | pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$` | - | | `cursor` | string | no | - | - | | `limit` | integer | no | min 1, max 100 | - | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `items` | object\[] | yes | - | - | | `items[].deviceId` | string | yes | pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$` | - | | `items[].scopeId` | string | yes | pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$` | - | | `items[].state` | enum | yes | one of `pending`, `completed`, `not_completed` | - | | `items[].inventoryId` | string or null | yes | - | - | | `items[].reason` | enum or null | yes | - | - | | `items[].completeness` | enum | no | one of `complete`, `partial`, `unknown` | Actual persisted collection completeness; omitted if no successful sample exists. | | `items[].message` | string or null | yes | - | - | | `nextCursor` | string or null | yes | - | - | | `snapshotId` | string | yes | - | - | | `snapshotExpiresAt` | string | yes | - | - | ### get_app_request Apps library get app request. Uses the same permissions and durable request key as REST. A pending or unconfirmed result is not success; query the original key. Never send APK bytes. These tools do not install apps: to install one, use the Apps page in the Console ([https://console.phoneuse.com/apps](https://console.phoneuse.com/apps)). **Required scope:** `apps:read` · **Added in:** 0.8.0 **Annotations:** `title` "get app request", `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `requestKey` | string | yes | min length 1, max length 128, pattern `^(?!\.{1,2}$)[A-Za-z0-9._:-]+$` | Caller-generated unique intent key, retained by client before sending. New library restriction, not a change to the legacy visible-ASCII key contract. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `requestKey` | string | yes | min length 1, max length 128, pattern `^(?!\.{1,2}$)[A-Za-z0-9._:-]+$` | Caller-generated unique intent key, retained by client before sending. New library restriction, not a change to the legacy visible-ASCII key contract. | | `operationId` | string | yes | - | - | | `state` | enum | yes | one of `processing`, `completed`, `not_completed` | - | | `resourceType` | enum or null | yes | - | - | | `resourceId` | string or null | yes | - | - | | `resourcePath` | string or null | yes | - | - | | `originalStatus` | integer or null | yes | - | - | | `createdAt` | string | yes | - | - | | `updatedAt` | string | yes | - | - | | `retainedUntil` | string | yes | - | - | | `error` | object or null | yes | - | - | ### list_devices Enumerate every reachable device with its per-device capabilities. Consult capabilities before calling action/observe tools, backends differ (a cloud phone, for one, has screenshots but no UI tree). **Required scope:** `devices:read` **Annotations:** `title` "List your phones", `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** This tool takes no parameters. **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `devices` | object\[] | yes | - | - | | `devices[].deviceId` | string | yes | - | - | | `devices[].backendKind` | enum | yes | one of `adb_cloud`, `adb_real`, `emulator`, `robot_hand`, `esp32_hid`, `byod_portal` | - | | `devices[].kind` | enum | yes | one of `emulator`, `cloud_phone`, `physical`, `robot` | - | | `devices[].status` | enum | yes | one of `online`, `offline`, `unauthorized`, `unknown` | - | | `devices[].capabilities` | object | yes | discriminated by `fidelityTier`: `"software"`, `"hid"`, `"physical"` | - | | `devices[].metadata` | object | yes | arbitrary keys | - | | `devices[].displayName` | string | no | - | - | | `devices[].info` | object | no | - | - | ### acquire_device Take a device for your organization before acting on it. Optional: any gesture tool takes the device for you when your organization does not hold it. Returns the lease (leaseId + expiry); keep leaseId to give the device back with release_device. A lease expires on its own after 10 minutes unless renewed. **Required scope:** `devices:lease` **Annotations:** `title` "Take a phone", `readOnlyHint` false, `destructiveHint` false, `idempotentHint` false, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `orgId` | string | yes | - | - | | `deviceId` | string | yes | - | - | | `leaseId` | string | yes | - | - | | `fencingToken` | integer | yes | - | - | | `acquiredAt` | string | yes | - | - | | `expiresAt` | string | yes | - | - | ### renew_lease Extend the lease your organization holds on a device, so work longer than one lease can keep its device. leaseId is optional; if supplied it must match the current lease. The lease may be one a colleague or a run took. Slides the expiry to ten minutes from now (it does not add ten minutes to the old expiry), and leaves leaseId, fencingToken and acquiredAt unchanged. Renew before the lease expires: an expired lease cannot be renewed, because by then the device is available to everyone else, and you have to take it again. **Required scope:** `devices:lease` · **Added in:** 0.4.0 **Annotations:** `title` "Keep the phone longer", `readOnlyHint` false, `destructiveHint` false, `idempotentHint` false, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | | `leaseId` | string | no | min length 1 | Optional. Lease id from acquire_device. Leave it out: the action runs under the lease your organization holds on the device, and a gesture takes the device for you when it holds none. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `orgId` | string | yes | - | - | | `deviceId` | string | yes | - | - | | `leaseId` | string | yes | - | Unchanged: the same lease continues, so keep using this id. | | `fencingToken` | integer | yes | - | Unchanged by a renewal: the holder generation is the same. | | `acquiredAt` | string | yes | - | Unchanged: the original acquire, which is what billing integrates from. | | `expiresAt` | string | yes | - | The NEW expiry, ten minutes from the moment the renewal was granted. | ### release_device Give a device back, by the lease id acquire_device returned. This tool requires the id; other actions accept an omitted id but reject a stale one. An id that is not the current one is refused with lease_mismatch. **Required scope:** `devices:lease` **Annotations:** `title` "Give the phone back", `readOnlyHint` false, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | | `leaseId` | string | yes | min length 1 | The lease id acquire_device returned. Required. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `ok` | literal | yes | always `true` | - | | `deviceId` | string | yes | - | - | ### screenshot Capture the device screen. Returns the image plus its pixelSize and, when your organization holds the device, a frameId; aim taps with the 0-1000 grid, and pass frameId as observedFrame on the next action so a stale frame is refused instead of mis-tapped. `others` says what anybody else did on the device since the previous frame. On a device your organization does not hold this is a watch: you get the image and no frame, and nothing is taken or billed. **Required scope:** `devices:read` **Annotations:** `title` "See the screen", `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | | `leaseId` | string | no | min length 1 | Optional. Lease id from acquire_device. Leave it out: the action runs under the lease your organization holds on the device, and a gesture takes the device for you when it holds none. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `format` | enum | yes | one of `png`, `jpeg` | - | | `source` | enum | yes | one of `framebuffer`, `camera` | - | | `pixelSize` | object | yes | - | Raw frame geometry in device/image pixels, informational; aim actions with the 0-1000 grid. | | `pixelSize.width` | integer | yes | - | - | | `pixelSize.height` | integer | yes | - | - | | `frameId` | string | no | - | Pass as observedFrame on the next action to bind it to this frame. Absent when your organization does not hold the device (a watch mints no frame). | | `sequence` | integer | no | - | - | | `capturedAt` | string | no | - | - | | `others` | object | no | - | What everybody else did on this device since you last looked. Present on every action result and every leased screenshot. | | `others.actions` | integer | yes | - | How many actions principals other than you took on this device since your anchor. Pending and committed receipts count; failed ones do not. | | `others.lastAt` | string or null | yes | - | When the newest of them was requested, ISO-8601 on the control-plane clock. Null when actions is 0. | | `others.by` | enum\[] | yes | each: one of `person`, `agent` | Who they were: person (a signed-in person acting directly) and/or agent (an API key, a copilot, or a run). Each at most once, person first. | ### ui_snapshot Structured element tree of the current screen. All bounds inside the tree are already in the 0-1000 grid, coordinates read here can be tapped directly. **Required scope:** `devices:read` **Annotations:** `title` "Read the screen's elements", `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | | `leaseId` | string | no | min length 1 | Optional. Lease id from acquire_device. Leave it out: the action runs under the lease your organization holds on the device, and a gesture takes the device for you when it holds none. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `tree` | string | yes | - | - | | `format` | enum | yes | one of `xml`, `json` | - | | `source` | enum | yes | one of `uiautomator`, `a11y` | - | | `pixelSize` | object | yes | - | Raw frame geometry in device/image pixels, informational; aim actions with the 0-1000 grid. | | `pixelSize.width` | integer | yes | - | - | | `pixelSize.height` | integer | yes | - | - | ### tap Tap at (x, y) in the 0-1000 grid. Returns the ActionOutcome: committed means the device applied it. Every action result also carries `others`, what other principals did on the device since your anchor; a person may drive the same device beside you, and you are informed rather than stopped. **Required scope:** `devices:act` **Annotations:** `title` "Tap", `readOnlyHint` false, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | | `x` | number | yes | min 0, max 1000 | Tap x in the normalized 0-1000 grid (origin top-left, current orientation). | | `y` | number | yes | min 0, max 1000 | Tap y in the normalized 0-1000 grid (origin top-left, current orientation). | | `leaseId` | string | no | min length 1 | Optional. Lease id from acquire_device. Leave it out: the action runs under the lease your organization holds on the device, and a gesture takes the device for you when it holds none. | | `idempotencyKey` | string | no | pattern `^[\x20-\x7e]{1,128}$` | Client-generated request id (1-128 printable ASCII, must not start with "agent:"). Reuse the SAME value when retrying the SAME intended action; the recorded outcome is replayed instead of double-executing. | | `observedFrame` | string | no | min length 1 | frameId from the screenshot you decided on. The action is refused (stale_frame) if that frame is no longer current, re-observe and decide again. | | `refuseIfOthersActed` | boolean | no | - | Refuse this action (stale_frame, reason others_acted) if another principal acted on the device after observedFrame was taken. Needs observedFrame. Default: on when you send observedFrame from an API key, a copilot or a run; off for a person acting directly, and off whenever no observedFrame is sent. You are told through `others` either way. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `status` | literal | yes | always `"committed"` | - | | `committedAt` | string | yes | - | ISO-8601, control-plane clock, taken when the backend confirmed device commit. | | `idempotencyKey` | string | no | - | The end-to-end key this action was deduplicated under. | | `deduplicated` | boolean | no | - | True when replayed from the receipt ledger without re-executing. | | `others` | object | yes | - | What everybody else did on this device since you last looked. Present on every action result and every leased screenshot. | | `others.actions` | integer | yes | - | How many actions principals other than you took on this device since your anchor. Pending and committed receipts count; failed ones do not. | | `others.lastAt` | string or null | yes | - | When the newest of them was requested, ISO-8601 on the control-plane clock. Null when actions is 0. | | `others.by` | enum\[] | yes | each: one of `person`, `agent` | Who they were: person (a signed-in person acting directly) and/or agent (an API key, a copilot, or a run). Each at most once, person first. | ### swipe Swipe between two points in the 0-1000 grid over durationMs milliseconds (default 300). **Required scope:** `devices:act` **Annotations:** `title` "Swipe", `readOnlyHint` false, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | | `fromX` | number | yes | min 0, max 1000 | Start x in the normalized 0-1000 grid (origin top-left, current orientation). | | `fromY` | number | yes | min 0, max 1000 | Start y in the normalized 0-1000 grid (origin top-left, current orientation). | | `toX` | number | yes | min 0, max 1000 | End x in the normalized 0-1000 grid (origin top-left, current orientation). | | `toY` | number | yes | min 0, max 1000 | End y in the normalized 0-1000 grid (origin top-left, current orientation). | | `durationMs` | integer | no | min 1, max 10000 | Gesture duration in milliseconds (default 300, max 10000). | | `leaseId` | string | no | min length 1 | Optional. Lease id from acquire_device. Leave it out: the action runs under the lease your organization holds on the device, and a gesture takes the device for you when it holds none. | | `idempotencyKey` | string | no | pattern `^[\x20-\x7e]{1,128}$` | Client-generated request id (1-128 printable ASCII, must not start with "agent:"). Reuse the SAME value when retrying the SAME intended action; the recorded outcome is replayed instead of double-executing. | | `observedFrame` | string | no | min length 1 | frameId from the screenshot you decided on. The action is refused (stale_frame) if that frame is no longer current, re-observe and decide again. | | `refuseIfOthersActed` | boolean | no | - | Refuse this action (stale_frame, reason others_acted) if another principal acted on the device after observedFrame was taken. Needs observedFrame. Default: on when you send observedFrame from an API key, a copilot or a run; off for a person acting directly, and off whenever no observedFrame is sent. You are told through `others` either way. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `status` | literal | yes | always `"committed"` | - | | `committedAt` | string | yes | - | ISO-8601, control-plane clock, taken when the backend confirmed device commit. | | `idempotencyKey` | string | no | - | The end-to-end key this action was deduplicated under. | | `deduplicated` | boolean | no | - | True when replayed from the receipt ledger without re-executing. | | `others` | object | yes | - | What everybody else did on this device since you last looked. Present on every action result and every leased screenshot. | | `others.actions` | integer | yes | - | How many actions principals other than you took on this device since your anchor. Pending and committed receipts count; failed ones do not. | | `others.lastAt` | string or null | yes | - | When the newest of them was requested, ISO-8601 on the control-plane clock. Null when actions is 0. | | `others.by` | enum\[] | yes | each: one of `person`, `agent` | Who they were: person (a signed-in person acting directly) and/or agent (an API key, a copilot, or a run). Each at most once, person first. | ### type_text Type into the focused input (focus one first, e.g. by tapping a search field). **Required scope:** `devices:act` **Annotations:** `title` "Type", `readOnlyHint` false, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | | `text` | string | yes | max length 4096 | Text for the focused input (max 4096 chars). Backends may reject characters they cannot inject. | | `leaseId` | string | no | min length 1 | Optional. Lease id from acquire_device. Leave it out: the action runs under the lease your organization holds on the device, and a gesture takes the device for you when it holds none. | | `idempotencyKey` | string | no | pattern `^[\x20-\x7e]{1,128}$` | Client-generated request id (1-128 printable ASCII, must not start with "agent:"). Reuse the SAME value when retrying the SAME intended action; the recorded outcome is replayed instead of double-executing. | | `observedFrame` | string | no | min length 1 | frameId from the screenshot you decided on. The action is refused (stale_frame) if that frame is no longer current, re-observe and decide again. | | `refuseIfOthersActed` | boolean | no | - | Refuse this action (stale_frame, reason others_acted) if another principal acted on the device after observedFrame was taken. Needs observedFrame. Default: on when you send observedFrame from an API key, a copilot or a run; off for a person acting directly, and off whenever no observedFrame is sent. You are told through `others` either way. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `status` | literal | yes | always `"committed"` | - | | `committedAt` | string | yes | - | ISO-8601, control-plane clock, taken when the backend confirmed device commit. | | `idempotencyKey` | string | no | - | The end-to-end key this action was deduplicated under. | | `deduplicated` | boolean | no | - | True when replayed from the receipt ledger without re-executing. | | `others` | object | yes | - | What everybody else did on this device since you last looked. Present on every action result and every leased screenshot. | | `others.actions` | integer | yes | - | How many actions principals other than you took on this device since your anchor. Pending and committed receipts count; failed ones do not. | | `others.lastAt` | string or null | yes | - | When the newest of them was requested, ISO-8601 on the control-plane clock. Null when actions is 0. | | `others.by` | enum\[] | yes | each: one of `person`, `agent` | Who they were: person (a signed-in person acting directly) and/or agent (an API key, a copilot, or a run). Each at most once, person first. | ### press_key Press a hardware or navigation key. The keys this tool accepts are the widest set any platform supports; a device supports a subset, published in its list_devices capabilities. **Required scope:** `devices:act` **Annotations:** `title` "Press a key", `readOnlyHint` false, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | | `key` | enum | yes | one of `home`, `back`, `enter`, `delete`, `app_switch`, `power`, `volume_up`, `volume_down` | Key to press. Check the device's capabilities for its supported subset. | | `leaseId` | string | no | min length 1 | Optional. Lease id from acquire_device. Leave it out: the action runs under the lease your organization holds on the device, and a gesture takes the device for you when it holds none. | | `idempotencyKey` | string | no | pattern `^[\x20-\x7e]{1,128}$` | Client-generated request id (1-128 printable ASCII, must not start with "agent:"). Reuse the SAME value when retrying the SAME intended action; the recorded outcome is replayed instead of double-executing. | | `observedFrame` | string | no | min length 1 | frameId from the screenshot you decided on. The action is refused (stale_frame) if that frame is no longer current, re-observe and decide again. | | `refuseIfOthersActed` | boolean | no | - | Refuse this action (stale_frame, reason others_acted) if another principal acted on the device after observedFrame was taken. Needs observedFrame. Default: on when you send observedFrame from an API key, a copilot or a run; off for a person acting directly, and off whenever no observedFrame is sent. You are told through `others` either way. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `status` | literal | yes | always `"committed"` | - | | `committedAt` | string | yes | - | ISO-8601, control-plane clock, taken when the backend confirmed device commit. | | `idempotencyKey` | string | no | - | The end-to-end key this action was deduplicated under. | | `deduplicated` | boolean | no | - | True when replayed from the receipt ledger without re-executing. | | `others` | object | yes | - | What everybody else did on this device since you last looked. Present on every action result and every leased screenshot. | | `others.actions` | integer | yes | - | How many actions principals other than you took on this device since your anchor. Pending and committed receipts count; failed ones do not. | | `others.lastAt` | string or null | yes | - | When the newest of them was requested, ISO-8601 on the control-plane clock. Null when actions is 0. | | `others.by` | enum\[] | yes | each: one of `person`, `agent` | Who they were: person (a signed-in person acting directly) and/or agent (an API key, a copilot, or a run). Each at most once, person first. | ### open_app Open an app by OS-level id (Android package name / iOS bundle id). **Required scope:** `devices:act` **Annotations:** `title` "Open an app", `readOnlyHint` false, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | | `appId` | string | yes | min length 1 | OS-level app id (Android package name / iOS bundle id). | | `leaseId` | string | no | min length 1 | Optional. Lease id from acquire_device. Leave it out: the action runs under the lease your organization holds on the device, and a gesture takes the device for you when it holds none. | | `idempotencyKey` | string | no | pattern `^[\x20-\x7e]{1,128}$` | Client-generated request id (1-128 printable ASCII, must not start with "agent:"). Reuse the SAME value when retrying the SAME intended action; the recorded outcome is replayed instead of double-executing. | | `observedFrame` | string | no | min length 1 | frameId from the screenshot you decided on. The action is refused (stale_frame) if that frame is no longer current, re-observe and decide again. | | `refuseIfOthersActed` | boolean | no | - | Refuse this action (stale_frame, reason others_acted) if another principal acted on the device after observedFrame was taken. Needs observedFrame. Default: on when you send observedFrame from an API key, a copilot or a run; off for a person acting directly, and off whenever no observedFrame is sent. You are told through `others` either way. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `status` | literal | yes | always `"committed"` | - | | `committedAt` | string | yes | - | ISO-8601, control-plane clock, taken when the backend confirmed device commit. | | `idempotencyKey` | string | no | - | The end-to-end key this action was deduplicated under. | | `deduplicated` | boolean | no | - | True when replayed from the receipt ledger without re-executing. | | `others` | object | yes | - | What everybody else did on this device since you last looked. Present on every action result and every leased screenshot. | | `others.actions` | integer | yes | - | How many actions principals other than you took on this device since your anchor. Pending and committed receipts count; failed ones do not. | | `others.lastAt` | string or null | yes | - | When the newest of them was requested, ISO-8601 on the control-plane clock. Null when actions is 0. | | `others.by` | enum\[] | yes | each: one of `person`, `agent` | Who they were: person (a signed-in person acting directly) and/or agent (an API key, a copilot, or a run). Each at most once, person first. | ### long_press Press and hold at (x, y) in the 0-1000 grid for durationMs (default 800), returning the ActionOutcome like tap. Only on a device whose capabilities say actions.longPress: a backend that cannot hold refuses with capability_unsupported rather than landing a brief press under this name. **Required scope:** `devices:act` · **Added in:** 0.2.0 **Annotations:** `title` "Press and hold", `readOnlyHint` false, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | | `x` | number | yes | min 0, max 1000 | Press x in the normalized 0-1000 grid (origin top-left, current orientation). | | `y` | number | yes | min 0, max 1000 | Press y in the normalized 0-1000 grid (origin top-left, current orientation). | | `durationMs` | integer | no | min 200, max 10000 | Hold duration in milliseconds (default 800, min 200, shorter is a tap, max 10000). | | `leaseId` | string | no | min length 1 | Optional. Lease id from acquire_device. Leave it out: the action runs under the lease your organization holds on the device, and a gesture takes the device for you when it holds none. | | `idempotencyKey` | string | no | pattern `^[\x20-\x7e]{1,128}$` | Client-generated request id (1-128 printable ASCII, must not start with "agent:"). Reuse the SAME value when retrying the SAME intended action; the recorded outcome is replayed instead of double-executing. | | `observedFrame` | string | no | min length 1 | frameId from the screenshot you decided on. The action is refused (stale_frame) if that frame is no longer current, re-observe and decide again. | | `refuseIfOthersActed` | boolean | no | - | Refuse this action (stale_frame, reason others_acted) if another principal acted on the device after observedFrame was taken. Needs observedFrame. Default: on when you send observedFrame from an API key, a copilot or a run; off for a person acting directly, and off whenever no observedFrame is sent. You are told through `others` either way. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `status` | literal | yes | always `"committed"` | - | | `committedAt` | string | yes | - | ISO-8601, control-plane clock, taken when the backend confirmed device commit. | | `idempotencyKey` | string | no | - | The end-to-end key this action was deduplicated under. | | `deduplicated` | boolean | no | - | True when replayed from the receipt ledger without re-executing. | | `others` | object | yes | - | What everybody else did on this device since you last looked. Present on every action result and every leased screenshot. | | `others.actions` | integer | yes | - | How many actions principals other than you took on this device since your anchor. Pending and committed receipts count; failed ones do not. | | `others.lastAt` | string or null | yes | - | When the newest of them was requested, ISO-8601 on the control-plane clock. Null when actions is 0. | | `others.by` | enum\[] | yes | each: one of `person`, `agent` | Who they were: person (a signed-in person acting directly) and/or agent (an API key, a copilot, or a run). Each at most once, person first. | ### wake Turn the device's screen on and drop its lock screen. Call it when a screenshot comes back black or a live video session shows nothing: a phone whose screen is off renders nothing until it is woken, and this is the ONLY way to wake one: press_key's `power` is a toggle, as likely to put an awake phone to sleep. Works where the device's capabilities say actions.wake: a cloud phone; any other device refuses with capability_unsupported. Safe to repeat: waking an awake phone does nothing. Best-effort, so `accepted` means the device was asked, not that the screen is on; take a screenshot to see. Writes no receipt, unlike the gesture tools. **Required scope:** `devices:act` · **Added in:** 0.6.0 **Annotations:** `title` "Wake the screen", `readOnlyHint` false, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | | `leaseId` | string | no | min length 1 | Optional. Lease id from acquire_device. Leave it out: the action runs under the lease your organization holds on the device, and a gesture takes the device for you when it holds none. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `accepted` | literal | yes | always `true` | The wake was dispatched to the device. It does NOT mean the screen is on: take a screenshot to see. | ### get_device One device's current status and capabilities without enumerating the whole fleet. **Required scope:** `devices:read` · **Added in:** 0.2.0 **Annotations:** `title` "Look at one phone", `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | - | - | | `backendKind` | enum | yes | one of `adb_cloud`, `adb_real`, `emulator`, `robot_hand`, `esp32_hid`, `byod_portal` | - | | `kind` | enum | yes | one of `emulator`, `cloud_phone`, `physical`, `robot` | - | | `status` | enum | yes | one of `online`, `offline`, `unauthorized`, `unknown` | - | | `capabilities` | object | yes | discriminated by `fidelityTier`: `"software"`, `"hid"`, `"physical"` | - | | `metadata` | object | yes | arbitrary keys | - | | `displayName` | string | no | - | - | | `info` | object | no | - | - | | `info.model` | string | no | - | - | | `info.androidVersion` | string | no | - | - | | `info.osVersion` | string | no | - | - | | `info.resolution` | object | no | - | - | | `info.carrier` | string or null | no | - | - | ### get_receipt Look up the receipt for an action by its idempotencyKey, the recovery path when an action's response was lost (transport timeout, stateless HTTP has no progress channel). found:false means the action never began and the SAME key is safe to retry. This answers about ONE key you already hold; to ENUMERATE recent receipts use GET /v1/receipts on the REST API. **Required scope:** `devices:read` · **Added in:** 0.2.0 **Annotations:** `title` "Look up what an action did", `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | | `idempotencyKey` | string | yes | pattern `^[\x20-\x7e]{1,128}$` | The idempotencyKey the action was sent with (1-128 printable ASCII). Required. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `found` | boolean | yes | - | - | | `receipt` | object | no | - | - | | `receipt.orgId` | string | yes | - | - | | `receipt.deviceId` | string | yes | - | - | | `receipt.idempotencyKey` | string | yes | - | - | | `receipt.backendKind` | enum | yes | one of `adb_cloud`, `adb_real`, `emulator`, `robot_hand`, `esp32_hid`, `byod_portal` | - | | `receipt.action` | enum | yes | one of `tap`, `swipe`, `typeText`, `pressKey`, `rotate`, `openApp`, `installApp`, `updateApp`, `uninstallApp` | - | | `receipt.argsSummary` | object | yes | arbitrary keys | - | | `receipt.observedFrame` | string | no | - | - | | `receipt.status` | enum | yes | one of `pending`, `committed`, `failed` | - | | `receipt.requestedAt` | string | yes | - | - | | `receipt.committedAt` | string | no | - | - | | `receipt.failedAt` | string | no | - | - | | `receipt.error` | object | no | - | - | | `receipt.reason` | enum | no | one of `interrupted_by_restart`, `outcome_unknown` | - | | `receipt.requiresManualReview` | boolean | no | - | - | | `receipt.actor` | object | no | - | Who acted, by kind (@since 0.7.0). `system` is PhoneUse itself (a schedule's timer, or PhoneUse driving a run), and `onBehalfOf` then says for whom: a schedule by id, a person or key by kind only. Credential ids are not on this tool; `GET /v1/receipts` carries them. | ### start_run Start an agent run for one natural-language goal. `executor` says who drives it. `phoneuse` runs it for you and returns no url. `self_hosted` means PhoneUse executes nothing: nothing happens on the device until your own worker connects to the run-scoped VisualRemote base url returned once here, which is a credential, and which is why `workerConnected` is false. Returns a runId to poll with get_run. Low-level tools stay available for deterministic control. **Required scope:** `runs:start` · **Added in:** 0.7.0 **Annotations:** `title` "Start a run", `readOnlyHint` false, `destructiveHint` true, `idempotentHint` false, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `semanticPlan` | object | no | - | - | | `semanticPlan.goalRevision` | integer | yes | min 0, max 9007199254740991 | - | | `semanticPlan.confirmed` | literal | yes | always `true` | - | | `semanticPlan.goalChecks` | object\[] | yes | - | - | | `semanticPlan.semanticSteps` | object\[] | yes | - | - | | `semanticPlan.screenPrerequisites` | object\[] | no | - | - | | `parameterInputs` | object\[] | no | - | - | | `parameterInputs[].slotRef` | string | yes | min length 1, max length 200 | - | | `parameterInputs[].type` | literal | yes | always `"text"` | - | | `parameterInputs[].value` | string | yes | min length 1, max length 4096 | - | | `parameterInputs[].nonSensitiveConfirmed` | literal | yes | always `true` | - | | `deviceId` | string | yes | min length 1 | Device id from list_devices. | | `leaseId` | string | no | min length 1 | Optional. Lease id from acquire_device. Leave it out: the action runs under the lease your organization holds on the device, and a gesture takes the device for you when it holds none. | | `goal` | string | yes | min length 1, max length 4000 | What to accomplish on the device, in natural language. | | `maxSteps` | integer | no | min 1 | Ceiling on metered steps for this run. A value above the server's own limit is capped to that limit, not refused (the limit is deployment configuration, not a published number); read the run's maxSteps for the effective ceiling. | | `deadlineMs` | integer | no | min 1000 | Wall-clock budget in ms, at least 1000 (a smaller window would be born expired). Capped by the server limit AND by the lease's own expiry. | | `executor` | enum | no | one of `phoneuse`, `self_hosted` | Who drives the run. `phoneuse` runs it for you and returns no run url; `self_hosted` means your own worker drives it through the `vrxBaseUrl` returned once. Default: `self_hosted` for an API key, `phoneuse` for a signed-in person. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `runId` | string | yes | - | The run. Use it on every later call about this run. | | `agentRunId` | string | yes | - | - | | `state` | enum | yes | one of `queued`, `running`, `needs_user_control`, `paused`, `succeeded`, `failed`, `canceled` | - | | `maxSteps` | integer | yes | - | The EFFECTIVE step ceiling: your ask, capped by the server's limit. Read this rather than assuming your ask was honoured. | | `deadlineAt` | string | yes | - | The effective wall-clock deadline (ISO 8601): your deadlineMs, capped by the server limit and the lease's expiry. | | `executor` | enum | yes | one of `phoneuse`, `self_hosted` | Who drives the run, as decided: what you asked for, or the default for your credential. | | `vrxBaseUrl` | string | no | - | Run-scoped VisualRemote base url for your worker, present ONLY when `executor` is `self_hosted`. Treat as a credential: it grants this one device for this one run. | | `workerConnected` | literal | yes | always `false` | Always false here, for two different reasons. On a `self_hosted` run no worker can have connected yet, because this response is the first place `vrxBaseUrl` exists, and nothing happens on the device until yours does. On a `phoneuse` run no worker ever connects at all: PhoneUse drives it, and its progress shows as `stepSeq` on the run rather than here. | ### get_run Bounded long-poll for a run's state. Returns immediately by default; with waitMs + sinceState it waits for a change and answers at the deadline regardless, it never hangs. Never echoes the run url. **Required scope:** `runs:start` · **Added in:** 0.7.0 **Annotations:** `title` "Watch a run", `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `runId` | string | yes | min length 1 | The runId start_run returned. | | `waitMs` | integer | no | min 0, max 25000 | Bounded wait for a state change, 0-25000 ms (default 0 = answer immediately). | | `sinceState` | enum | no | one of `queued`, `running`, `needs_user_control`, `paused`, `succeeded`, `failed`, `canceled` | Return as soon as the state differs from this one; otherwise answer at the deadline. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `progress` | object | no | - | - | | `progress.revision` | integer | yes | min 0 | - | | `progress.goalRevision` | integer | yes | min 0 | - | | `progress.completedStepIds` | string\[] | yes | - | - | | `progress.remainingStepIds` | string\[] | yes | - | - | | `progress.unresolvedOperations` | object\[] | yes | - | - | | `progress.goalChecks` | object\[] | yes | - | - | | `progress.verifiedOutcome` | boolean | yes | - | - | | `recovery` | object or null | no | - | - | | `recovery.id` | string | yes | - | - | | `recovery.since` | string | yes | - | - | | `recovery.remainingMs` | integer | yes | min 0, max 9007199254740991 | - | | `recovery.blockedReason` | enum or null | yes | one of `action_unresolved`, `budget_exhausted` | - | | `runId` | string | yes | - | - | | `agentRunId` | string | yes | - | - | | `deviceId` | string | yes | - | - | | `goal` | string | yes | - | What this run was asked to accomplish, in the words it was started with (@since 0.3.0). | | `executor` | enum | yes | one of `phoneuse`, `self_hosted` | Who drives this run: `phoneuse` (we do) or `self_hosted` (your worker does). | | `state` | enum | yes | one of `queued`, `running`, `needs_user_control`, `paused`, `succeeded`, `failed`, `canceled` | - | | `stepSeq` | integer | yes | - | Metered steps issued so far (one per frame served through VRX). | | `maxSteps` | integer | yes | - | - | | `deadlineAt` | string or null | yes | - | - | | `createdAt` | string | yes | - | - | | `updatedAt` | string | yes | - | - | | `workerFirstContactAt` | string or null | yes | - | When a self-hosted worker first reached this run, or null when none ever did. On a `self_hosted` run you supply the worker, and one that stays queued with null here is waiting for it. A `phoneuse` run is driven in process and never sets this. | | `initiator` | object | yes | - | Who started this run. Always present; see `kind` for what it can and cannot say. | | `initiator.kind` | enum | yes | one of `api_key`, `oauth`, `dev_token`, `system`, `unattributed` | Which credential started the run. `system` is PhoneUse itself (a schedule's timer). `unattributed` means the record cannot say, a run older than this field, and is NOT the same as a positive claim that no key was involved. | | `initiator.userId` | string | no | - | The authorization server's subject id of the person, when a person started it. An id, never a name. | | `initiator.apiKeyId` | string | no | - | The key's id, when a key started it. | | `initiator.viaCopilot` | boolean | yes | - | Whether a copilot started it for the person named above. Always present. | | `initiator.onBehalfOf` | object | no | - | Whose work PhoneUse did, present exactly when the principal kind is `system`. | | `reason` | enum | no | one of `worker_reported_failure`, `budget_exhausted`, `deadline_exceeded`, `canceled_by_caller`, `lease_lost`, `interrupted_by_restart` | - | | `detail` | string | no | - | - | | `lastFrame` | object or null | yes | - | The last frame this run looked at, or null when it never looked (@since 0.8.0). `GET /v1/frames/{frameId}` turns the id into a short-lived image URL, where the deployment archives frames; where it does not, the id is still minted and that route answers 404. | | `lastFrame.frameId` | string | yes | - | - | | `lastFrame.viewport` | object | yes | - | - | ### list_runs List this org's runs, newest first. Each entry carries the goal it was started with and how it ended, so a lost runId is recoverable. Page with the returned nextBefore cursor. Never echoes a run url. **Required scope:** `runs:start` · **Added in:** 0.7.0 **Annotations:** `title` "List your runs", `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `limit` | integer | no | min 1, max 200 | How many runs to return, 1-200 (default 50). Newest first. | | `before` | string | no | min length 1 | Opaque cursor from a previous page's nextBefore. Returns only runs older than it. | | `state` | enum | no | one of `queued`, `running`, `needs_user_control`, `paused`, `succeeded`, `failed`, `canceled` | Return only runs in this state. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `runs` | object\[] | yes | - | - | | `runs[].progress` | object | no | - | - | | `runs[].recovery` | object or null | no | - | - | | `runs[].runId` | string | yes | - | - | | `runs[].agentRunId` | string | yes | - | - | | `runs[].deviceId` | string | yes | - | - | | `runs[].goal` | string | yes | - | What this run was asked to accomplish, in the words it was started with (@since 0.3.0). | | `runs[].executor` | enum | yes | one of `phoneuse`, `self_hosted` | Who drives this run: `phoneuse` (we do) or `self_hosted` (your worker does). | | `runs[].state` | enum | yes | one of `queued`, `running`, `needs_user_control`, `paused`, `succeeded`, `failed`, `canceled` | - | | `runs[].stepSeq` | integer | yes | - | Metered steps issued so far (one per frame served through VRX). | | `runs[].maxSteps` | integer | yes | - | - | | `runs[].deadlineAt` | string or null | yes | - | - | | `runs[].createdAt` | string | yes | - | - | | `runs[].updatedAt` | string | yes | - | - | | `runs[].workerFirstContactAt` | string or null | yes | - | When a self-hosted worker first reached this run, or null when none ever did. On a `self_hosted` run you supply the worker, and one that stays queued with null here is waiting for it. A `phoneuse` run is driven in process and never sets this. | | `runs[].initiator` | object | yes | - | Who started this run. Always present; see `kind` for what it can and cannot say. | | `runs[].reason` | enum | no | one of `worker_reported_failure`, `budget_exhausted`, `deadline_exceeded`, `canceled_by_caller`, `lease_lost`, `interrupted_by_restart` | - | | `runs[].detail` | string | no | - | - | | `runs[].lastFrame` | object or null | yes | - | The last frame this run looked at, or null when it never looked (@since 0.8.0). `GET /v1/frames/{frameId}` turns the id into a short-lived image URL, where the deployment archives frames; where it does not, the id is still minted and that route answers 404. | | `nextBefore` | string | no | - | Cursor for the next (older) page; absent when this page reached the end. | ### cancel_run End a run and destroy its VisualRemote credential. Already-terminal runs are returned unchanged, terminal is terminal. **Required scope:** `runs:start` · **Added in:** 0.7.0 **Annotations:** `title` "Stop a run", `readOnlyHint` false, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `runId` | string | yes | min length 1 | The runId start_run returned. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `progress` | object | no | - | - | | `progress.revision` | integer | yes | min 0 | - | | `progress.goalRevision` | integer | yes | min 0 | - | | `progress.completedStepIds` | string\[] | yes | - | - | | `progress.remainingStepIds` | string\[] | yes | - | - | | `progress.unresolvedOperations` | object\[] | yes | - | - | | `progress.goalChecks` | object\[] | yes | - | - | | `progress.verifiedOutcome` | boolean | yes | - | - | | `recovery` | object or null | no | - | - | | `recovery.id` | string | yes | - | - | | `recovery.since` | string | yes | - | - | | `recovery.remainingMs` | integer | yes | min 0, max 9007199254740991 | - | | `recovery.blockedReason` | enum or null | yes | one of `action_unresolved`, `budget_exhausted` | - | | `runId` | string | yes | - | - | | `agentRunId` | string | yes | - | - | | `deviceId` | string | yes | - | - | | `goal` | string | yes | - | What this run was asked to accomplish, in the words it was started with (@since 0.3.0). | | `executor` | enum | yes | one of `phoneuse`, `self_hosted` | Who drives this run: `phoneuse` (we do) or `self_hosted` (your worker does). | | `state` | enum | yes | one of `queued`, `running`, `needs_user_control`, `paused`, `succeeded`, `failed`, `canceled` | - | | `stepSeq` | integer | yes | - | Metered steps issued so far (one per frame served through VRX). | | `maxSteps` | integer | yes | - | - | | `deadlineAt` | string or null | yes | - | - | | `createdAt` | string | yes | - | - | | `updatedAt` | string | yes | - | - | | `workerFirstContactAt` | string or null | yes | - | When a self-hosted worker first reached this run, or null when none ever did. On a `self_hosted` run you supply the worker, and one that stays queued with null here is waiting for it. A `phoneuse` run is driven in process and never sets this. | | `initiator` | object | yes | - | Who started this run. Always present; see `kind` for what it can and cannot say. | | `initiator.kind` | enum | yes | one of `api_key`, `oauth`, `dev_token`, `system`, `unattributed` | Which credential started the run. `system` is PhoneUse itself (a schedule's timer). `unattributed` means the record cannot say, a run older than this field, and is NOT the same as a positive claim that no key was involved. | | `initiator.userId` | string | no | - | The authorization server's subject id of the person, when a person started it. An id, never a name. | | `initiator.apiKeyId` | string | no | - | The key's id, when a key started it. | | `initiator.viaCopilot` | boolean | yes | - | Whether a copilot started it for the person named above. Always present. | | `initiator.onBehalfOf` | object | no | - | Whose work PhoneUse did, present exactly when the principal kind is `system`. | | `reason` | enum | no | one of `worker_reported_failure`, `budget_exhausted`, `deadline_exceeded`, `canceled_by_caller`, `lease_lost`, `interrupted_by_restart` | - | | `detail` | string | no | - | - | | `lastFrame` | object or null | yes | - | The last frame this run looked at, or null when it never looked (@since 0.8.0). `GET /v1/frames/{frameId}` turns the id into a short-lived image URL, where the deployment archives frames; where it does not, the id is still minted and that route answers 404. | | `lastFrame.frameId` | string | yes | - | - | | `lastFrame.viewport` | object | yes | - | - | ### resume_run Resume a run that is on hold: one a person paused with pause_run, or one in needs_user_control waiting for a person. If recovery is present, pass expectedRecoveryId equal to its current id and hold the device's current lease yourself; a missing lease fails with lease_required and another person's lease fails with lease_mismatch. Missing or stale recovery ids, blocked recovery, or exhausted recovery budget return the run unchanged without restarting it. Recovery waiting preserves progress and freezes the remaining execution time until this explicit continuation. For ordinary pauses or steps such as a login or challenge, existing resume behavior applies: a paused run needs the lease it acts under and fails with lease_mismatch when the device has moved on. Finished and other ineligible runs are returned unchanged. **Required scope:** `runs:start` · **Added in:** 0.7.0 **Annotations:** `title` "Let a run carry on", `readOnlyHint` false, `destructiveHint` true, `idempotentHint` true, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `runId` | string | yes | min length 1 | The runId of a run that is paused or parked in needs_user_control. | | `expectedRecoveryId` | string | no | - | The current recovery.id, required to continue saved recovery waiting. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `progress` | object | no | - | - | | `progress.revision` | integer | yes | min 0 | - | | `progress.goalRevision` | integer | yes | min 0 | - | | `progress.completedStepIds` | string\[] | yes | - | - | | `progress.remainingStepIds` | string\[] | yes | - | - | | `progress.unresolvedOperations` | object\[] | yes | - | - | | `progress.goalChecks` | object\[] | yes | - | - | | `progress.verifiedOutcome` | boolean | yes | - | - | | `recovery` | object or null | no | - | - | | `recovery.id` | string | yes | - | - | | `recovery.since` | string | yes | - | - | | `recovery.remainingMs` | integer | yes | min 0, max 9007199254740991 | - | | `recovery.blockedReason` | enum or null | yes | one of `action_unresolved`, `budget_exhausted` | - | | `runId` | string | yes | - | - | | `agentRunId` | string | yes | - | - | | `deviceId` | string | yes | - | - | | `goal` | string | yes | - | What this run was asked to accomplish, in the words it was started with (@since 0.3.0). | | `executor` | enum | yes | one of `phoneuse`, `self_hosted` | Who drives this run: `phoneuse` (we do) or `self_hosted` (your worker does). | | `state` | enum | yes | one of `queued`, `running`, `needs_user_control`, `paused`, `succeeded`, `failed`, `canceled` | - | | `stepSeq` | integer | yes | - | Metered steps issued so far (one per frame served through VRX). | | `maxSteps` | integer | yes | - | - | | `deadlineAt` | string or null | yes | - | - | | `createdAt` | string | yes | - | - | | `updatedAt` | string | yes | - | - | | `workerFirstContactAt` | string or null | yes | - | When a self-hosted worker first reached this run, or null when none ever did. On a `self_hosted` run you supply the worker, and one that stays queued with null here is waiting for it. A `phoneuse` run is driven in process and never sets this. | | `initiator` | object | yes | - | Who started this run. Always present; see `kind` for what it can and cannot say. | | `initiator.kind` | enum | yes | one of `api_key`, `oauth`, `dev_token`, `system`, `unattributed` | Which credential started the run. `system` is PhoneUse itself (a schedule's timer). `unattributed` means the record cannot say, a run older than this field, and is NOT the same as a positive claim that no key was involved. | | `initiator.userId` | string | no | - | The authorization server's subject id of the person, when a person started it. An id, never a name. | | `initiator.apiKeyId` | string | no | - | The key's id, when a key started it. | | `initiator.viaCopilot` | boolean | yes | - | Whether a copilot started it for the person named above. Always present. | | `initiator.onBehalfOf` | object | no | - | Whose work PhoneUse did, present exactly when the principal kind is `system`. | | `reason` | enum | no | one of `worker_reported_failure`, `budget_exhausted`, `deadline_exceeded`, `canceled_by_caller`, `lease_lost`, `interrupted_by_restart` | - | | `detail` | string | no | - | - | | `lastFrame` | object or null | yes | - | The last frame this run looked at, or null when it never looked (@since 0.8.0). `GET /v1/frames/{frameId}` turns the id into a short-lived image URL, where the deployment archives frames; where it does not, the id is still minted and that route answers 404. | | `lastFrame.frameId` | string | yes | - | - | | `lastFrame.viewport` | object | yes | - | - | ### pause_run Put a run on hold so a person can act on the device while the agent waits. The run's deadline stops advancing and the lease it acts under is slid to a fresh window; the hold ends at manualControlUntil, after which an unresumed run is canceled. Resume it with resume_run. Fails with lease_mismatch when the device has already moved on. **Required scope:** `runs:start` · **Added in:** 0.7.0 **Annotations:** `title` "Hold a run", `readOnlyHint` false, `destructiveHint` false, `idempotentHint` false, `openWorldHint` false **Parameters** | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `runId` | string | yes | min length 1 | The runId of the run to put on hold. | **Result fields** (the `structuredContent` of a successful call) | Field | Type | Required | Constraints | Description | | - | - | - | - | - | | `run` | object | yes | - | - | | `run.progress` | object | no | - | - | | `run.recovery` | object or null | no | - | - | | `run.runId` | string | yes | - | - | | `run.agentRunId` | string | yes | - | - | | `run.deviceId` | string | yes | - | - | | `run.goal` | string | yes | - | What this run was asked to accomplish, in the words it was started with (@since 0.3.0). | | `run.executor` | enum | yes | one of `phoneuse`, `self_hosted` | Who drives this run: `phoneuse` (we do) or `self_hosted` (your worker does). | | `run.state` | enum | yes | one of `queued`, `running`, `needs_user_control`, `paused`, `succeeded`, `failed`, `canceled` | - | | `run.stepSeq` | integer | yes | - | Metered steps issued so far (one per frame served through VRX). | | `run.maxSteps` | integer | yes | - | - | | `run.deadlineAt` | string or null | yes | - | - | | `run.createdAt` | string | yes | - | - | | `run.updatedAt` | string | yes | - | - | | `run.workerFirstContactAt` | string or null | yes | - | When a self-hosted worker first reached this run, or null when none ever did. On a `self_hosted` run you supply the worker, and one that stays queued with null here is waiting for it. A `phoneuse` run is driven in process and never sets this. | | `run.initiator` | object | yes | - | Who started this run. Always present; see `kind` for what it can and cannot say. | | `run.reason` | enum | no | one of `worker_reported_failure`, `budget_exhausted`, `deadline_exceeded`, `canceled_by_caller`, `lease_lost`, `interrupted_by_restart` | - | | `run.detail` | string | no | - | - | | `run.lastFrame` | object or null | yes | - | The last frame this run looked at, or null when it never looked (@since 0.8.0). `GET /v1/frames/{frameId}` turns the id into a short-lived image URL, where the deployment archives frames; where it does not, the id is still minted and that route answers 404. | | `leaseId` | string | yes | - | The lease the run acts under, slid to a fresh window for the hold. | | `manualControlUntil` | string | yes | - | When the hold ends (ISO 8601). Past it, an unresumed run is canceled. | # Transports Source: https://docs.phoneuse.com/mcp/transports stdio and HTTP publish the same tools. Here is what actually differs. The control plane speaks MCP over two transports, and both publish the same tool surface: the stdio one is a relay to the HTTP endpoint, so a tool you can call on one you can call on the other. What differs is authentication, statefulness, and which optional protocol features can physically reach you. ## At a glance | | stdio (the CLI relay) | HTTP | | - | - | - | | How it starts | Your client spawns `phoneuse mcp --stdio` | Your client posts to `POST /mcp` | | Credential | The key `phoneuse login` stored, or `PHONEUSE_API_KEY` | A bearer token, or a development token locally | | Where it goes | The hosted endpoint, `https://mcp.phoneuse.com/mcp` | Local or hosted | | Lifetime | One process, relaying each message to the stateless endpoint | One server per request | | Progress notifications | No | No | | Human takeover | No | No | Config blocks for both are in [MCP config](/getting-started/mcp-config). ## stdio: the CLI relay `phoneuse mcp --stdio` (CLI [0.5.0](https://www.npmjs.com/package/@phoneuse/cli/v/0.5.0) and later) gives a stdio-only client your cloud phones. It reads MCP messages on standard input, sends each one to `https://mcp.phoneuse.com/mcp` with your key, and writes the answers to standard output. Nothing is interpreted on the way through, so every rule on this page for HTTP applies: the key's scopes decide which tools exist, and there are no progress notifications or human takeover prompts. The CLI refuses to send the key over plain `http` to anything but your own machine. Nothing but the transport writes to standard output, because standard output is the wire. Diagnostics go to standard error, which is where the startup line you see comes from. ## HTTP The endpoint is `POST /mcp`. It speaks JSON-RPC, in JSON response mode, and it is stateless. Stateless means a fresh server and transport are built for each request, and that leases travel as explicit parameters rather than living in a session. There is nothing to resume and nothing to tear down, which is why `GET` and `DELETE` on the same path answer `405` with an `Allow: POST` header. Two protections run on every request, and a client that trips either is refused: * **Host checking.** In hosted mode only the deployment's public host is accepted. Locally only loopback hosts are. * **Origin refusal.** Any request carrying a browser `Origin` header is refused. Without this, a web page could rebind its own hostname to loopback and drive your device with no cross origin preflight standing in its way. Loopback binding stops callers on other machines; it does not stop this. Authentication happens before anything else. Local mode may require a development token; a hosted deployment requires OAuth or an API key. See [Authentication](/mcp/auth). ## What stateless HTTP cannot carry Two protocol features need a live bidirectional session, and this is the part worth reading before you design a loop around them. **Progress notifications.** An action blocks until the device commits. A client that sent a progress token would be told the action was dispatched and is awaiting device commit, but over stateless HTTP, and over the CLI relay in front of it, there is no channel for a mid request notification, so nothing arrives. The server does not fail the action over it: progress is a transport capability, never a promise the tool surface makes. **Human takeover.** Elicitation is a request from the server to the client, so it also needs a live session. Over stateless HTTP it never happens, and the caller sees a terminal outcome instead. The substitute for both is the same one, and it is not a workaround: pass an `idempotencyKey` with your action and use `get_receipt` to find out what happened. That path works on every transport, survives a lost response, and survives a restarted client. See [Progress and takeover](/mcp/progress-and-takeover). ## Choosing Use **stdio** when your client can only spawn a process (Claude Desktop, Cursor): the CLI relay gives it your cloud phones over the hosted endpoint. Use **HTTP** for everything else: anything shared, anything remote, and anything with more than one caller. Whichever you choose, the calls you write do not change. # Quickstart Source: https://docs.phoneuse.com/quickstart Get a key, connect an MCP client, and drive a real phone in about ten minutes. Five steps: sign in, get a key, paste one block of config, drive a device, read the run back as evidence. You need nothing installed beyond an MCP client. **1. Sign in** The console is at [console.phoneuse.com](https://console.phoneuse.com/sign-up). Everything below assumes an account and an organization, and the key in the next step is minted from a signed in session, so this is the step that has to come first. Signing up takes an email address and a password, and confirms the address with a six digit code. The organization is created for you on the way in; you can rename it later in Settings. Keep the tab in front while you submit. A human check runs in the background and can stall in a tab you have switched away from; if nothing happens, see [Signing up](/help/troubleshooting#signing-up). **2. Get a key** Every hosted request authenticates with an org-scoped API key: a single bearer string that starts with `pbk_`. The API also accepts keys that start with `puk_`, and so does the current CLI, [0.6.0](https://www.npmjs.com/package/@phoneuse/cli/v/0.6.0); the older CLI [0.4.1](https://www.npmjs.com/package/@phoneuse/cli/v/0.4.1) accepts only `pbk_`. **Mint one yourself** from the `/keys` screen in the console. You get a key scoped to your org, carrying the scopes you pick, and optionally narrowed to a subset of your devices. Either role can mint: you do not need to be an org admin. What minting does need is a signed in console session, because an API key cannot mint another key. The scopes you request cannot exceed the scopes your own session holds. It is the `/v1/api-keys` surface described in [Authentication](/mcp/auth#getting-a-key). No device yet either? [Buy and drive a device](/guides/first-device) is the whole loop, starting from the console. The full token is shown to you exactly once. Only a hash is stored, so nobody (including PhoneUse) can read it back later. Put it in an environment variable and treat it like a password: ```bash theme={null} export PHONEUSE_API_KEY="pbk__" ``` What the key can do is pinned at issuance: its [scopes](/mcp/auth#scopes) decide which tools exist for you, and it can optionally be narrowed to a subset of your org's devices. If a tool seems missing later, that is your key's scope set, not a fault. **3. Connect** PhoneUse speaks MCP over HTTP. Point any MCP client at the hosted control plane with one block of config: ```json theme={null} { "mcpServers": { "phoneuse": { "type": "http", "url": "https://mcp.phoneuse.com/mcp", "headers": { "Authorization": "Bearer pbk__" } } } } ``` With Claude Code that is one command: ```bash theme={null} claude mcp add --transport http phoneuse https://mcp.phoneuse.com/mcp \ --header "Authorization: Bearer $PHONEUSE_API_KEY" ``` Your client's tool list is the connection test: if the PhoneUse tools appear, you are authenticated and in. Which tools appear is decided by your key's scopes. To check without a client in the way (the endpoint requires an `Accept` header naming both content types): ```bash theme={null} curl -sS https://mcp.phoneuse.com/mcp \ -H "Authorization: Bearer $PHONEUSE_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` Client can only spawn a process (Claude Desktop, Cursor)? Run `npx -y @phoneuse/cli login` once, then use `npx -y @phoneuse/cli mcp --stdio` as the server command. It relays to the same hosted endpoint. Running a control plane on your own machine instead? Local mode is covered in [MCP config](/getting-started/mcp-config). **4. Drive** Every session follows the same four beats: acquire a lease, observe, act under that lease, release. ```text theme={null} list_devices see what is reachable, and what each device can do acquire_device take an exclusive lease, and keep the leaseId screenshot observe, and keep the frameId tap act, under that lease release_device hand the device back ``` Call `list_devices` first and read the `capabilities` on each device before you call anything else. Capabilities differ between devices, and an action the hardware cannot perform is refused rather than silently dropped. If `list_devices` comes back empty, that is provisioning, not a fault: no devices have been attached to your org yet, or your key was narrowed to a subset that is itself empty. Add one from **Add a phone** in the console; that screen names what is available to buy right now. An empty list is not how an unreachable device shows up. A device your org owns is always listed, and when the control plane cannot currently reach it the entry says so in `status` instead of going missing. Two statuses mean that, and the difference between them is whether anything answered. `offline` is a positive report that the device is not up: the cloud phone platform named it and said it was not running. `unknown` means nothing answered at all: the cloud phone platform's fleet listing failed or never mentioned this device, or the row names no reachable transport. Either way the device exists and is yours, and it needs attention on the device side rather than a new device. Treat anything other than `online` as not drivable. A check written as `status === "offline"` silently misses the `unknown` case, which is the one you get when the cloud phone platform stops answering for a device. `leaseId` is optional on every action and observation tool: a gesture runs under the lease your organization holds, or takes the device for you. Coordinates are always on a normalized 0 to 1000 grid, which is why the same tap works across screen sizes. Bounds in the `ui_snapshot` tree are already on that grid, so a value you read there can be tapped directly. Naming the frame does not put your action on a clock. Take as long as you like between the screenshot and the tap, and take more screenshots in between if you want to: neither ages a frame out. What the frame buys you is the answer to the only question that matters here, reported on every action as `others`: did another hand act on this device since you looked, and was it a person or an agent. When a task needs different hardware, the device you name is the only thing that changes. The tool calls do not. **5. Read the run back** The run comes back as evidence rather than as a claim. Every successful result carries typed `structuredContent`, shaped by the `outputSchema` that tool publishes. Every action returns an outcome recording when the device committed it, not merely that the request was accepted. Pass an `idempotencyKey` with an action and you can look that outcome up later with `get_receipt`. Reusing the same key on a retry replays what was recorded instead of performing the gesture a second time. A key whose action failed terminally is the exception: it replays the failure and asks you to retry under a new key. See [Reading a trace](/getting-started/trace). Unknown or misspelled parameters are refused by the schema, so a typo fails loudly instead of travelling on to a real phone. ## When a first run refuses The three refusals new integrations actually hit, and what each is telling you: 1. **A tool you expected is missing from the tool list.** That is your key's scopes, not a fault: an out-of-scope tool is never registered on your connection, so it genuinely does not exist there. The run tools need `runs:start` **and** `devices:act`. See [Authentication](/mcp/auth#scopes). 2. **`acquire_device` answers `device_unavailable` with reason `leased`.** Leases are exclusive per device across your whole org: someone else holds it, or your own earlier session never released. Leases expire on their own, so waiting works, and the holder saw `expiresAt` in their acquire response. Your organization must hold the device. If you supply a `leaseId`, it must match the current lease; a stale or invented id returns `lease_mismatch` without moving the phone. Omit the id to use the current lease or, when permitted, take a free device. If the org holds none and the gesture cannot take one, the refusal is `lease_required`. 3. **`stale_frame`.** The screen changed between your observation and your action, and the action was refused before anything physical happened. Your idempotency key was not consumed: observe again, decide again, act again under the same key. Everything else (error shapes, every code, retry semantics) is in [Troubleshooting](/help/troubleshooting) and the [error reference](/mcp/errors). ## Where to go next > [card] [Tool reference](/mcp/reference) > > Every tool, its parameters, and the scope it needs. > [card] [Device tiers](/devices/tiers) > > What the control plane can reach, and how input reaches it. > [card] [CLI](/cli/overview) > > Install `@phoneuse/cli` from npm, then use the `phoneuse` command. See installation and login instructions. > [card] [Agent tier](/agent/overview) > > Hand a goal to a worker instead of driving each step yourself. # Acceptable use Source: https://docs.phoneuse.com/security/acceptable-use What you may not do with a phone you drive through PhoneUse, and what we do about it. This page is short on purpose. It says what is not allowed, where those rules come from, and what happens when they are broken. It is part of our [Terms of Service](https://www.phoneuse.com/terms). Where the two ever disagree, the Terms of Service win. How we handle personal data is in our [Privacy Policy](https://www.phoneuse.com/privacy). ## Your model supplier's rules reach you through us PhoneUse's copilot sends your instructions to third-party model providers (today an OpenAI model reached through [OpenRouter](https://openrouter.ai/terms)) and runs the model's replies against your phone. That means their rules apply to what you ask for here, not only to what we do. **Your use of the copilot must comply with your model supplier's usage policies.** Those policies are theirs to write and to change, and we pass them on rather than restating them: read [OpenRouter's Terms of Service](https://openrouter.ai/terms) and [OpenAI's usage policies](https://openai.com/policies/usage-policies) for the current text. This is the part people are most often surprised by. A request our own rules do not mention can still be refused upstream, and a refusal that arrives from the model provider is not a PhoneUse fault. ## Three things you may not use a phone for Nothing illegal is allowed, ever. On top of that, these three are ours, and they are about the device rather than the model. 1. **Fraud.** Do not use a phone to deceive a person or a service for gain. That includes payment fraud, fake engagement, fabricated identities and anything whose purpose is to make a counterparty act on a false belief. 2. **Taking accounts that are not yours.** Do not use a phone to sign in to, recover, or hold an account you are not authorised to hold. Credential stuffing, SMS interception for somebody else's login, and working through a list of accounts all fall here. 3. **Getting around a platform's own protections.** Do not use a phone to defeat another service's security or integrity controls. Rate limits, device attestation, bot detection, region locks and account-linking protections are that service's decisions about its own product. The second and third are worth reading together. PhoneUse gives an agent a real handset with a real number, which is exactly the shape of thing those protections exist to see. Having a real device does not make you authorised to use it against somebody else's account. ## What we do when this is broken **We may throttle, suspend, or terminate.** That is the right this policy reserves. What that means in practice today is withdrawal of access. An API key can be revoked, and from its next request it is refused with the reason it was refused for, which is a sentence your client can print. A device can have its entitlement revoked, and `operator` is one of the recorded reasons for that. Withdrawing access is not a deletion. The receipt ledger is a separate record and revoking a credential does not touch it, so what already happened stays readable. ## If you are unsure Ask before you build it. Describe the workflow to us at [abdulla@phoneuse.com](mailto:abdulla@phoneuse.com) and we will tell you whether it is something this product is for. That is a cheaper conversation than discovering the answer after your access is withdrawn. # Frame retention Source: https://docs.phoneuse.com/security/frame-retention How long captured screen frames are kept, and who can read them. A screenshot of a real device in use can contain anything that was on that screen: a signed in app, a message, a personal detail. Frames are therefore treated as the most sensitive thing the control plane touches. ## The default archive policy has no automatic expiry Archiving requires configured frame storage on the deployment. When storage is configured, the default policy enables archiving and keeps frames with no expiry time. An organisation with an explicit policy keeps its own setting. The service does not automatically delete persisted frame bytes. Its background loop reconciles unconfirmed writes and reports storage usage; it does not remove an archived image. Do not assume that returning a device, deleting a chat thread or closing an account erases a separately archived frame. ## Read one available frame `GET /v1/frames/{frameId}` returns a short-lived signed URL for one archived image. Obtain the frame id from a run's `lastFrame.frameId` or an action receipt's `observedFrame`, then call the route with your bearer credential. The credential needs `devices:read` or permission to run tasks, and any device restriction on the credential applies to the frame too. An unknown frame, another organisation's frame, an unconfirmed write, an expired frame or a frame outside the credential's devices all return `404 frame_not_found`. A deployment without frame storage returns that answer for every frame id. A live screenshot can still be available even when no archived copy exists. The former run-frames and receipt-frame endpoints have been withdrawn. Use the current single-frame route rather than those old paths. ### The store is private, and a read uses a URL we mint The store is private in its own right: an anonymous request, a request carrying the public API key, and a request from a signed in browser session are all refused, including the request that only asks whether an object exists. The route returns a **signed URL** for one image rather than pixels. Its normal lifetime is one minute, with a signer cap of five minutes; a finite frame expiry can shorten it. The response contains `frameId` and `url`, not a TTL field. Treat the URL as a password for that one image while it lasts: do not store it, log it, or paste it into a bug report. Fetch a new URL when you need to view the image again. Before any URL is signed, the frame is looked up in the database under your organisation's own row level policy, and the storage location is read out of that row. It is never constructed from the values in a request. That distinction is the authorisation: a location built from arguments would be a valid looking location for somebody else's frame, and object storage has no idea which tenant asked. ### What we do not do to a frame Frames are **not** encrypted at the application layer, and the reason is worth being straight about rather than implying more protection than exists. The protection is the private bucket, a credential whose reach is object storage and not the database, the organisation check above, and the short lived URL. There is no per organisation key, and per frame crypto shredding is not available today. ## Turning archiving off An organisation can be taken out of frame archiving entirely, and can instead choose a finite retention window with a ceiling of 90 days. Both are set through the operational management path, not by you and not by an agent; ask if you want either. Two things about those settings: * **Leaving the archive does not erase what is already in it.** It stops new frames being written. * **A zero day window means the bytes are never written**, not written and then cleaned up shortly after. At that setting the control plane records that a frame was captured and stores no image, so there is nothing waiting on a cleanup process to run on time. An organisation on a finite window has frames that stop being readable through new API requests when that window passes. The database gate enforces this. A finite expiry can shorten a signed URL's lifetime, but signing uses whole seconds with a one-second minimum: an existing URL is not guaranteed to stop working at the exact expiry instant. **Expiry of API access is not deletion of the stored bytes.** Ask about existing archive data when arranging a retention change or deletion request. ## Retention is decoupled from billing, permanently Frame bytes do not participate in billing, usage or quota, and never have. The billing pipeline derives from the receipt ledger, which contains no frames. This is not a coincidence maintained by care. The two read and write completely disjoint paths, and that is checked directly: billing derived with frame data present and billing derived with it gone produce identical results. The consequence that matters to you: what happens to your frames can never cost you a billing record, so "we need it for billing" can never become an argument about images. ## What the control plane keeps besides the image A frame's **identity** is tracked separately from its bytes, and was long before the bytes were stored: * the frame id you can echo back as `observedFrame`, * a per device sequence number, * when it was registered, and the geometry it was captured at. That is what makes it possible to refuse an action decided on a screen that has already changed. The receipt ledger holds no frame bytes. `screenshot` is not one of the actions a receipt records, and the summaries that are recorded are deliberately thin: a typed string is recorded as its **length**, never its content. ## An agent cannot configure its own retention Retention configuration is **not** an MCP tool, and this is a structural decision rather than a backlog item. An agent that could shorten its own audit retention could erase the record of what it did. That defeats the purpose of having a record. So the configuration surface is not reachable from the tool surface at all: it is written through the operational management path, under the same org pinning and row level policies as everything else. Cross org access to that configuration is blocked by the same two independent guards described in [Org isolation](/security/org-isolation), and the absence of a configuration tool on the MCP surface is checked rather than assumed. ## In a private deployment Where the part that reaches your devices runs in your own environment, frames never leave it. The same schema travels with it, and **you** hold the storage. PhoneUse does not reach into your environment to read or remove your data, in the same way it does not reach in to meter it. That deployment shape is a seam that is kept clean, not a product you can buy today. # A leaked credential Source: https://docs.phoneuse.com/security/leaked-credentials What to do first when a key or a run token has been exposed. You pushed a key to a public repository, pasted one into a chat, or found one in a log that more people can read than you thought. This page is the order of operations. Read the first section, do it, then read the rest. ## Do this first: revoke, do not rotate **Revoke the exposed key.** Do not rotate it. That distinction is the single most important thing on this page, because the two look interchangeable and are not: | | What happens to the exposed token | | - | - | | **Revoke** | Refused from the next request onwards. | | **Rotate** | Keeps working for a grace window, **24 hours by default**. | Rotation exists so you can swap a key in a running deployment without an outage, and the grace window is the whole point of it. In a leak, that same window is 24 more hours of access for whoever has your key. Rotation is the routine path and it is the wrong path here. If you rotate anyway, because a hard cutover would take something important down, then **rotate with `graceMs: 0`**. That invalidates the old token immediately and gives you the new one in the same call. `graceMs` accepts any integer from 0 up to 72 hours, so the safe value is available and it is not the default. ## How to revoke, today **Revoke it yourself, in the console.** Open the Keys page at [console.phoneuse.com/keys](https://console.phoneuse.com/keys), signed in to the org the key belongs to, and revoke it. A member can revoke the keys they minted; an admin can revoke any key in the org. Create, rotate, revoke and narrowing to a device subset are all on that page, and it needs nobody's working hours. **If the key was made by `phoneuse login`**, run `phoneuse logout` on that machine. It revokes the key the CLI stored and removes it, and says `Logged out: key ... revoked`. If it prints `warning: could not revoke key` instead, the key is still live: it was only removed from that machine. Revoke it on the Keys page straight away. A key you set in `PHONEUSE_API_KEY` is left alone; revoke that one on the Keys page. A revoked key is refused from the next request onwards, and a request holding it fails with `revoked_key`. If you cannot reach the console, write to the security contact below, say plainly that a key is exposed and must be revoked now, and include the key's **id**, never the token itself. See [Getting a key](/mcp/auth#getting-a-key). ## Security contact Report a leaked key, or any other security problem, to [abdulla@phoneuse.com](mailto:abdulla@phoneuse.com). Put "urgent" in the subject so it is read first. ## Then work out what the key could do A key is not all keys. Before you assume the worst, check what this one was scoped to, because the answer changes how much you have to unwind. * **Scopes.** A key carries a scope set, and a tool outside it is not merely refused, it is never registered on the connection. A key without an action scope could not have touched a device. * **Device narrowing.** A key can be narrowed to a subset of your devices. A narrowed key could not see, let alone drive, anything outside that subset. * **Expiry.** A key has an expiry, and an expired key is refused with `expired_key`. If the leak is older than the key, the exposure window closed on its own. Read those off the key's record rather than assuming. See [Auth and scopes](/mcp/auth). ## What you cannot reconstruct today Say it here rather than let you discover it during an incident. Receipts record what happened to a device: the org, the device, the idempotency key, the backend kind, the action, a summary of its arguments, the frame it was bound to, the outcome and the timestamps. What a receipt does **not** record is **which key made the call**. There is no actor or key id on the ledger, so "what did this specific key do" is not a question this surface can answer yet. The one signal that exists is `lastUsedAt` on the key itself, and it is worth knowing that it lags, so a quiet key is weak evidence rather than proof of an unused one. Two consequences follow, and both point the same way: 1. Treat the exposure window as everything the key was scoped to reach, for the whole time it was valid, rather than trying to narrow it from the ledger. 2. Revoke first and investigate second. Investigation is the part that is currently limited; revocation is not. ## A leaked run token A run token is a credential too, and it is the whole url rather than a header, which is why it ends up in logs and issue threads more easily than a key does. A run token is bound to one device, one lease and one run. It cannot be used to reach another device in your org, and it expires. Ending the run ends the token's usefulness: cancel the run, and a request carrying that token is refused the same way an unknown one is. See [VRX device channel](/agent/vrx). # Org isolation Source: https://docs.phoneuse.com/security/org-isolation Where the boundary between orgs runs, and what enforces it. The **org** is the unit of isolation. An org owns its devices, its credentials, its leases, its receipts and its usage. Nothing crosses between orgs, and this page describes what makes that true rather than merely intended. An operator is a person who belongs to one or more orgs. An agent acts on behalf of an org with a credential issued for it. Neither one owns anything: the org does. ## Org context comes from the request Every request resolves to exactly one org, at the entry point, once. There is no process wide notion of a current org. There never has been, and the service is built so that there cannot be: an org identifier is a checked value rather than a bare string, so an unvalidated value cannot reach a query or a storage key by accident. From the entry point onward the org travels as an explicit parameter into every call. Where it comes from depends on the credential: * **An OAuth token** carries the org in a claim, using the same claim name the database's own policies read. * **An API key** is issued for exactly one org and resolves to it. There is no authenticated state without an org. It is not a case the code has to handle, because the shape of the authorization context does not permit it. ## Two independent guards on the data Isolation does not rest on one mechanism, because one mechanism has one bug. **A forced org scope in the application.** Every read and write is scoped to the resolved org before it reaches the database. A query carrying no org condition is refused outright rather than left for a reviewer to catch. **Row level security in the database.** Every table that holds more than one org's data has policies enabled. Inside the transaction the resolved org is set as a session variable, and the policies read it. The control plane connects with a dedicated database role that **cannot** bypass row level security. This is the detail that makes the two guards genuinely independent rather than nominally so: if the application layer ever failed to scope a query, the database would still refuse the rows. Each is the other's backstop. The same policy set serves the other application that reads this database, which reaches it with a different identity and reads the org from its own token. One set of policies, two callers, no second definition to drift. ## Narrower than an org An API key can be restricted to a subset of its org's devices. That subset is applied by filtering the device rows at the entry point, before any surface sees them, so it narrows **visibility and addressing together**. The consequence is worth stating plainly: a device outside your key's subset is not refused, it is not found. There is no oracle telling you that a device exists but is out of reach. `get_device` reports it as not found, receipts for it report as not found, and it does not appear in `list_devices`. The same rule applies across the whole surface. The MCP tools, the REST run routes and the device channel all resolve devices through one directory built from the same visibility rules, so they cannot disagree about what a credential can see. ## Leases are org scoped A lease binds an org to a device. Acquiring a device that another org holds is refused, and so is acquiring one that belongs to another org at all, since a device's ownership is a property of the device's own record. Leases carry a fencing token, which is what makes a resumed or duplicated caller lose to the current holder rather than acting on stale authority. You never handle it: it is issued and checked inside the control plane, and it is deliberately withheld from anything running outside it. ## Stored objects are prefixed by org Any object the control plane stores for you is written under a prefix derived from your org id. Cross org read paths are not merely unauthorized, they are not expressible as a key. That is also why an org id is validated rather than trusted. Control characters, path separators and dot segments are rejected when the id is parsed, so a value that could escape a prefix cannot be constructed in the first place. ## The device boundary The control plane never speaks to hardware directly. It does not open a debug bridge, a serial port or a camera. A cloud phone is reached through the cloud phone platform's HTTPS API. That boundary exists for isolation, and it is also the seam along which a private deployment becomes possible: the part that reaches devices could one day run in your environment while the control plane stays where it is. That deployment shape is not built. What is guaranteed today is that the boundary is clean enough to keep it possible. ## Local mode Local mode is a single org on a single machine, on loopback, with no shared database. It resolves to a constant local org rather than to a mutable global, so the request pipeline has the same shape it has in a hosted deployment. Do not read local mode's convenience as a permission model. It grants every scope to whoever can reach the port, which is exactly why it refuses to bind anywhere but loopback. ## Related > [card] [Authentication](/mcp/auth) > > How a credential resolves to an org and a set of scopes. > [card] [Frame retention](/security/frame-retention) > > What happens to captured screens.