POST /ui/query

Check live selector matches and uniqueness.

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 foreground app identifier.
`selector`	JSON object	Required UIHelper selector. String shorthand is not accepted over HTTP.

Response

JSON query result with backend,bundleId,count,unique and match summaries (up to 50).

Example

curl --fail-with-body "$DEVICE_URL/ui/query" \
  -H 'Content-Type: application/json' \
  -d '{"selector":{"type":"Button","label":"Continue","visible":true}}'

Notes

The example label must be adapted to the app/language. A query does not supply an actionable observation ref; obtain that through /ui/observe. Confirm uniqueness before choosing an element.

Check the HTTP status and any JSON error. HTTP workflows and error handling explain shared limits. All endpoints.

# POST /ui/query

Check live selector matches and uniqueness.

This is a device HTTP route. Set `DEVICE_URL` to your reachable device URL; [connection and examples](https://mcp.applesauceos.com/doc/http.md) explain how. Do not append this path to the public MCP URL.

## Parameters

| Parameter | Type | Meaning |
| --- | --- | --- |
| `bundleId` | JSON string | Optional foreground app identifier. |
| `selector` | JSON object | Required UIHelper selector. String shorthand is not accepted over HTTP. |

## Response

JSON query result with backend,bundleId,count,unique and match summaries (up to 50).

## Example

```sh
curl --fail-with-body "$DEVICE_URL/ui/query" \
  -H 'Content-Type: application/json' \
  -d '{"selector":{"type":"Button","label":"Continue","visible":true}}'
```

## Notes

The example label must be adapted to the app/language. A query does not supply an actionable observation ref; obtain that through /ui/observe. Confirm uniqueness before choosing an element.

Check the HTTP status and any JSON error. [HTTP workflows and error handling](https://mcp.applesauceos.com/doc/http-guide.md) explain shared limits. [All endpoints](https://mcp.applesauceos.com/doc/http.md).