Skip to content

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

docs: add root cause analysis of API misuse and solutions

Mario5ea7c64f3a6f
diff --git a/docs/API-MISUSE-ROOT-CAUSE-ANALYSIS.md b/docs/API-MISUSE-ROOT-CAUSE-ANALYSIS.md
new file mode 100644
index 00000000..692971b8
--- /dev/null
+++ b/docs/API-MISUSE-ROOT-CAUSE-ANALYSIS.md
@@ -0,0 +1,293 @@
+# Pinchtab API Misuse: Root Cause Analysis & Solutions
+
+**Date:** February 27, 2026
+**Summary:** Misunderstood Pinchtab API design led to silent failures. Root cause: inadequate documentation of API dependencies and workflows.
+
+---
+
+## The Problem
+
+### What I Did Wrong
+```bash
+curl 'http://localhost:9867/snapshot?url=https://www.bbc.com&format=text'
+ ↑
+ This parameter doesn't exist!
+```
+
+### What Happened
+- Endpoint exists: `/snapshot` ✓
+- Parameter exists: `?format=text` ✓
+- Parameter `?url=...` does NOT exist ✗
+- API returned 200 OK (not an error!)
+- But with no tabId → defaulted to current tab (blank)
+- Result: `about:blank` response (silent failure)
+
+### Why It Was Confusing
+I didn't get an error. The API returned valid JSON:
+```json
+{
+ "title": "",
+ "url": "about:blank"
+}
+```
+
+This looked like Pinchtab was broken, not like I was using the API wrong.
+
+---
+
+## Root Cause: Documentation Gaps
+
+### Problem 1: API Reference Assumes Too Much Context
+
+**File:** `skill/pinchtab/references/api.md`
+
+**Current documentation:**
+```bash
+# Snapshot (accessibility tree)
+curl /snapshot
+
+# Interactive elements only
+curl "/snapshot?filter=interactive"
+
+# Limit depth
+curl "/snapshot?depth=5"
+```
+
+**Why it's misleading:**
+- Shows isolated examples without dependencies
+- Doesn't mention `?tabId=...` (required parameter!)
+- No examples using `?tabId=X`
+- Implies you can just call `/snapshot` and get page content
+- Agent's mental model: "snapshot is like web_fetch, takes a URL"
+
+**Missing context:**
+- You CANNOT: `curl /snapshot?url=https://...`
+- You MUST: `curl /snapshot?tabId=<ID>&url=...` (and tabId comes from elsewhere)
+- Where does tabId come from? → Not explained in this section
+
+---
+
+### Problem 2: Tab Management Section Exists But Isn't Connected
+
+**File:** `skill/pinchtab/references/api.md` (later in the document)
+
+**Current documentation:**
+```bash
+# Tab management
+curl /tabs
+
+# Open new tab
+curl -X POST /tab -H 'Content-Type: application/json' \
+ -d '{"action": "new", "url": "https://example.com"}'
+
+# Close tab
+curl -X POST /tab -H 'Content-Type: application/json' \
+ -d '{"action": "close", "tabId": "TARGET_ID"}'
+```
+
+**Problem:**
+- Shows how to CREATE a tab and get `tabId`
+- But `/snapshot` section (earlier) doesn't reference this
+- No explicit: "After creating a tab, use this tabId with /snapshot"
+- Two sections that need each other aren't connected
+
+---
+
+### Problem 3: SKILL.md Conceptual But Not Practical
+
+**File:** `skill/pinchtab/SKILL.md`
+
+**Current documentation:**
+```markdown
+# Core Workflow: Actual API Calls
+
+The typical agent loop:
+
+1. **Navigate** to a URL
+2. **Snapshot** the accessibility tree (get refs)
+3. **Act** on refs (click, type, press)
+```
+
+**Problem:**
+- "Navigate to a URL" — but which endpoint?
+ - `/navigate` (POST) — navigates current tab
+ - `/tab {"action":"new","url":"..."}` (POST) — creates new tab
+ - Documentation doesn't clarify the difference!
+- "Snapshot the accessibility tree" — assumes you already know you need a tabId
+- Missing the `→ curl` examples that show actual sequencing
+
+---
+
+## The Correct API Flow
+
+### Step-by-Step (What Actually Works)
+
+```bash
+# ✅ STEP 1: Create tab + navigate (returns tabId)
+curl -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://www.bbc.com","timeout":10}'
+
+# Response:
+# {
+# "tabId": "7A2578741782B5C085640C984F511358",
+# "title": "BBC - Home",
+# "url": "https://www.bbc.co.uk/"
+# }
+
+# ✅ STEP 2: Use tabId to get snapshot
+curl "http://localhost:9867/snapshot?tabId=7A2578741782B5C085640C984F511358&format=text&maxTokens=2000"
+
+# Response:
+# # BBC - Home
+# # https://www.bbc.co.uk/
+# # 149 nodes
+#
+# e0 RootWebArea "BBC - Home" [focused]
+# e1 banner
+# e2 main
+# ... (semantic accessibility tree with clickable refs)
+```
+
+### Why This Design?
+
+Pinchtab is **tab-centric**, not URL-centric:
+- `/snapshot` operates on a tab, not a URL
+- Multiple tabs can exist simultaneously
+- Each tab has its own state, navigation history, cookies
+- Need to specify WHICH tab you're working with → `?tabId=X`
+
+This is correct design (matches CDP/browser model), but the documentation doesn't explain the "why".
+
+---
+
+## Solutions Implemented
+
+### 1. **New Wrapper Script: `scripts/pinchtab-curl-wrapper.sh`**
+
+Hides complexity behind simple commands:
+```bash
+# Instead of:
+# Step 1: Create tab, extract tabId
+# Step 2: Call /snapshot with tabId
+# Step 3: Parse JSON, act on result
+
+# Just use:
+./pinchtab-curl-wrapper.sh text https://www.bbc.com
+./pinchtab-curl-wrapper.sh snapshot https://www.bbc.com compact
+./pinchtab-curl-wrapper.sh click https://www.bbc.com e5
+```
+
+**What it does:**
+- Handles tab creation internally
+- Manages tabId flow
+- Provides clean CLI
+- Error handling
+- Color output
+
+---
+
+### 2. **Updated Documentation**
+
+#### In `pinchtab-clean-slate.md`
+- Added "Validation Method" section explaining API flow
+- Included sample response showing structure
+- Clarified why Pinchtab returns refs (e0, e1...) not just text
+- Provided working curl examples
+
+#### In PR Description
+- "Root Cause Analysis" section
+- Actual curl examples
+- Explanation of why it failed
+
+#### Recommendations for Future Docs
+1. Add **"Workflow Examples"** section BEFORE API reference
+2. Show complete end-to-end examples:
+ ```markdown
+ ### Example 1: Extract Text from a URL
+ - Use: /tab to create tab
+ - Then: /text to extract
+
+ ### Example 2: Get Refs and Click Elements
+ - Use: /tab to create tab
+ - Then: /snapshot to get refs (e0, e1...)
+ - Then: /action to click a ref
+ - Then: /snapshot again to see result
+ ```
+
+3. Add "Why This Design?" sections explaining:
+ - Why /snapshot needs tabId (tab-centric, not URL-centric)
+ - How it differs from web_fetch or OpenClaw (which are stateless)
+ - When to use /navigate vs /tab?action=new
+
+---
+
+## Lessons Learned
+
+### For API Design
+- **Document the dependencies**, not just the endpoints
+- **Show complete workflows** in addition to isolated commands
+- **Explain the "why"** — why is it tab-centric? Why not just pass URL?
+- **Connect related sections** (Tab Management + Snapshot)
+
+### For API Usage
+- **Read the entire reference**, not just the section you think you need
+- **Look for examples showing sequencing** (step 1, step 2, step 3)
+- **Try the wrapper/CLI first** before raw HTTP if it exists
+- **Debug silently by checking assumptions** — "is my tabId valid?" not "is the API broken?"
+
+### For Documentation
+- **Isolate reference docs** (api.md) from **practical guides** (getting-started.md)
+- **Use workflow diagrams** showing dependencies
+- **Include "common mistakes"** section
+
+---
+
+## Real Data: Pinchtab is Excellent
+
+Once you use it correctly:
+
+| Metric | Value |
+|--------|-------|
+| Response size | 7.3-7.7 KB |
+| Tokens per page | 1,834-1,934 |
+| Includes JavaScript rendering | ✓ |
+| Returns clickable refs | ✓ (e0, e1, e2...) |
+| vs OpenClaw snapshot | 27x lighter |
+| vs web_fetch | 3.1-3.6x lighter |
+
+The API is well-designed. The documentation just needs a getting-started section.
+
+---
+
+## Files Included
+
+- `API-MISUSE-ROOT-CAUSE-ANALYSIS.md` (this file)
+- `scripts/pinchtab-curl-wrapper.sh` (solution)
+- `pinchtab-clean-slate.md` (with empirical data + proper examples)
+- PR #52 with complete benchmark data
+
+---
+
+## Recommendations
+
+### Short Term (PR Ready)
+- ✅ Add wrapper script
+- ✅ Update benchmark docs with real data
+- ✅ Document the proper API flow in pinchtab-clean-slate.md
+
+### Medium Term (Next Release)
+- [ ] Add "Workflow Examples" section to api.md
+- [ ] Add Getting-Started guide (different from reference docs)
+- [ ] Add "Common Mistakes" section
+- [ ] Update SKILL.md with actual curl examples
+- [ ] Add "Why This Design?" boxes
+
+### Long Term
+- [ ] Consider CLI-first approach (users learn \`pinchtab\` CLI before HTTP)
+- [ ] Add interactive tutorial: \`pinchtab interactive-tutorial\`
+- [ ] Add validation tool: \`pinchtab validate-setup\` (checks Pinchtab is running, port is open, etc.)
+
+---
+
+**Bottom line:** The Pinchtab API is solid. The documentation just needs to show HOW to use it in addition to WHAT endpoints exist.