Take a screenshot
A PNG of the desktop, in the coordinate space resolution reports. This is the image to hand a model that is about to decide where to click.
IF YOU ARE DRIVING THE DESKTOP, PASS fresh=1. A bare call may serve a frame up to 1.5 seconds old — up to 30 seconds while the computer is busy with another operation — which is fast and fine for a thumbnail and wrong for a loop: a model reading a stale frame concludes its click missed and clicks again, which is how a dialog gets dismissed twice.
A suspended computer returns its saved desktop as a JPEG up to 640 pixels wide, with X-GC-Frame: suspended, including without w. A w (or format=jpeg) is accepted but ignored there: the saved frame comes back as it was stored, at its own width. This is a stored picture, not a live screen to drive. Suspend keeps that image locally on disk until the session is resumed or discarded; it is not uploaded or included in backups. Older sessions may have no saved frame; those answer 409 with reason: unavailable, and starting the computer brings back a live one.
An explicit fresh=1 (or fresh=true) request against a suspended computer answers 409 with reason: unavailable; start it before requesting a live frame. A concurrent lifecycle operation, or another operation holding the screen with no recent frame to serve, answers 409 with reason: contention; retry after that operation finishes. A stopped computer answers 409 with reason: unavailable, as exec and input do; start it before driving its desktop.
region, scale, format and quality shape the picture: a crop, a smaller image, and a cheaper encoding, applied in that order to the same capture a bare call would return. A cropped or scaled image is in its OWN pixel space: to click on something in it, divide its position by the scale and add the region’s x and y. A suspended computer answers a crop, a scale, format=png or quality with 409 and reason: unavailable, because its saved picture is not the screen.
Every live answer names the capture it was cut from in X-GC-Capture, and gives that capture’s own size in X-GC-Capture-Size (for example 3840x2160) — the pixels region is read in, which is usually resolution but not always: a desktop resumed from a capture taken at another size, or resized from inside the guest, can differ. TO CUT A CROP FROM THE CAPTURE YOU MEASURED, send its name back as capture: the answer comes from that capture and no other, and takes no new one. Only the newest capture of a computer is held, so the next one replaces it — an ordinary call 1.5 seconds later at the earliest, a fresh=1 call at once. It is also lost when the daemon on its host restarts or the computer moves to another host. A name that is no longer held answers 409 with reason: stale_capture rather than a crop of a different picture. Take a new screenshot and use the name it carries. Measuring on a small w thumbnail and then cropping by capture costs two small requests, where measuring on the whole PNG costs the screen’s full size. A suspended computer has no capture: its saved picture carries neither header, and capture on it answers 409 with reason: unavailable.
A query parameter not listed here, or one given twice, answers 400 naming the parameters this route takes, as does a value it cannot read.
Requires the viewer role or higher.
Request
- Base URL: https://app.mandala.computer/api/v1
- URL: https://app.mandala.computer/api/v1/computers/{id}/screenshot
- Auth: HTTP bearer
Path parameters
The computer id.
Query parameters
Skip the cache and capture now: 1 or true. 0 or false is the same as leaving it out. Pass this whenever the screenshot is feeding a decision.
Answer from the capture an earlier screenshot named in X-GC-Capture, rather than from the screen now, so a crop can be worked out on one answer and cut from the same pixels by the next. A capture that is no longer held answers 409 with reason: stale_capture. Not with fresh, which asks for a capture taken after the request.
Downscale to this width and answer JPEG instead of PNG unless format says otherwise. For thumbnails. A positive whole number: 0, a negative number or anything else is a 400. A width below 64 is raised to 64, and one wider than what is being shrunk — the screen, or the region — is lowered to its width, so the picture is never enlarged. Not with scale. On a suspended computer it is accepted and ignored: the saved frame (up to 640 pixels wide) comes back unchanged.
Downscale by this factor, greater than 0 and at most 1, keeping the encoding PNG unless format says otherwise. 0.5 halves both sides, which is a quarter of the pixels a model is sent. Not with w.
Crop to x,y,width,height, in the capture’s own pixels — the size X-GC-Capture-Size reports, which is ordinarily resolution — before any scaling. The region has to lie inside the capture: one that reaches past an edge answers 400 naming its size, rather than being clipped to a smaller picture than you asked for. With capture, it is cut from that capture.
The encoding. PNG by default, JPEG by default with w.
JPEG quality, 1 to 100; 72 when not given. With a PNG answer it is a 400.
Response
The current screen, or the region of it asked for, as PNG — or JPEG with w or format=jpeg. A live answer carries X-GC-Capture (the capture it was cut from, to send back as capture) and X-GC-Capture-Size (that capture’s width x height in pixels). Suspended sessions return a saved JPEG marked X-GC-Frame: suspended, with neither.
Changes
No recorded changes to this operation across all 1 revision of this API.