A valid request URL is required to generate request examples{
"refreshAfterMs": 1,
"thumbnails": [
{
"deviceId": "<string>",
"state": "ready",
"version": "<string>",
"capturedAt": "2023-11-07T05:31:56Z",
"width": 2,
"height": 2,
"image": "<string>"
}
]
}{
"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": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}Small pictures of several devices' screens
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.
A valid request URL is required to generate request examples{
"refreshAfterMs": 1,
"thumbnails": [
{
"deviceId": "<string>",
"state": "ready",
"version": "<string>",
"capturedAt": "2023-11-07T05:31:56Z",
"width": 2,
"height": 2,
"image": "<string>"
}
]
}{
"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": "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_ or puk_ 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.