Find

/find lets PinchTab locate elements by natural-language description instead of CSS selectors or XPath.

It works against the accessibility snapshot for a tab and returns the best matching ref, which you can pass to /action.

Endpoints

PinchTab exposes two forms:

• POST /find
• POST /tabs/{id}/find

Use POST /find when you are talking directly to a bridge-style runtime or shorthand route and want to pass tabId in the request body.

Use POST /tabs/{id}/find when you already know the tab ID and want the orchestrator to route the request to the correct instance.

Request Body

Main Example

pinchtab find --tab <tabId> "login button"

curl -X POST http://localhost:9867/tabs/<tabId>/find \  -H "Content-Type: application/json" \  -d '{"query":"login button","threshold":0.3,"topK":3}'

There is a dedicated CLI find command:

pinchtab find "login button"pinchtab find --threshold 0.5 --explain "primary submit button"pinchtab find --ref-only "search input"

pinchtab find "login button"pinchtab find --threshold 0.5 --explain "primary submit button"pinchtab find --ref-only "search input"

Using POST /find

curl -X POST http://localhost:9867/find \  -H "Content-Type: application/json" \  -d '{"tabId":"<tabId>","query":"search input"}'

curl -X POST http://localhost:9867/find \  -H "Content-Type: application/json" \  -d '{"tabId":"<tabId>","query":"search input"}'

If tabId is omitted, PinchTab uses the active tab in the current bridge context.

Response Fields

When explain is enabled, each match may also include lexical and embedding score details.

Query Syntax

Beyond plain natural-language descriptions, the matcher understands three query modifiers:

Ordinal Queries

Use ordinal words to pick a position from otherwise similar matches:

pinchtab find "first button"pinchtab find "second search result"pinchtab find "last link"

pinchtab find "first button"pinchtab find "second search result"pinchtab find "last link"

Ordinal matching is applied after semantic scoring. When the snapshot has no coordinates, document order is used as the stable order.

Negative Queries

Use not, without, exclude, excluding, except, no, or ignore to push elements away from the match:

# Picks Cancel over Submitpinchtab find "button not submit"# Compose multiple exclusionspinchtab find "input no password no username"# Exclude a phrasepinchtab find "button without sign in"

# Picks Cancel over Submitpinchtab find "button not submit"# Compose multiple exclusionspinchtab find "input no password no username"# Exclude a phrasepinchtab find "button without sign in"

Tokens before the trigger are positive; everything after is negative until the next trigger or end of query.

Visual / Location Queries

Directional and relative phrases bias the match toward elements at the matching position on the page:

# Directional (top / bottom / left / right / corner)pinchtab find "bottom button"pinchtab find "button in top right corner"pinchtab find "sidebar on the left"# Anchor-relative (above / below / under / over)pinchtab find "link below the search box"pinchtab find "button above the footer"

# Directional (top / bottom / left / right / corner)pinchtab find "bottom button"pinchtab find "button in top right corner"pinchtab find "sidebar on the left"# Anchor-relative (above / below / under / over)pinchtab find "link below the search box"pinchtab find "button above the footer"

When the accessibility snapshot has no coordinates, document order is used as a fallback for vertical position — so "bottom button" selects the last matching button in the snapshot. When element bounding boxes are available they take precedence.

Visual hints are applied by the combined matcher (the default). They do not affect the lexical-only matcher.

Confidence Levels

Common Flow

The standard pattern is:

navigate -> find -> action

Example:

curl -X POST http://localhost:9867/tabs/<tabId>/find \  -H "Content-Type: application/json" \  -d '{"query":"username input"}'

curl -X POST http://localhost:9867/tabs/<tabId>/find \  -H "Content-Type: application/json" \  -d '{"query":"username input"}'

Then use the returned ref:

curl -X POST http://localhost:9867/tabs/<tabId>/action \  -H "Content-Type: application/json" \  -d '{"ref":"e14","kind":"type","text":"user@pinchtab.com"}'

curl -X POST http://localhost:9867/tabs/<tabId>/action \  -H "Content-Type: application/json" \  -d '{"ref":"e14","kind":"type","text":"user@pinchtab.com"}'

Operational Notes

• /find uses the tab’s accessibility snapshot, not raw DOM selectors.
• Structured /find queries such as role:button Save, text:Submit, label:Email, placeholder:Search, alt:Logo, title:Close, testid:submit, first:role:button, last:text:Submit, and nth:2:label:Email are matched by the semantic engine against enriched descriptors.
• In action commands, role:, label:, placeholder:, alt:, title:, testid:, and wrappers around those forms use semantic matching. CSS, XPath, refs, the existing text: action selector, and bare CSS/text wrappers such as first:button remain browser-side selector resolution.
• If there is no cached snapshot, PinchTab tries to refresh it automatically before matching.
• Successful matches are useful inputs to /action, /actions, and higher-level recovery logic.
• A 200 response can still return an empty best_ref if nothing met the threshold.

Error Cases