Skip to content

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

docs: getting started guide for pinchtab api workflows

Mario7be32cfc98ff
diff --git a/docs/getting-started-api-workflows.md b/docs/getting-started-api-workflows.md
new file mode 100644
index 00000000..31fda223
--- /dev/null
+++ b/docs/getting-started-api-workflows.md
@@ -0,0 +1,558 @@
+# Pinchtab API Workflows: Getting Started
+
+Learn the correct way to use Pinchtab's API through practical, step-by-step examples.
+
+## Core Concept: Tab-Centric Design
+
+Pinchtab is **tab-centric**, not URL-centric. This is the key to understanding the API.
+
+### Why Tab-Centric?
+
+```
+❌ WRONG ASSUMPTION:
+"I can call /snapshot and pass a URL"
+curl '/snapshot?url=https://example.com'
+
+✅ CORRECT MODEL:
+1. Create a tab (which navigates to a URL) → get tabId
+2. Use tabId for all subsequent operations
+```
+
+### Why This Design?
+
+- **Multiple tabs** can exist simultaneously, each with different state
+- **Each tab has its own** cookies, navigation history, scripts, DOM
+- **You need to specify WHICH tab** you're working with → `?tabId=X`
+- **Matches Chrome's DevTools Protocol** (the standard browser API)
+- **Enables multi-agent coordination** (agents can lock tabs)
+
+---
+
+## The Complete Workflow Pattern
+
+Every Pinchtab workflow follows this pattern:
+
+```
+1. Create tab (+ navigate to URL) → Get tabId
+ ↓
+2. Interact with tab (snapshot, click, type, eval)
+ ↓
+3. Verify results (snapshot again, screenshot)
+ ↓
+4. Optional: Close tab when done
+```
+
+---
+
+## Workflow 1: Text Extraction (Simplest)
+
+**Goal:** Get readable text from a webpage.
+
+### Step-by-Step
+
+**Step 1: Create tab + navigate**
+```bash
+curl -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://example.com"}'
+```
+
+**Response:**
+```json
+{
+ "tabId": "ABC123DEF456",
+ "title": "Example Domain",
+ "url": "https://example.com/"
+}
+```
+
+**Step 2: Extract text (use tabId)**
+```bash
+curl "http://localhost:9867/text?tabId=ABC123DEF456"
+```
+
+**Response:**
+```json
+{
+ "text": "Example Domain\nThis domain is for use in examples...",
+ "length": 234
+}
+```
+
+**Complete script:**
+```bash
+#!/bin/bash
+URL="https://example.com"
+
+# Create tab and extract tabId
+TAB_RESPONSE=$(curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d "{\"action\":\"new\",\"url\":\"$URL\"}")
+
+TABID=$(echo $TAB_RESPONSE | jq -r '.tabId')
+echo "Created tab: $TABID"
+
+# Get text
+curl -s "http://localhost:9867/text?tabId=$TABID" | jq '.text'
+
+# Cleanup
+curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d "{\"action\":\"close\",\"tabId\":\"$TABID\"}"
+```
+
+---
+
+## Workflow 2: Snapshot + Click (Interaction)
+
+**Goal:** See page structure, click an element, verify the change.
+
+### Step-by-Step
+
+**Step 1: Create tab + navigate**
+```bash
+curl -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://example.com/interactive"}'
+```
+
+**Response:**
+```json
+{
+ "tabId": "XYZ789",
+ "title": "Interactive Page",
+ "url": "https://example.com/interactive"
+}
+```
+
+**Step 2: Get snapshot (see interactive elements)**
+```bash
+curl "http://localhost:9867/snapshot?tabId=XYZ789&filter=interactive"
+```
+
+**Response:**
+```json
+{
+ "elements": [
+ {
+ "ref": "e0",
+ "role": "heading",
+ "name": "Interactive Page"
+ },
+ {
+ "ref": "e5",
+ "role": "button",
+ "name": "Click Me!"
+ },
+ {
+ "ref": "e8",
+ "role": "link",
+ "name": "Learn More"
+ }
+ ]
+}
+```
+
+**Step 3: Click element (e5)**
+```bash
+curl -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"click","ref":"e5","tabId":"XYZ789"}'
+```
+
+**Step 4: Verify result (snapshot again)**
+```bash
+curl "http://localhost:9867/snapshot?tabId=XYZ789&filter=interactive"
+```
+
+**Complete script:**
+```bash
+#!/bin/bash
+URL="https://example.com/interactive"
+
+# Step 1: Create tab
+TAB=$(curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d "{\"action\":\"new\",\"url\":\"$URL\"}")
+
+TABID=$(echo $TAB | jq -r '.tabId')
+echo "Tab created: $TABID"
+
+# Step 2: Get interactive elements
+echo "Getting interactive elements..."
+SNAPSHOT=$(curl -s "http://localhost:9867/snapshot?tabId=$TABID&filter=interactive")
+echo $SNAPSHOT | jq '.elements[] | {ref, name}'
+
+# Step 3: Click first button (ref=e5)
+echo "Clicking button e5..."
+curl -s -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d "{\"kind\":\"click\",\"ref\":\"e5\",\"tabId\":\"$TABID\"}"
+
+# Step 4: Verify change
+echo "Verifying result..."
+curl -s "http://localhost:9867/snapshot?tabId=$TABID&filter=interactive" | jq '.elements'
+
+# Cleanup
+curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d "{\"action\":\"close\",\"tabId\":\"$TABID\"}"
+```
+
+---
+
+## Workflow 3: Form Filling
+
+**Goal:** Fill a form and submit it.
+
+### Step-by-Step
+
+**Step 1: Navigate to form**
+```bash
+TABID=$(curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://example.com/login"}' | jq -r '.tabId')
+```
+
+**Step 2: Get form fields (snapshot)**
+```bash
+curl -s "http://localhost:9867/snapshot?tabId=$TABID&filter=interactive" | jq '.elements[]'
+```
+
+**Output:**
+```json
+{
+ "ref": "e3",
+ "role": "textbox",
+ "name": "Email"
+}
+{
+ "ref": "e5",
+ "role": "textbox",
+ "name": "Password"
+}
+{
+ "ref": "e7",
+ "role": "button",
+ "name": "Sign In"
+}
+```
+
+**Step 3: Fill email field (e3)**
+```bash
+curl -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"fill","ref":"e3","text":"[email protected]","tabId":"'"$TABID"'"}'
+```
+
+**Step 4: Fill password field (e5)**
+```bash
+curl -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"fill","ref":"e5","text":"mypassword","tabId":"'"$TABID"'"}'
+```
+
+**Step 5: Click submit (e7)**
+```bash
+curl -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"click","ref":"e7","tabId":"'"$TABID"'"}'
+```
+
+**Step 6: Verify success (check page)**
+```bash
+curl -s "http://localhost:9867/text?tabId=$TABID" | jq '.text'
+```
+
+**Complete script:**
+```bash
+#!/bin/bash
+TABID=$(curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://example.com/login"}' | jq -r '.tabId')
+
+echo "Tab: $TABID"
+
+# Get form
+echo "Getting form fields..."
+curl -s "http://localhost:9867/snapshot?tabId=$TABID&filter=interactive" | jq '.elements[] | {ref, name}'
+
+# Fill email
+curl -s -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d "{\"kind\":\"fill\",\"ref\":\"e3\",\"text\":\"[email protected]\",\"tabId\":\"$TABID\"}"
+
+# Fill password
+curl -s -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d "{\"kind\":\"fill\",\"ref\":\"e5\",\"text\":\"mypassword\",\"tabId\":\"$TABID\"}"
+
+# Click submit
+curl -s -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d "{\"kind\":\"click\",\"ref\":\"e7\",\"tabId\":\"$TABID\"}"
+
+# Wait for page load
+sleep 2
+
+# Check result
+echo "Login result:"
+curl -s "http://localhost:9867/text?tabId=$TABID" | jq '.text' | head -5
+
+# Cleanup
+curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d "{\"action\":\"close\",\"tabId\":\"$TABID\"}"
+```
+
+---
+
+## Workflow 4: Multi-Tab Coordination
+
+**Goal:** Work with multiple tabs simultaneously.
+
+### Step-by-Step
+
+**Step 1: Create first tab**
+```bash
+TAB1=$(curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://github.com"}' | jq -r '.tabId')
+
+echo "Tab 1: $TAB1"
+```
+
+**Step 2: Create second tab**
+```bash
+TAB2=$(curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://stackoverflow.com"}' | jq -r '.tabId')
+
+echo "Tab 2: $TAB2"
+```
+
+**Step 3: List all tabs**
+```bash
+curl -s http://localhost:9867/tabs | jq '.tabs[]'
+```
+
+**Step 4: Get snapshot from each tab**
+```bash
+echo "Tab 1 snapshot:"
+curl -s "http://localhost:9867/snapshot?tabId=$TAB1&format=text&maxTokens=500"
+
+echo "Tab 2 snapshot:"
+curl -s "http://localhost:9867/snapshot?tabId=$TAB2&format=text&maxTokens=500"
+```
+
+**Step 5: Interact with specific tabs**
+```bash
+# Click on Tab 1
+curl -s -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d "{\"kind\":\"click\",\"ref\":\"e5\",\"tabId\":\"$TAB1\"}"
+
+# Click on Tab 2
+curl -s -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d "{\"kind\":\"click\",\"ref\":\"e3\",\"tabId\":\"$TAB2\"}"
+```
+
+**Complete script:**
+```bash
+#!/bin/bash
+
+# Create tabs
+TAB1=$(curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://github.com"}' | jq -r '.tabId')
+
+TAB2=$(curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://stackoverflow.com"}' | jq -r '.tabId')
+
+echo "Tab 1: $TAB1"
+echo "Tab 2: $TAB2"
+
+# List all tabs
+echo "Open tabs:"
+curl -s http://localhost:9867/tabs | jq '.tabs[] | {id, url, title}'
+
+# Get content from each
+echo "Tab 1 content:"
+curl -s "http://localhost:9867/text?tabId=$TAB1" | jq '.text' | head -3
+
+echo "Tab 2 content:"
+curl -s "http://localhost:9867/text?tabId=$TAB2" | jq '.text' | head -3
+
+# Cleanup
+curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d "{\"action\":\"close\",\"tabId\":\"$TAB1\"}"
+
+curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d "{\"action\":\"close\",\"tabId\":\"$TAB2\"}"
+```
+
+---
+
+## Workflow 5: PDF Export
+
+**Goal:** Generate a PDF from a webpage.
+
+### Step-by-Step
+
+**Step 1: Navigate**
+```bash
+TABID=$(curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://example.com/report"}' | jq -r '.tabId')
+```
+
+**Step 2: Generate PDF**
+```bash
+curl "http://localhost:9867/pdf?tabId=$TABID&landscape=true&displayHeaderFooter=true" \
+ -o report.pdf
+```
+
+**Complete script:**
+```bash
+#!/bin/bash
+TABID=$(curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://example.com/report"}' | jq -r '.tabId')
+
+echo "Creating PDF from tab: $TABID"
+
+# Generate PDF with options
+curl -s "http://localhost:9867/pdf?tabId=$TABID&landscape=true&displayHeaderFooter=true&headerTemplate=%3Cdiv%3EReport%3C%2Fdiv%3E" \
+ -o report.pdf
+
+echo "PDF saved: report.pdf"
+
+# Cleanup
+curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d "{\"action\":\"close\",\"tabId\":\"$TABID\"}"
+```
+
+---
+
+## Common Mistakes & Solutions
+
+### ❌ Mistake 1: Calling /snapshot without tabId
+
+```bash
+# WRONG - returns about:blank
+curl "http://localhost:9867/snapshot?format=text"
+
+# CORRECT - use tabId
+curl "http://localhost:9867/snapshot?tabId=ABC123&format=text"
+```
+
+### ❌ Mistake 2: Passing URL to /action or /snapshot
+
+```bash
+# WRONG - /snapshot doesn't take a URL
+curl "http://localhost:9867/snapshot?url=https://example.com"
+
+# CORRECT - create tab first, then use tabId
+TABID=$(curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://example.com"}' | jq -r '.tabId')
+curl "http://localhost:9867/snapshot?tabId=$TABID"
+```
+
+### ❌ Mistake 3: Not extracting tabId from response
+
+```bash
+# WRONG - response is JSON, not plain text
+TABID=$(curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://example.com"}')
+
+# Use $TABID in queries → gets entire JSON object
+
+# CORRECT - extract with jq
+TABID=$(curl -s -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://example.com"}' | jq -r '.tabId')
+```
+
+### ❌ Mistake 4: Using refs from old snapshots
+
+```bash
+# WRONG - page changed, e5 no longer a button
+curl "http://localhost:9867/snapshot?tabId=$TABID&filter=interactive" > snapshot1.json
+# ... do something ...
+curl -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"click","ref":"e5","tabId":"'"$TABID"'"}'
+
+# CORRECT - get fresh snapshot before clicking
+curl "http://localhost:9867/snapshot?tabId=$TABID&filter=interactive" > snapshot2.json
+# Read refs from snapshot2.json
+curl -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"click","ref":"e7","tabId":"'"$TABID"'"}'
+```
+
+---
+
+## Key Takeaways
+
+1. **Create tab first** — Every workflow starts with creating a tab
+2. **Extract tabId** — Use jq: `jq -r '.tabId'`
+3. **Pass tabId everywhere** — All operations need `?tabId=X` or in request body
+4. **Get fresh snapshots** — Refs change when page updates; get new snapshot
+5. **Chain operations** — Navigate → Snapshot → Click → Snapshot → Close
+
+---
+
+## Quick Reference: When to Use Each Endpoint
+
+| Goal | Endpoint | Requires tabId |
+|------|----------|---|
+| Create/navigate | `POST /tab` | No (creates tab) |
+| See page structure | `GET /snapshot` | Yes |
+| See only buttons/links | `GET /snapshot?filter=interactive` | Yes |
+| Click/type/press | `POST /action` | Yes |
+| Extract text | `GET /text` | Yes |
+| Run JavaScript | `POST /execute` | Yes |
+| Screenshot | `GET /screenshot` | Yes |
+| PDF export | `GET /pdf` | Yes |
+| List tabs | `GET /tabs` | No |
+| Close tab | `POST /tab` (close) | Yes (in body) |
+
+---
+
+## Debugging Tips
+
+### Check if tab exists
+```bash
+curl http://localhost:9867/tabs | jq '.tabs[] | select(.id=="ABC123")'
+```
+
+### Get current page URL
+```bash
+curl -s "http://localhost:9867/text?tabId=$TABID" | jq '.url'
+```
+
+### Verify tabId is valid
+```bash
+curl -s "http://localhost:9867/snapshot?tabId=$TABID" | jq 'if .url then "Valid" else "Invalid" end'
+```
+
+### See all interactive elements
+```bash
+curl -s "http://localhost:9867/snapshot?tabId=$TABID&filter=interactive" | jq '.elements[].name'
+```
+
+---
+
+## Next Steps
+
+- **Workflow examples:** See [`docs/curl-commands.md`](curl-commands.md) for more examples
+- **CLI alternative:** Try `pinchtab` CLI commands in [`docs/cli-commands.md`](cli-commands.md)
+- **API reference:** Full endpoint documentation in [`docs/curl-commands.md`](curl-commands.md)