A valid request URL is required to generate request examples{
"deviceId": "<string>",
"backendKind": "adb_cloud",
"kind": "emulator",
"status": "online",
"capabilities": {
"fidelityTier": "software",
"actions": {
"tap": true,
"swipe": true,
"typeText": "native",
"pressKey": [
"home"
],
"openApp": "intent",
"installApp": "apk",
"longPress": true,
"wake": true,
"stop": true
},
"observations": {
"screenshot": "framebuffer",
"uiTree": "uiautomator",
"framesAreReferenceable": true,
"freshnessMs": 123,
"stream": "webrtc"
},
"os": "android",
"coordSpace": {
"width": 123,
"height": 123
}
},
"metadata": {},
"displayName": "<string>",
"info": {
"model": "<string>",
"androidVersion": "<string>",
"osVersion": "<string>",
"resolution": {
"width": 123,
"height": 123
},
"carrier": "<string>"
},
"staffHold": {
"reason": "leased",
"retryable": true,
"hint": "<string>"
},
"holdsUnknown": true
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "payload_too_large",
"message": "<string>"
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}Rename a device
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.
A valid request URL is required to generate request examples{
"deviceId": "<string>",
"backendKind": "adb_cloud",
"kind": "emulator",
"status": "online",
"capabilities": {
"fidelityTier": "software",
"actions": {
"tap": true,
"swipe": true,
"typeText": "native",
"pressKey": [
"home"
],
"openApp": "intent",
"installApp": "apk",
"longPress": true,
"wake": true,
"stop": true
},
"observations": {
"screenshot": "framebuffer",
"uiTree": "uiautomator",
"framesAreReferenceable": true,
"freshnessMs": 123,
"stream": "webrtc"
},
"os": "android",
"coordSpace": {
"width": 123,
"height": 123
}
},
"metadata": {},
"displayName": "<string>",
"info": {
"model": "<string>",
"androidVersion": "<string>",
"osVersion": "<string>",
"resolution": {
"width": 123,
"height": 123
},
"carrier": "<string>"
},
"staffHold": {
"reason": "leased",
"retryable": true,
"hint": "<string>"
},
"holdsUnknown": true
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "payload_too_large",
"message": "<string>"
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}Authorizations
The control surface credential. Send Authorization: Bearer <token>.
Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.
Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.
Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.
Path Parameters
The deviceId from a listing.
Body
The new label.
What to call this device. Any text you can read, up to the length below.
1 - 120Response
The device, renamed.
One device, as DeviceSummary, plus holdsUnknown when its staff hold could not be read. The same shape the get_device tool returns.
The id every other endpoint addresses this device by.
How this device is reached.
adb_cloud, adb_real, emulator, robot_hand, esp32_hid, byod_portal What this device IS, in the words a person uses: an emulator, a cloud_phone in somebody's rack, a physical handset, or one driven by a robot arm. backendKind beside it names the TRANSPORT instead, which is the right key for picking an adapter and the wrong word for a label: adb_real and adb_cloud are one sentence to an operator and two different objects to a customer. Derive nothing from backendKind that this field already answers.
THESE ARE NOT THE PURCHASABLE TIERS. What an organisation can buy is a separate, shorter list; the words overlap and the sets do not.
emulator, cloud_phone, physical, robot Whether the control plane can currently REACH the device. online does not mean you can drive it: an online device may be held right now by an unexpired lease, or by our staff (then it carries staffHold), and a device your org owns that discovery cannot see is offline rather than missing.
online, offline, unauthorized, unknown What THIS device can do, which is always a subset of what its backend kind can do. Consult it before acting: backends differ, and a robot hand has camera frames but no UI tree.
- Option 1
- Option 2
- Option 3
Show child attributes
Show child attributes
Backend defined detail, echoed as the backend reported it. Its keys are not part of this contract.
What you have chosen to call this device, set through PATCH /v1/devices/{deviceId}. ABSENT when nobody has named it, which is not the same as an empty name: show deviceId in its place. Nothing in the control plane reads it, and it never addresses the device.
WHAT THE PHONE SAYS IT IS, rather than what the control plane knows about it (D126): the facts a person reads off Settings → About.
READ ONCE AND CACHED. It is filled THE FIRST TIME THE DEVICE IS ACQUIRED, and retried on each later acquire while it is still missing; nothing probes the device to answer a listing, because a per-device round trip on GET /v1/devices would be paid by every caller for a field most do not read. A reading can therefore appear on a device that had none a moment ago, and the acquire response that triggered it may still not carry it.
THE ABSENCES ARE THREE DIFFERENT ANSWERS and collapsing them will report a phone wrong. info itself absent: nobody has ever asked this device. Render Not reported yet, never a blank model. A FIELD absent: it was asked and did not answer for that one. carrier: null: asked, answered, and the answer is that it has no operator.
Which fields arrive depends on the transport, not on the phone. A cloud phone reached over the provider's HTTPS API has no route that returns a shell command's output, so resolution, which is a wm size call and not a system property, is absent there today even though the screen plainly has one. A robot-driven phone is read by the rig next to it: model, osVersion and, on Android, androidVersion and resolution. An iPhone on a rig reports no resolution, and no robot-driven phone reports carrier.
Show child attributes
Show child attributes
OUR STAFF HOLD THIS DEVICE right now: a calibration, maintenance, an on site check. Present only while the hold lasts, and only on a robot arm. Also absent when holdsUnknown is true: then we could not check, and absent means not known.
It is the refusal you would get, shown before you ask: a lease request (POST /v1/devices/{deviceId}/lease, acquire_device) or a renewal is refused 409 device_unavailable with exactly this reason, retryable and hint. Pick another device, or wait and list again when retryable is true.
It is NOT availability. A device another customer is using shows no hold, and status stays reachability.
Show child attributes
Show child attributes
Present, and true, only on a robot arm whose staff hold we could not check just now. The device reads as normal, but no staffHold then means not known rather than not held. Absent on every other device, since nothing else can be held. A lease request still refuses a held device, so the cost of acting on this reading is a refusal, never a lease or a charge.