Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

9.7 KB
Raw Blame

Tabs

Tabs are the main execution surface for browsing, extraction, interaction, and diagnostics.

Use tab-scoped HTTP routes once you already have a tab ID. In the CLI, use the normal top-level browser commands with --tab <id>.

pinchtab tab itself is only for:

  • listing tabs
  • focusing a tab
  • closing a tab
  • human handoff (handoff, handoff-status, resume)

Open a new tab with pinchtab nav <url> --new-tab. There are no subcommands such as pinchtab tab navigate or pinchtab tab click.

Top-Level Browser Commands

These pages cover the shorthand routes and matching CLI commands:

Open A Tab In A Specific Instance

curl -X POST http://localhost:9867/instances/inst_ea2e747f/tabs/open \
  -H "Content-Type: application/json" \
  -d '{"url":"https://pinchtab.com"}'
# Response
{
  "tabId": "8f9c7d4e1234567890abcdef12345678",
  "url": "https://pinchtab.com",
  "title": "PinchTab"
}

There is still no dedicated instance-scoped tab-open CLI command. The CLI shortcut is:

pinchtab instance navigate inst_ea2e747f https://pinchtab.com

That command opens a tab for the instance already on the URL, in one tabs/open call.

List Tabs

Active Bridge Or Shorthand Context

curl http://localhost:9867/tabs
# Response (API always returns JSON)
{
  "tabs": [
    {
      "id": "8f9c7d4e1234567890abcdef12345678",
      "url": "https://pinchtab.com",
      "title": "PinchTab",
      "type": "page",
      "status": "active"
    }
  ]
}

# CLI Alternative (human-readable by default)
pinchtab tab
# Output: *8f9c7d4e...  https://pinchtab.com  PinchTab

pinchtab tab --json                    # Full JSON response

Notes:

  • GET /tabs is not a fleet-wide inventory
  • in bridge mode or shorthand mode it lists tabs from the active browser context
  • pinchtab tab follows that shorthand behavior
  • the current tab is listed first
  • tabs on about:blank, chrome://, chrome-extension://, devtools://, file:// or the server's own port are not listed
  • status is active, or paused_handoff with handoffReason and pausedAt; a locked tab also carries owner and lockedUntil, and browserContextId appears when the tab has one

Tabs For One Instance

curl http://localhost:9867/instances/inst_ea2e747f/tabs

Tabs Across All Running Instances

curl http://localhost:9867/instances/tabs

Use GET /instances/tabs when you need the orchestrator-wide view.

Both instance routes return a bare JSON array of {"id","instanceId","url","title"} objects. Results are cached per instance; add ?fresh=1 to refetch.

Focus And Close From The CLI

pinchtab tab                           # list tabs
pinchtab tab 2                         # focus tab by 1-based index
pinchtab tab 8f9c7d4e1234...           # focus tab by tab ID
pinchtab nav https://pinchtab.com --new-tab  # open a new tab and navigate it
pinchtab tab close 8f9c7d4e1234...     # close tab

Numeric arguments are resolved as 1-based indices against GET /tabs. Non-numeric arguments are treated as tab IDs.

Focusing, navigating, or otherwise accessing a tracked tab marks it as the current tab. Unscoped commands use that current tab; if the recorded current tab has gone stale, PinchTab falls back to the most recently used tracked tab.

Top-level navigation uses the current tab when one is available. Use pinchtab nav <url> --new-tab when you explicitly want another tab.

Operate On An Existing Tab

Use the tab-scoped HTTP route or the top-level CLI command with --tab.

Navigate

curl -X POST http://localhost:9867/tabs/<tabId>/navigate \
  -H "Content-Type: application/json" \
  -d '{"url":"https://pinchtab.com"}'
# CLI Alternative
pinchtab nav https://pinchtab.com --tab <tabId>

Snapshot

curl "http://localhost:9867/tabs/<tabId>/snapshot?filter=interactive&format=compact"
# CLI Alternative
pinchtab snap --tab <tabId> -i -c

Text

curl "http://localhost:9867/tabs/<tabId>/text?mode=raw"
# CLI Alternative
pinchtab text --tab <tabId> --raw

Find

curl -X POST http://localhost:9867/tabs/<tabId>/find \
  -H "Content-Type: application/json" \
  -d '{"query":"login button"}'
# CLI Alternative
pinchtab find --tab <tabId> "login button"

Actions

curl -X POST http://localhost:9867/tabs/<tabId>/action \
  -H "Content-Type: application/json" \
  -d '{"kind":"click","ref":"e5"}'
# CLI Alternatives
pinchtab click --tab <tabId> e5
pinchtab fill --tab <tabId> '#email' '[email protected]'
pinchtab wait --tab <tabId> 'text:Done'
pinchtab network --tab <tabId> --limit 20

Low-level pointer control uses the same action surface:

curl -X POST http://localhost:9867/tabs/<tabId>/action \
  -H "Content-Type: application/json" \
  -d '{"kind":"mouse-move","ref":"e5"}'

curl -X POST http://localhost:9867/tabs/<tabId>/action \
  -H "Content-Type: application/json" \
  -d '{"kind":"mouse-down","button":"left"}'

curl -X POST http://localhost:9867/tabs/<tabId>/action \
  -H "Content-Type: application/json" \
  -d '{"kind":"mouse-wheel","x":400,"y":320,"deltaY":240}'

# CLI Alternatives
pinchtab mouse move --tab <tabId> e5
pinchtab mouse down --tab <tabId> --button left
pinchtab mouse wheel --tab <tabId> 240 --dx 40

Handoff State

Human handoff is tab-scoped and available through CLI or API.

pinchtab tab handoff <tabId> --reason captcha --timeout-ms 120000
pinchtab tab handoff-status <tabId>
pinchtab tab resume <tabId> --status completed

API equivalents:

When a tab is marked paused_handoff, action execution routes reject with 409 tab_paused_handoff until the tab is resumed or the optional timeout expires.

curl -X POST http://localhost:9867/tabs/<tabId>/handoff \
  -H "Content-Type: application/json" \
  -d '{"reason":"captcha","timeoutMs":120000}'

curl http://localhost:9867/tabs/<tabId>/handoff

curl -X POST http://localhost:9867/tabs/<tabId>/resume \
  -H "Content-Type: application/json" \
  -d '{"status":"completed","resolvedData":{"operator":"human"}}'

Use this when automation must pause for a CAPTCHA, 2FA prompt, login approval, or another human-only step. When a timeout is provided, handoff status includes expiresAt and timeoutMs.

Screenshot

curl "http://localhost:9867/tabs/<tabId>/screenshot?raw=true" > out.jpg
# CLI Alternative
pinchtab screenshot --tab <tabId> -o out.jpg

PDF

curl "http://localhost:9867/tabs/<tabId>/pdf?raw=true" > page.pdf
# CLI Alternative
pinchtab pdf --tab <tabId> -o page.pdf

Cookies

curl http://localhost:9867/tabs/<tabId>/cookies
curl -X POST http://localhost:9867/tabs/<tabId>/cookies \
  -H "Content-Type: application/json" \
  -d '{"cookies":[{"name":"session","value":"abc"}]}'

POST defaults url to the tab's current page, so injecting a session cookie needs no URL lookup. A cookie with an empty value is set (blanking it without deleting it); a cookie with no name is rejected with 400 rather than skipped. DELETE /tabs/<tabId>/cookies is tab-scoped in addressing only — it clears every cookie for every origin, exactly like DELETE /cookies.

The same operations from the CLI:

pinchtab cookies get --tab <tabId>                  # read cookies, with values
pinchtab cookies get --tab <tabId> --name session   # one cookie
pinchtab cookies set session abc123 --tab <tabId>   # set on the tab's current URL
pinchtab cookies clear                              # every cookie, every origin

cookies set takes --url, --domain, --path, --same-site, --secure and --http-only; it exits non-zero if the server reports the cookie was not set. There is no per-cookie removal verb — clear is browser-wide, and nothing in the CLI restores what it wipes, so re-set what you need or use state load.

Reading, writing, and clearing cookies requires security.allowCookies=true.

Metrics

curl http://localhost:9867/tabs/<tabId>/metrics

This reports the owning browser instance's aggregate memory — the whole process tree — not an isolated per-tab reading: the tab id picks the instance to ask. Two tabs of one instance return the same figures. See Memory monitoring.

Lock And Unlock

Tab locking is API-only.

curl -X POST http://localhost:9867/tabs/<tabId>/lock \
  -H "Content-Type: application/json" \
  -d '{"owner":"my-agent","timeoutSec":60}'

curl -X POST http://localhost:9867/tabs/<tabId>/unlock \
  -H "Content-Type: application/json" \
  -d '{"owner":"my-agent"}'

owner is required. timeoutSec is optional and defaults to 10 minutes. Lock answers {"locked":true,"owner":"...","expiresAt":"..."}, unlock answers {"unlocked":true}, and a conflicting owner gets 409.

There are also root forms at POST /lock and POST /unlock; they take the tab in the body as tabId (required).

Important Limits

  • There is no GET /tabs/{id} endpoint. GET /tabs/{id}/state reports one tab's tabId, url, title, dialogPresent/dialog, load (readyState, navigationInProgress, networkIdle, state) and actionability.
  • GET /tabs and GET /instances/tabs serve different purposes and are not interchangeable.
  • In the CLI, tab-scoped work happens through top-level commands with --tab, not through pinchtab tab <subcommand> variants — except for handoff, resume, and handoff-status, which are exposed both as top-level commands and as pinchtab tab handoff|resume|handoff-status subcommands.