docs/reference/tabs.md

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:

• Health
• Navigate
• Snapshot
• Text
• Click
• Type
• Fill
• Screenshot
• PDF
• Eval
• Press
• Hover
• Scroll
• Select
• Focus

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 no dedicated instance-scoped tab open CLI command today.

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

pinchtab instance navigate inst_ea2e747f https://pinchtab.com

List Tabs

Shorthand Or Bridge List

curl http://localhost:9867/tabs
# CLI Alternative
pinchtab tab
# 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 tab follows that shorthand behavior

One Instance

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

All Running Instances

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

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

Navigate An Existing Tab

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

Snapshot

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

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

Text

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

Find

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

curl -X POST http://localhost:9867/tabs/<tabId>/action \
  -H "Content-Type: application/json" \
  -d '{"kind":"click","ref":"e5"}'
# CLI Alternative
pinchtab tab click <tabId> 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

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

PDF

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

Cookies

curl http://localhost:9867/tabs/<tabId>/cookies
# CLI Alternative
pinchtab tab cookies <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

Tab lock/unlock is API-only — no CLI commands exist yet.

Lock A Specific Tab

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

Lock The Active Tab

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

Unlock A Specific Tab

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

Unlock The Active Tab

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

Close A Tab

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

Important Limits

• There is no GET /tabs/{id} endpoint for fetching single tab info. Use GET /tabs to list all tabs or access tab-scoped sub-paths like /tabs/{id}/snapshot, /tabs/{id}/action, etc.
• GET /tabs and GET /instances/tabs serve different purposes and should not be treated as interchangeable