A valid request URL is required to generate request examples{
"devices": [
{
"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": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}List the devices you can see
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.
A valid request URL is required to generate request examples{
"devices": [
{
"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": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"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.
Response
The devices this credential can see.
Every device this credential can see, in any status.
Show child attributes
Show child attributes
Present, and true, only when we could not check which devices our staff hold just now. The devices are listed as normal, but no staffHold on any of them then means not known rather than not held. Absent when the check ran, and when nothing listed can be held (only a robot arm can). 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.