File size: 4,295 Bytes
6a7089a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 | # 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 currently exposes two useful 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
| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `query` | string | yes | - | Natural-language description of the target element |
| `tabId` | string | no | active tab | Tab ID when using `POST /find` |
| `threshold` | float | no | `0.3` | Minimum similarity score |
| `topK` | int | no | `3` | Maximum number of matches to return |
| `lexicalWeight` | float | no | matcher default | Override lexical score weight |
| `embeddingWeight` | float | no | matcher default | Override embedding score weight |
| `explain` | bool | no | `false` | Include per-match score breakdown |
## Main Example
```bash
curl -X POST http://localhost:9867/tabs/<tabId>/find \
-H "Content-Type: application/json" \
-d '{"query":"login button","threshold":0.3,"topK":3}'
# Response
{
"best_ref": "e5",
"confidence": "high",
"score": 0.85,
"matches": [
{
"ref": "e5",
"score": 0.85,
"role": "button",
"name": "Log in"
}
],
"strategy": "combined:lexical+embedding:hashing",
"threshold": 0.3,
"latency_ms": 2,
"element_count": 42
}
```
There is no dedicated CLI `find` command at the moment.
## Using `POST /find`
```bash
curl -X POST http://localhost:9867/find \
-H "Content-Type: application/json" \
-d '{"tabId":"<tabId>","query":"search input"}'
# Response
{
"best_ref": "e7",
"confidence": "high",
"score": 0.91,
"matches": [
{
"ref": "e7",
"score": 0.91,
"role": "textbox",
"name": "Search"
}
],
"strategy": "combined:lexical+embedding:hashing",
"threshold": 0.3,
"latency_ms": 18,
"element_count": 142
}
```
If `tabId` is omitted, PinchTab uses the active tab in the current bridge context.
## Response Fields
| Field | Description |
| --- | --- |
| `best_ref` | Highest-scoring element reference to use with `/action` |
| `confidence` | `high`, `medium`, or `low` |
| `score` | Score of the best match |
| `matches` | Top matches above threshold |
| `strategy` | Matching strategy used |
| `threshold` | Threshold used for the request |
| `latency_ms` | Matching time in milliseconds |
| `element_count` | Number of elements evaluated |
When `explain` is enabled, each match may also include:
- `lexical_score`
- `embedding_score`
- `composite`
## Confidence Levels
| Level | Score Range | Meaning |
| --- | --- | --- |
| `high` | `>= 0.80` | Usually safe to act on directly |
| `medium` | `0.60 - 0.79` | Reasonable match, but verify for critical actions |
| `low` | `< 0.60` | Weak match; rephrase the query or lower the threshold carefully |
## Common Flow
The standard pattern is:
```text
navigate -> find -> action
```
Example:
```bash
curl -X POST http://localhost:9867/tabs/<tabId>/find \
-H "Content-Type: application/json" \
-d '{"query":"username input"}'
# Response
{
"best_ref": "e14",
"confidence": "high",
"score": 0.85
}
```
Then use the returned ref:
```bash
curl -X POST http://localhost:9867/tabs/<tabId>/action \
-H "Content-Type: application/json" \
-d '{"ref":"e14","kind":"type","text":"user@example.com"}'
```
## Operational Notes
- `/find` uses the tab's accessibility snapshot, not raw DOM selectors.
- 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
| Status | Condition |
| --- | --- |
| `400` | invalid JSON or missing `query` |
| `404` | tab not found |
| `500` | Chrome not initialized, snapshot unavailable, or matcher failure |
|