Tabs

Tabs are the main execution surface for browsing, extracting, and interacting with pages.

Use tab-scoped routes once you already have a tab ID. Use instance-scoped routes when you need to create a new tab in a specific instance.

Tab IDs should be treated as opaque values returned by the API. Do not construct them yourself or assume one stable format across all routes.

Shorthand Browser Commands

Top-level browser commands such as nav, snap, text, click, type, fill, pdf, ss, eval, and health now have their own quick reference pages.

Use those pages when you want the shorthand route plus the matching CLI command:

Open A Tab In A Specific Instance

terminal 
curl -X POST http://localhost:9867/instances/inst_ea2e747f/tabs/open \  -H "Content-Type: application/json" \  -d '{"url":"https://pinchtab.com"}'
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 no dedicated instance-scoped tab open CLI command today.

If you want a CLI shortcut that opens a tab and navigates it, use:

terminal 
pinchtab instance navigate inst_ea2e747f https://pinchtab.com
pinchtab instance navigate inst_ea2e747f https://pinchtab.com

List Tabs

Shorthand Or Bridge List

terminal 
pinchtab tabs
curl http://localhost:9867/tabs
Response 
{
  "tabs": [
    {
      "id": "8f9c7d4e1234567890abcdef12345678",
      "url": "https://pinchtab.com",
      "title": "PinchTab",
      "type": "page"
    }
  ]
}

Notes:

  • GET /tabs is not a fleet-wide orchestrator inventory
  • in bridge mode or shorthand mode it lists tabs from the active browser context
  • pinchtab tabs follows that shorthand behavior

One Instance

terminal 
curl http://localhost:9867/instances/inst_ea2e747f/tabs
curl http://localhost:9867/instances/inst_ea2e747f/tabs
Response 
[
  {
    "id": "8f9c7d4e1234567890abcdef12345678",
    "instanceId": "inst_ea2e747f",
    "url": "https://pinchtab.com",
    "title": "PinchTab"
  }
]

All Running Instances

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

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

terminal 
pinchtab tab navigate <tabId> https://example.com
curl -X POST http://localhost:9867/tabs/<tabId>/navigate \  -H "Content-Type: application/json" \  -d '{"url":"https://example.com"}'
Response 
{
  "tabId": "8f9c7d4e1234567890abcdef12345678",
  "url": "https://example.com",
  "title": "Example Domain"
}

Snapshot

terminal 
pinchtab tab snapshot <tabId> -i -c
curl "http://localhost:9867/tabs/<tabId>/snapshot?interactive=true&compact=true"

Use this to retrieve the accessibility snapshot and element refs for the page.

Text

terminal 
pinchtab tab text <tabId> --raw
curl "http://localhost:9867/tabs/<tabId>/text?raw=true"

Find

terminal 
curl -X POST http://localhost:9867/tabs/<tabId>/find \  -H "Content-Type: application/json" \  -d '{"query":"login button"}'
curl -X POST http://localhost:9867/tabs/<tabId>/find \  -H "Content-Type: application/json" \  -d '{"query":"login button"}'
Response 
{
  "best_ref": "e5",
  "confidence": "high",
  "score": 0.85
}

There is no dedicated CLI find command today.

Action

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

Other CLI-backed tab operations include:

  • pinchtab tab type <tabId> <ref> <text>
  • pinchtab tab fill <tabId> <ref> <text>
  • pinchtab tab press <tabId> <key>
  • pinchtab tab hover <tabId> <ref>
  • pinchtab tab scroll <tabId> <direction|pixels>
  • pinchtab tab select <tabId> <ref> <value>
  • pinchtab tab focus <tabId> <ref>

Screenshot

terminal 
pinchtab tab screenshot <tabId> -o out.png
curl "http://localhost:9867/tabs/<tabId>/screenshot?raw=true" > out.png

PDF

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

Cookies

terminal 
pinchtab tab cookies <tabId>
curl http://localhost:9867/tabs/<tabId>/cookies

Metrics

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

This returns aggregate browser metrics for the tab’s owning instance, not isolated per-tab memory.

Lock And Unlock

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

Close A Tab

terminal 
pinchtab tab close <tabId>
curl -X POST http://localhost:9867/tabs/<tabId>/close
Response 
{
  "status": "closed"
}

Important Limits

  • there is no documented GET /tabs/{id} resource endpoint in the current server routes
  • pinchtab tab info <tabId> exists in the CLI, but it depends on a route that is not part of the current documented HTTP surface
  • GET /tabs and GET /instances/tabs serve different purposes and should not be treated as interchangeable