Schema
Envelope Format
The top-level CUP JSON envelope structure.
Overview
The CUP envelope is the root JSON object returned by snapshot_raw(). It contains metadata about the capture and the UI tree.
Structure
{
"version": "0.1.0",
"platform": "windows",
"timestamp": 1740067200000,
"screen": {
"w": 2560,
"h": 1440,
"scale": 1.0
},
"scope": "foreground",
"app": {
"name": "Spotify",
"pid": 1234
},
"tree": [ ... ],
"windows": [ ... ]
}Fields
| Field | Type | Description |
|---|---|---|
version | string | Schema version (semver) |
platform | enum | Source platform: windows, macos, linux, web, android, ios |
timestamp | integer | Unix epoch in milliseconds |
screen.w | integer | Screen width in pixels |
screen.h | integer | Screen height in pixels |
screen.scale | number | Display scale factor (default 1.0) |
scope | enum | Capture scope: overview, foreground, desktop, full |
app.name | string | Focused application name |
app.pid | integer | Process ID |
app.bundleId | string? | macOS/iOS bundle ID or Android package name |
tree | array | Root-level UI nodes |
windows | array | Window list with metadata |
tools | array? | WebMCP tools (web platform only) |
Window list
The windows array provides metadata about open windows:
{
"windows": [
{
"title": "Spotify",
"pid": 1234,
"focused": true,
"bounds": { "x": 120, "y": 40, "w": 1680, "h": 1020 }
},
{
"title": "Terminal",
"pid": 5678,
"focused": false,
"bounds": { "x": 0, "y": 0, "w": 800, "h": 600 }
}
]
}