High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
Extract
/extract reads typed values off the current page against a JSON schema: a price comes
back as a JSON number, a checkbox as a boolean, a product grid as an array of objects. It
works against the tab's accessibility snapshot, so every field also carries the ref it
was read from, usable with /action straight away.
Endpoints
PinchTab exposes two forms:
POST /extractPOST /tabs/{id}/extract
Use POST /extract with tabId in the body (or none, for the active tab). Use
POST /tabs/{id}/extract when you already know the tab ID and want the orchestrator to
route the request to the instance that owns it.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
schema |
object or string | yes | - | JSON schema describing the data; see Schema Subset |
tabId |
string | no | active tab | Tab ID when using POST /extract |
scope |
string | no | whole page | Confine every field to the subtree of one element: a bare ref (e12), role:, text: or a plain query. CSS and XPath are refused (400) |
threshold |
float | no | 0.3 |
Minimum match score per field |
maxItems |
int | no | 100 |
Cap on items per array |
Main Example
Save the schema as product.schema.json:
{
"type": "object",
"required": ["name", "price", "inStock"],
"properties": {
"name": {"type": "string", "description": "product name", "x-pinchtab-hint": "role:heading"},
"price": {"type": "number", "description": "product price"},
"rating": {"type": "number", "description": "product rating out of 5"},
"inStock": {"type": "boolean", "description": "in stock availability", "x-pinchtab-hint": "role:checkbox"}
}
}
curl -X POST http://localhost:9867/extract \
-H "Content-Type: application/json" \
-d "{\"schema\":$(cat product.schema.json)}"
# CLI Alternative
pinchtab extract --schema product.schema.json
On a product page the CLI prints the data alone:
{
"inStock": true,
"name": "Sony WH-1000XM5 Wireless Headphones",
"price": 1299,
"rating": 4.7
}
CLI
pinchtab extract --schema product.schema.json
cat product.schema.json | pinchtab extract --schema -
pinchtab extract --schema product.schema.json --fields
pinchtab extract --schema products.schema.json --max-items 2
pinchtab extract --schema amounts.schema.json --scope role:table
| Flag | Description |
|---|---|
--schema <file|-> |
Schema file, or - to read it from stdin (required) |
--scope <selector> |
Sent as scope |
--max-items <n> |
Sent as maxItems |
--fields |
After the data, print one field<TAB>ref<TAB>confidence row per field; array items appear as products[0] and products[0].name |
--explain |
The same table with score, source and reason columns |
--json |
Print the full response envelope instead of data |
--tab <id> |
Target a tab through POST /tabs/{id}/extract |
Missing required fields and a truncated array are reported on stderr; the command still
exits 0, because the page answered. A schema the server refuses exits non-zero with the
server's 400 message, which names the offending path.
The CLI keeps the vocabulary the extract minted, so a field's ref can be clicked next without a snapshot in between:
pinchtab extract --schema product.schema.json --fields
pinchtab click e7
Response Fields
| Field | Description |
|---|---|
data |
Values coerced to the schema types; arrays hold one object per repeated group |
fields |
Per property: ref, score, confidence (high, medium, low), source (value, text, name, checked, hint) and reason when it did not resolve; arrays add items (each with its own ref and fields) and truncated |
missing |
Required properties that did not resolve |
truncated |
true when any array hit its item cap |
vocabularyToken |
The ref vocabulary the returned refs belong to (also in X-PinchTab-Vocab) |
latency_ms |
Resolution time in milliseconds |
element_count |
Number of snapshot nodes considered |
idpiWarning |
Advisory warning when IDPI is in warn mode |
Schema Subset
- The root is an object with
properties;requiredlists the fields reported inmissing. - A property is
string,number,integerorboolean, or anarraywhoseitemsis an object of such properties. Nested objects and arrays inside array items are refused. - The matcher searches for the property name plus its
description, so a descriptivedescription("product price") matters more than the key. maxItemsandminItemsbound an array; an array belowminItemsdoes not resolve.- An unsupported construct is a
400naming the path, for exampleproperties.price.type: object is not supported.
Hints And Scope
x-pinchtab-hinton a property pins where it is read from: a ref (e12), or arole:,text:or other semantic selector. Add one when a field comes backlow.x-pinchtab-scopeon an array pins its container, for examplerole:table, when the page has more than one repeated group.- The request-level
scopeconfines the whole schema to one subtree; a scope that matches nothing leaves every field unresolved with reasonscope_not_found.
When To Use It
extractfor typed values you would otherwise parse out of a snapshot: prices, flags, table rows, search results.findfor one element to act on.text --markdownfor prose to read.
Error Cases
| Status | Condition |
|---|---|
400 |
invalid JSON, missing schema, or an unsupported schema or scope (the message names the path) |
403 |
blocked by IDPI in strict mode |
404 |
tab not found |
409 |
dialog_blocked: a JavaScript dialog is blocking the tab (answer it with pinchtab dialog) |
500 |
Chrome not initialized, snapshot unavailable, or the snapshot has no elements |