POST /ui/observe
Capture structured elements using JSON options.
This is a device HTTP route. Set DEVICE_URL to your reachable device URL; connection and examples explain how. Do not append this path to the public MCP URL.
Parameters
| Parameter | Type | Meaning |
|---|---|---|
bundleId | JSON string | Optional; must be foreground if provided; otherwise current foreground app. |
limit | JSON number | 1..1000; default 300. |
includeContainers | JSON boolean | Default false. |
includeHidden | JSON boolean | Default false. |
screenshot | JSON boolean | Default false; true includes screenshotURL for a cached PNG. |
Response
Observation JSON: schemaVersion,backend,observationId,bundleId,pid,processSessionId,timestamp,captureDurationMs,expiresInSeconds,screen,elements and traversal coverage. Each element includes ref, attributes, rect, actions and selector suggestions.
Example
curl --fail-with-body "$DEVICE_URL/ui/observe" \
-H 'Content-Type: application/json' \
-d '{"limit":100,"screenshot":true}'Notes
Close the inspector before requesting a screenshot. Capture is not atomic: check timestamps. References belong to this observation and process, last at most 60 seconds, and may be evicted earlier. Refresh after navigation. screen uses nativePixels. See the HTTP workflow guide for all observation fields.
Check the HTTP status and any JSON error. HTTP workflows and error handling explain shared limits. All endpoints.