A valid request URL is required to generate request examples{
"accepted": 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": "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
}
}Wake a device's screen
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.
A valid request URL is required to generate request examples{
"accepted": 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": "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.
Response
Accepted: the wake was asked for. Best-effort, so this says the request reached the device rather than that the screen is on.
Always true; a 202 is the only success answer here.