Skip to content

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

fix: update all documentation examples to use correct API routes

Marioaf40f19e868c
diff --git a/docs/get-started.md b/docs/get-started.md
index 378b51ff..2cac802d 100644
--- a/docs/get-started.md
+++ b/docs/get-started.md
@@ -94,10 +94,10 @@ sleep 3
pinchtab instance navigate $INST https://example.com
# Get page structure
-curl http://localhost:9867/instances/$INST/snapshot | jq '.nodes | map({role, name}) | .[0:5]'
+curl http://localhost:9867/tabs/$TAB_ID/snapshot | jq '.nodes | map({role, name}) | .[0:5]'
# Extract text
-curl http://localhost:9867/instances/$INST/text | jq '.text'
+curl http://localhost:9867/tabs/$TAB_ID/text | jq '.text'
```
✅ **You're running PinchTab!**
@@ -113,14 +113,14 @@ INST=$(pinchtab instance launch | jq -r '.id')
sleep 2
# Navigate
-TAB_ID=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \
- -d '{"url":"https://example.com"}' | jq -r '.tabId')
+TAB_ID=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
+ -d '{"url":"https://example.com"}' | jq -r '.id')
# Read the page as text
-curl http://localhost:9867/instances/$INST/text
+curl http://localhost:9867/tabs/$TAB_ID/text
# Get interactive elements (snapshot)
-curl http://localhost:9867/instances/$INST/snapshot | jq '.nodes | map({ref, role, name})'
+curl http://localhost:9867/tabs/$TAB_ID/snapshot | jq '.nodes | map({ref, role, name})'
```
### Take a Screenshot
@@ -141,18 +141,18 @@ curl "http://localhost:9867/tabs/$TAB_ID/pdf?landscape=true" -o output.pdf
```bash
# Get page structure (snapshot)
-SNAPSHOT=$(curl http://localhost:9867/instances/$INST/snapshot)
+SNAPSHOT=$(curl http://localhost:9867/tabs/$TAB_ID/snapshot)
# Extract a reference (e.g., first button)
BUTTON_REF=$(echo "$SNAPSHOT" | jq -r '.nodes[] | select(.role=="button") | .ref' | head -1)
# Click the button
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-H "Content-Type: application/json" \
-d '{"kind":"click","ref":"'$BUTTON_REF'"}'
# Or fill a form input
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-H "Content-Type: application/json" \
-d '{"kind":"fill","ref":"e3","text":"[email protected]"}'
```
@@ -171,7 +171,7 @@ curl http://localhost:9867/tabs
# Operate on specific tab
TAB_ID=$(curl http://localhost:9867/instances/$INST/tabs | jq -r '.[0].id')
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"click","ref":"e5","tabId":"'$TAB_ID'"}'
```
@@ -205,18 +205,18 @@ INST=$(pinchtab instance launch | jq -r '.id')
sleep 2
# 2. Navigate to a page
-TAB_ID=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \
- -d '{"url":"https://example.com"}' | jq -r '.tabId')
+TAB_ID=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
+ -d '{"url":"https://example.com"}' | jq -r '.id')
# 3. Get page structure (see buttons, links, inputs)
-curl http://localhost:9867/instances/$INST/snapshot
+curl http://localhost:9867/tabs/$TAB_ID/snapshot
# 4. Interact with page (click, type, etc.)
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"click","ref":"e5"}'
# 5. Verify changes
-curl http://localhost:9867/instances/$INST/snapshot
+curl http://localhost:9867/tabs/$TAB_ID/snapshot
# 6. Capture result
curl "http://localhost:9867/tabs/$TAB_ID/screenshot" -o page.png
@@ -241,15 +241,15 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch | jq -r '.id')
sleep 2
# Navigate
-curl -X POST http://localhost:9867/instances/$INST/navigate \
+curl -X POST http://localhost:9867/instances/$INST/tabs/open \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'
# Get snapshot
-curl http://localhost:9867/instances/$INST/snapshot
+curl http://localhost:9867/tabs/$TAB_ID/snapshot
# Extract text
-curl http://localhost:9867/instances/$INST/text
+curl http://localhost:9867/tabs/$TAB_ID/text
# Stop instance
curl -X POST http://localhost:9867/instances/$INST/stop
@@ -277,14 +277,15 @@ print(f"Created instance: {inst_id}")
# Wait for Chrome to initialize
time.sleep(2)
-# 2. Navigate
-resp = requests.post(f"{BASE}/instances/{inst_id}/navigate", json={
+# 2. Create tab by navigating
+resp = requests.post(f"{BASE}/instances/{inst_id}/tabs/open", json={
"url": "https://example.com"
})
+tab_id = resp.json()["id"]
print(f"Navigated: {resp.json()}")
# 3. Get snapshot
-snapshot = requests.get(f"{BASE}/instances/{inst_id}/snapshot").json()
+snapshot = requests.get(f"{BASE}/tabs/{tab_id}/snapshot").json()
# Print interactive elements
for elem in snapshot.get("nodes", []):
@@ -292,13 +293,13 @@ for elem in snapshot.get("nodes", []):
print(f"{elem['ref']}: {elem['role']} - {elem['name']}")
# 4. Click an element
-requests.post(f"{BASE}/instances/{inst_id}/action", json={
- "kind": "click",
+requests.post(f"{BASE}/tabs/{tab_id}/action", json={
+ "action": "click",
"ref": "e5"
})
# 5. Get text
-text = requests.get(f"{BASE}/instances/{inst_id}/text").json()
+text = requests.get(f"{BASE}/tabs/{tab_id}/text").json()
print(f"Page text: {text['text'][:200]}...")
# 6. Stop instance
@@ -330,17 +331,19 @@ async function main() {
// Wait for Chrome to initialize
await new Promise(r => setTimeout(r, 2000));
- // 2. Navigate
- await fetch(`${BASE}/instances/${instId}/navigate`, {
+ // 2. Create tab by navigating
+ const navResp = await fetch(`${BASE}/instances/${instId}/tabs/open`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
url: "https://example.com"
})
});
+ const navData = await navResp.json();
+ const tabId = navData.id;
// 3. Get snapshot
- const snapResp = await fetch(`${BASE}/instances/${instId}/snapshot`);
+ const snapResp = await fetch(`${BASE}/tabs/${tabId}/snapshot`);
const snap = await snapResp.json();
// Print interactive elements
@@ -349,17 +352,17 @@ async function main() {
.forEach(n => console.log(`${n.ref}: ${n.role} - ${n.name}`));
// 4. Click element
- await fetch(`${BASE}/instances/${instId}/action`, {
+ await fetch(`${BASE}/tabs/${tabId}/action`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
- kind: "click",
+ action: "click",
ref: "e5"
})
});
// 5. Get text
- const textResp = await fetch(`${BASE}/instances/${instId}/text`);
+ const textResp = await fetch(`${BASE}/tabs/${tabId}/text`);
const text = await textResp.json();
console.log(`Page text: ${text.text.substring(0, 200)}...`);
@@ -432,14 +435,14 @@ INST=$(pinchtab instance launch | jq -r '.id')
sleep 2
# Navigate
-curl -X POST http://localhost:9867/instances/$INST/navigate \
+curl -X POST http://localhost:9867/instances/$INST/tabs/open \
-d '{"url":"https://example.com/article"}'
# Extract text
-curl http://localhost:9867/instances/$INST/text | jq '.text'
+curl http://localhost:9867/tabs/$TAB_ID/text | jq '.text'
# Save to file
-curl http://localhost:9867/instances/$INST/text | jq -r '.text' > article.txt
+curl http://localhost:9867/tabs/$TAB_ID/text | jq -r '.text' > article.txt
# Stop instance
curl -X POST http://localhost:9867/instances/$INST/stop
@@ -453,28 +456,28 @@ INST=$(pinchtab instance launch | jq -r '.id')
sleep 2
# Navigate to form
-curl -X POST http://localhost:9867/instances/$INST/navigate \
+curl -X POST http://localhost:9867/instances/$INST/tabs/open \
-d '{"url":"https://example.com/contact"}'
# Get form structure
-SNAP=$(curl http://localhost:9867/instances/$INST/snapshot)
+SNAP=$(curl http://localhost:9867/tabs/$TAB_ID/snapshot)
# Fill fields (get refs from snapshot)
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"fill","ref":"e3","text":"John Doe"}'
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"fill","ref":"e5","text":"[email protected]"}'
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"fill","ref":"e7","text":"My message here"}'
# Click submit
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"click","ref":"e10"}'
# Verify success
-curl http://localhost:9867/instances/$INST/snapshot | jq '.nodes | length'
+curl http://localhost:9867/tabs/$TAB_ID/snapshot | jq '.nodes | length'
```
### Scenario 3: Login + Stay Logged In
@@ -490,16 +493,16 @@ INST=$(curl -s -X POST http://localhost:9867/instances/start \
sleep 2
# Login
-curl -X POST http://localhost:9867/instances/$INST/navigate \
+curl -X POST http://localhost:9867/instances/$INST/tabs/open \
-d '{"url":"https://example.com/login"}'
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"fill","ref":"e3","text":"[email protected]"}'
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"fill","ref":"e5","text":"password"}'
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"click","ref":"e7"}'
# Stop instance (profile saved)
@@ -511,7 +514,7 @@ INST=$(curl -s -X POST http://localhost:9867/instances/start \
sleep 2
# Navigate to dashboard (cookies preserved)
-curl -X POST http://localhost:9867/instances/$INST/navigate \
+curl -X POST http://localhost:9867/instances/$INST/tabs/open \
-d '{"url":"https://example.com/dashboard"}'
```
@@ -522,8 +525,8 @@ curl -X POST http://localhost:9867/instances/$INST/navigate \
INST=$(pinchtab instance launch | jq -r '.id')
sleep 2
-TAB_ID=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \
- -d '{"url":"https://reports.example.com/monthly"}' | jq -r '.tabId')
+TAB_ID=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
+ -d '{"url":"https://reports.example.com/monthly"}' | jq -r '.id')
# Export PDF
curl "http://localhost:9867/tabs/$TAB_ID/pdf?landscape=true" -o report.pdf
```
@@ -549,10 +552,10 @@ SOURCE_TAB=$(echo "$TABS" | jq -r '.[0].id')
DEST_TAB=$(echo "$TABS" | jq -r '.[1].id')
# Extract from source tab
-DATA=$(curl "http://localhost:9867/instances/$INST/text" | jq -r '.text')
+DATA=$(curl "http://localhost:9867/tabs/$TAB_ID/text" | jq -r '.text')
# Fill destination tab
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-H "Content-Type: application/json" \
-d '{"kind":"fill","ref":"e3","text":"'$DATA'","tabId":"'$DEST_TAB'"}'
```
@@ -589,7 +592,7 @@ while [ "$(curl -s http://localhost:9867/instances/$INST | jq -r '.status')" !=
done
# Now safe to use
-curl -X POST http://localhost:9867/instances/$INST/navigate \
+curl -X POST http://localhost:9867/instances/$INST/tabs/open \
-d '{"url":"https://example.com"}'
```
@@ -648,13 +651,13 @@ curl http://localhost:9867/instances/$INST
**Solution:**
```bash
# Get fresh snapshot
-SNAP=$(curl http://localhost:9867/instances/$INST/snapshot)
+SNAP=$(curl http://localhost:9867/tabs/$TAB_ID/snapshot)
# Extract new ref from snapshot
NEW_REF=$(echo "$SNAP" | jq -r '.nodes[] | select(.role=="button") | .ref' | head -1)
# Use new ref
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"click","ref":"'$NEW_REF'"}'
```
@@ -666,13 +669,13 @@ curl -X POST http://localhost:9867/instances/$INST/action \
```bash
# Get text content
-curl http://localhost:9867/instances/$INST/text
+curl http://localhost:9867/tabs/$TAB_ID/text
# Get snapshot (DOM structure)
-curl http://localhost:9867/instances/$INST/snapshot
+curl http://localhost:9867/tabs/$TAB_ID/snapshot
# Filter snapshot to interactive elements
-curl http://localhost:9867/instances/$INST/snapshot | \
+curl http://localhost:9867/tabs/$TAB_ID/snapshot | \
jq '.nodes[] | select(.role | IN("button", "link", "textbox"))'
```
@@ -680,31 +683,31 @@ curl http://localhost:9867/instances/$INST/snapshot | \
```bash
# Click element
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"click","ref":"e5"}'
# Type text
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"type","ref":"e3","text":"hello"}'
# Fill input
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"fill","ref":"e3","text":"value"}'
# Press key
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"press","key":"Enter"}'
# Focus element
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"focus","ref":"e5"}'
# Hover element
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"hover","ref":"e5"}'
# Select dropdown
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB_ID/action \
-d '{"kind":"select","ref":"e8","text":"Option 2"}'
```
@@ -748,7 +751,7 @@ done
# Distribute work across instances (round-robin)
for URL in "${URLS[@]}"; do
INST="${INSTANCES[$((INDEX % 5))]}"
- curl -X POST "http://localhost:9867/instances/$INST/navigate" \
+ curl -X POST "http://localhost:9867/instances/$INST/tabs/open" \
-d '{"url":"'$URL'"}' &
((INDEX++))
done
@@ -759,10 +762,10 @@ wait
```bash
# Use text extraction (cheaper than screenshots)
-curl http://localhost:9867/instances/$INST/text # Lower tokens
+curl http://localhost:9867/tabs/$TAB_ID/text # Lower tokens
# Use snapshot (cheaper than screenshot)
-curl http://localhost:9867/instances/$INST/snapshot # Lower tokens
+curl http://localhost:9867/tabs/$TAB_ID/snapshot # Lower tokens
# Screenshots are expensive (JPG encoding)
curl "http://localhost:9867/tabs/$TAB_ID/screenshot" # Higher tokens
@@ -777,11 +780,11 @@ curl "http://localhost:9867/tabs/$TAB_ID/screenshot" # Higher tokens
| Start orchestrator | `pinchtab` |
| Health check | `curl http://localhost:9867/health` |
| Create instance | `INST=$(pinchtab instance launch \| jq -r '.id')` |
-| Navigate | `curl -X POST http://localhost:9867/instances/$INST/navigate -d '{"url":"..."}' ` |
-| See structure | `curl http://localhost:9867/instances/$INST/snapshot` |
-| Get text | `curl http://localhost:9867/instances/$INST/text` |
-| Click element | `curl -X POST http://localhost:9867/instances/$INST/action -d '{"kind":"click","ref":"e5"}'` |
-| Type text | `curl -X POST http://localhost:9867/instances/$INST/action -d '{"kind":"type","ref":"e3","text":"hello"}'` |
+| Navigate | `curl -X POST http://localhost:9867/instances/$INST/tabs/open -d '{"url":"..."}' ` |
+| See structure | `curl http://localhost:9867/tabs/$TAB_ID/snapshot` |
+| Get text | `curl http://localhost:9867/tabs/$TAB_ID/text` |
+| Click element | `curl -X POST http://localhost:9867/tabs/$TAB_ID/action -d '{"kind":"click","ref":"e5"}'` |
+| Type text | `curl -X POST http://localhost:9867/tabs/$TAB_ID/action -d '{"kind":"type","ref":"e3","text":"hello"}'` |
| Screenshot | `curl "http://localhost:9867/tabs/$TAB_ID/screenshot" -o page.png` |
| PDF export | `curl http://localhost:9867/tabs/$TAB_ID/pdf -o out.pdf` |
| List instances | `curl http://localhost:9867/instances` |
diff --git a/docs/guides/common-patterns.md b/docs/guides/common-patterns.md
index 1eff8655..ca1fbbaf 100644
--- a/docs/guides/common-patterns.md
+++ b/docs/guides/common-patterns.md
@@ -47,7 +47,7 @@ echo "Chrome window is open - interact manually or use API calls"
sleep 2
# Optionally navigate to starting URL (via orchestrator proxy)
-curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \
+curl -s -X POST "http://localhost:9867/instances/$INST/tabs/open" \
-H "Content-Type: application/json" \
-d '{"url":"https://app.example.com"}'
@@ -115,12 +115,12 @@ for i in "${!INSTANCES[@]}"; do
# Run test in parallel (via orchestrator proxy)
(
- curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \
+ curl -s -X POST "http://localhost:9867/instances/$INST/tabs/open" \
-H "Content-Type: application/json" \
-d "{\"url\":\"$URL\"}" > /dev/null
# Verify page loaded
- TITLE=$(curl -s "http://localhost:9867/instances/$INST/snapshot" | jq -r '.title')
+ TITLE=$(curl -s "http://localhost:9867/tabs/$TAB_ID/snapshot" | jq -r '.title')
echo "Test $i: $TITLE"
) &
done
@@ -195,7 +195,7 @@ for i in "${!URLS[@]}"; do
URL="${URLS[$i]}"
INST="${INSTANCES[$((i % ${#INSTANCES[@]}))]}"
- curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \
+ curl -s -X POST "http://localhost:9867/instances/$INST/tabs/open" \
-H "Content-Type: application/json" \
-d "{\"url\":\"$URL\"}" &
done
@@ -243,7 +243,7 @@ for i in "${!URLS[@]}"; do
URL="${URLS[$i]}"
INST="${INSTANCES[$((i % ${#INSTANCES[@]}))]}"
- curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \
+ curl -s -X POST "http://localhost:9867/instances/$INST/tabs/open" \
-H "Content-Type: application/json" \
-d "{\"url\":\"$URL\"}" &
done
@@ -291,7 +291,7 @@ for i in $(seq 0 $((MAX_JOBS - 1))); do
INST="${INSTANCES[$((CURRENT_JOB % MAX_JOBS))]}"
(
- curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \
+ curl -s -X POST "http://localhost:9867/instances/$INST/tabs/open" \
-H "Content-Type: application/json" \
-d "{\"url\":\"$URL\"}" > /dev/null
echo "Processed: $URL"
@@ -306,7 +306,7 @@ while [ $CURRENT_JOB -lt ${#QUEUE[@]} ]; do
INST="${INSTANCES[$((CURRENT_JOB % MAX_JOBS))]}"
(
- curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \
+ curl -s -X POST "http://localhost:9867/instances/$INST/tabs/open" \
-H "Content-Type: application/json" \
-d "{\"url\":\"$URL\"}" > /dev/null
echo "Processed: $URL"
@@ -366,7 +366,7 @@ U3=$(curl -s -X POST http://localhost:9867/instances/start \
# - No interference between users
# User 1 navigates (via orchestrator proxy)
-curl -s -X POST "http://localhost:9867/instances/$U1/navigate" \
+curl -s -X POST "http://localhost:9867/instances/$U1/tabs/open" \
-H "Content-Type: application/json" \
-d '{"url":"https://app.example.com/login?user=1"}'
diff --git a/docs/guides/multi-instance.md b/docs/guides/multi-instance.md
index 6fea0bb3..14b22d26 100644
--- a/docs/guides/multi-instance.md
+++ b/docs/guides/multi-instance.md
@@ -47,7 +47,7 @@ The instance gets:
Navigate the instance via the orchestrator (recommended):
```bash
-curl -X POST http://localhost:9867/instances/inst_a365262a/navigate \
+curl -X POST http://localhost:9867/instances/inst_a365262a/tabs/open \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'
```
@@ -55,28 +55,31 @@ curl -X POST http://localhost:9867/instances/inst_a365262a/navigate \
**Response:**
```json
{
- "tabId": "tab_19949f62",
+ "id": "tab_19949f62",
"url": "https://example.com",
"title": "Example Domain"
}
```
-Each navigation automatically creates a new tab. Use the `tabId` for subsequent operations on that specific tab.
+Each navigation automatically creates a new tab. Use the `id` (tabId) for subsequent operations on that specific tab.
-**Note:** You can also access the instance directly on its port (9868), but using the orchestrator proxy (`9867/instances/{id}/*`) is recommended for consistency.
+**Note:** You can also access the instance directly on its port (9868), but using the orchestrator proxy is recommended for consistency.
### 4. Get Page Content
-Retrieve page snapshot (DOM, text, structured data) via orchestrator:
+Retrieve page snapshot using the tab ID:
```bash
-curl http://localhost:9867/instances/inst_a365262a/snapshot
+TAB=$(curl -s -X POST http://localhost:9867/instances/inst_a365262a/tabs/open \
+ -d '{"url":"https://example.com"}' | jq -r '.id')
+
+curl http://localhost:9867/tabs/$TAB/snapshot
```
Or get just the text:
```bash
-curl http://localhost:9867/instances/inst_a365262a/text
+curl http://localhost:9867/tabs/$TAB/text
```
### 5. Stop Instance
@@ -132,24 +135,26 @@ sleep 2
echo "Navigating all instances concurrently..."
-# Navigate all instances via orchestrator proxy (concurrent)
+# Navigate all instances and capture tab IDs
+TABS=()
for i in "${!INSTANCES[@]}"; do
ID="${INSTANCES[$i]}"
URL="${URLS[$i]}"
- curl -s -X POST "http://localhost:9867/instances/$ID/navigate" \
+ RESPONSE=$(curl -s -X POST "http://localhost:9867/instances/$ID/tabs/open" \
-H "Content-Type: application/json" \
- -d "{\"url\":\"$URL\"}" &
+ -d "{\"url\":\"$URL\"}")
+ TAB_ID=$(echo "$RESPONSE" | jq -r '.id')
+ TABS+=("$TAB_ID")
done
-wait
echo "All pages loaded. Getting snapshots..."
-# Get snapshots
-for i in "${!INSTANCES[@]}"; do
- ID="${INSTANCES[$i]}"
+# Get snapshots using tab IDs
+for i in "${!TABS[@]}"; do
+ TAB="${TABS[$i]}"
- curl -s "http://localhost:9867/instances/$ID/snapshot" > "snapshot-$i.json" &
+ curl -s "http://localhost:9867/tabs/$TAB/snapshot" > "snapshot-$i.json" &
done
wait
@@ -248,7 +253,7 @@ for TASK in "${TASKS[@]}"; do
ID="${INSTANCES[$((INSTANCE_INDEX % $FLEET_SIZE))]}"
# Send task to instance via orchestrator proxy
- curl -s -X POST "http://localhost:9867/instances/$ID/navigate" \
+ curl -s -X POST "http://localhost:9867/instances/$ID/tabs/open" \
-H "Content-Type: application/json" \
-d "{\"url\":\"https://api.example.com?task=$TASK\"}" > /dev/null &
@@ -402,7 +407,7 @@ while [ "$(curl -s http://localhost:9867/instances/$INST | jq -r '.status')" !=
done
# Now safe to use
-curl -X POST http://localhost:9867/instances/$INST/navigate \
+curl -X POST http://localhost:9867/instances/$INST/tabs/open \
-d '{"url":"https://example.com"}'
```
@@ -550,7 +555,7 @@ while [ "$(curl -s http://localhost:9867/instances/$INST | jq -r '.status')" !=
done
# Now safe to navigate
-curl -X POST http://localhost:9867/instances/$INST/navigate \
+curl -X POST http://localhost:9867/instances/$INST/tabs/open \
-d '{"url":"https://example.com"}'
```
@@ -593,11 +598,11 @@ Frees ports and RAM for new instances.
```bash
# DO: Use orchestrator proxy (recommended)
-curl -X POST http://localhost:9867/instances/$INST/navigate \
+curl -X POST http://localhost:9867/instances/$INST/tabs/open \
-d '{"url":"https://example.com"}'
# AVOID: Direct port access (less consistent)
-curl -X POST http://localhost:$PORT/navigate \
+curl -X POST http://localhost:$PORT/tabs/open \
-d '{"url":"https://example.com"}'
```
@@ -758,7 +763,7 @@ curl -X POST http://localhost:9867/instances/$OLD_INST/stop
```bash
# Instance IDs are stable, but ports change on restart
# Always use orchestrator proxy:
-curl http://localhost:9867/instances/$INST/navigate \
+curl http://localhost:9867/instances/$INST/tabs/open \
-d '{"url":"https://example.com"}'
# Don't rely on cached port numbers
diff --git a/docs/showcase.md b/docs/showcase.md
index 689bb8b5..9e0962e0 100644
--- a/docs/showcase.md
+++ b/docs/showcase.md
@@ -76,11 +76,11 @@ curl -X POST http://localhost:9867/instances/launch \
sleep 2
```
-**Step 3: Navigate to URL (returns tabId)**
+**Step 3: Create tab and navigate to URL (returns tabId)**
```bash
-TAB=$(curl -s -X POST http://localhost:9867/instances/inst_abc123/navigate \
+TAB=$(curl -s -X POST http://localhost:9867/instances/inst_abc123/tabs/open \
-H "Content-Type: application/json" \
- -d '{"url":"https://example.com"}' | jq -r '.tabId')
+ -d '{"url":"https://example.com"}' | jq -r '.id')
echo "Tab created: $TAB"
```
@@ -88,7 +88,7 @@ echo "Tab created: $TAB"
**Response contains:**
```json
{
- "tabId": "tab_def456",
+ "id": "tab_def456",
"title": "Example Domain",
"url": "https://example.com/"
}
@@ -96,7 +96,7 @@ echo "Tab created: $TAB"
**Step 4: Extract text (use tabId)**
```bash
-curl "http://localhost:9867/instances/inst_abc123/text?tabId=$TAB"
+curl "http://localhost:9867/tabs/$TAB/text"
```
**Response:**
@@ -122,16 +122,16 @@ echo "Created instance: $INST"
# Step 2: Wait for Chrome initialization
sleep 2
-# Step 3: Navigate and capture tabId
-TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \
+# Step 3: Create tab by navigating
+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
-H "Content-Type: application/json" \
- -d "{\"url\":\"$URL\"}" | jq -r '.tabId')
+ -d "{\"url\":\"$URL\"}" | jq -r '.id')
echo "Created tab: $TAB"
-# Step 4: Get text using tabId
+# Step 4: Get text
echo "Extracting text from $URL..."
-curl -s "http://localhost:9867/instances/$INST/text?tabId=$TAB" | jq '.text'
+curl -s "http://localhost:9867/tabs/$TAB/text" | jq '.text'
# Step 5: Cleanup
curl -s -X POST "http://localhost:9867/instances/$INST/stop"
@@ -146,7 +146,7 @@ echo "Stopped instance: $INST"
### Step-by-Step
-**Step 1: Create instance and navigate (get tabId)**
+**Step 1: Create instance and navigate to get tabId**
```bash
INST=$(curl -s -X POST http://localhost:9867/instances/launch \
-H "Content-Type: application/json" \
@@ -154,16 +154,16 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch \
sleep 2
-TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \
+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
-H "Content-Type: application/json" \
- -d '{"url":"https://example.com/interactive"}' | jq -r '.tabId')
+ -d '{"url":"https://example.com/interactive"}' | jq -r '.id')
echo "Instance: $INST, Tab: $TAB"
```
-**Step 2: Get snapshot (see interactive elements, use tabId)**
+**Step 2: Get snapshot (see interactive elements)**
```bash
-curl "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB"
+curl "http://localhost:9867/tabs/$TAB/snapshot"
```
**Response:**
@@ -189,16 +189,16 @@ curl "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB"
}
```
-**Step 3: Click element (e5, use tabId)**
+**Step 3: Click element**
```bash
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB/action \
-H "Content-Type: application/json" \
- -d '{"kind":"click","ref":"e5","tabId":"'$TAB'"}'
+ -d '{"action":"click","ref":"e5"}'
```
-**Step 4: Verify result (snapshot again, use tabId)**
+**Step 4: Verify result**
```bash
-curl "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB" | jq '.nodes'
+curl "http://localhost:9867/tabs/$TAB/snapshot" | jq '.nodes'
```
**Complete script:**
@@ -213,29 +213,29 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch \
echo "Instance: $INST"
-# Step 2: Wait and navigate (capture tabId)
+# Step 2: Wait and navigate to create tab
sleep 2
-TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \
+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
-H "Content-Type: application/json" \
- -d "{\"url\":\"$URL\"}" | jq -r '.tabId')
+ -d "{\"url\":\"$URL\"}" | jq -r '.id')
echo "Tab: $TAB"
-# Step 3: Get interactive elements using tabId
+# Step 3: Get interactive elements
echo "Getting interactive elements..."
-SNAPSHOT=$(curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB")
+SNAPSHOT=$(curl -s "http://localhost:9867/tabs/$TAB/snapshot")
echo "$SNAPSHOT" | jq '.nodes[] | select(.role | IN("button", "link")) | {ref, name}'
-# Step 4: Click button using tabId
+# Step 4: Click button
echo "Clicking button e5..."
-curl -s -X POST http://localhost:9867/instances/$INST/action \
+curl -s -X POST http://localhost:9867/tabs/$TAB/action \
-H "Content-Type: application/json" \
- -d '{"kind":"click","ref":"e5","tabId":"'$TAB'"}'
+ -d '{"action":"click","ref":"e5"}'
-# Step 5: Wait for action and verify using tabId
+# Step 5: Wait for action and verify
sleep 1
echo "Verifying result..."
-curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB" | jq '.nodes[] | {ref, role, name}' | head -10
+curl -s "http://localhost:9867/tabs/$TAB/snapshot" | jq '.nodes[] | {ref, role, name}' | head -10
# Step 6: Cleanup
curl -s -X POST "http://localhost:9867/instances/$INST/stop"
@@ -250,7 +250,7 @@ echo "Stopped instance: $INST"
### Step-by-Step
-**Step 1: Create instance and navigate to form (capture tabId)**
+**Step 1: Create instance and navigate to form**
```bash
INST=$(curl -s -X POST http://localhost:9867/instances/launch \
-H "Content-Type: application/json" \
@@ -258,16 +258,16 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch \
sleep 2
-TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \
+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
-H "Content-Type: application/json" \
- -d '{"url":"https://example.com/login"}' | jq -r '.tabId')
+ -d '{"url":"https://example.com/login"}' | jq -r '.id')
echo "Instance: $INST, Tab: $TAB"
```
-**Step 2: Get form fields (snapshot with tabId)**
+**Step 2: Get form fields**
```bash
-curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB" | jq '.nodes[] | select(.role | IN("textbox", "button"))'
+curl -s "http://localhost:9867/tabs/$TAB/snapshot" | jq '.nodes[] | select(.role | IN("textbox", "button"))'
```
**Output:**
@@ -289,30 +289,30 @@ curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB" | jq '.nodes
}
```
-**Step 3: Fill email field (e3, use tabId)**
+**Step 3: Fill email field**
```bash
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB/action \
-H "Content-Type: application/json" \
- -d '{"kind":"fill","ref":"e3","text":"[email protected]","tabId":"'$TAB'"}'
+ -d '{"action":"fill","ref":"e3","text":"[email protected]"}'
```
-**Step 4: Fill password field (e5, use tabId)**
+**Step 4: Fill password field**
```bash
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB/action \
-H "Content-Type: application/json" \
- -d '{"kind":"fill","ref":"e5","text":"mypassword","tabId":"'$TAB'"}'
+ -d '{"action":"fill","ref":"e5","text":"mypassword"}'
```
-**Step 5: Click submit (e7, use tabId)**
+**Step 5: Click submit**
```bash
-curl -X POST http://localhost:9867/instances/$INST/action \
+curl -X POST http://localhost:9867/tabs/$TAB/action \
-H "Content-Type: application/json" \
- -d '{"kind":"click","ref":"e7","tabId":"'$TAB'"}'
+ -d '{"action":"click","ref":"e7"}'
```
-**Step 6: Verify success (check page, use tabId)**
+**Step 6: Verify success (check page)**
```bash
-curl -s "http://localhost:9867/instances/$INST/text?tabId=$TAB" | jq '.text'
+curl -s "http://localhost:9867/tabs/$TAB/text" | jq '.text'
```
**Complete script:**
@@ -328,39 +328,39 @@ echo "Instance: $INST"
# Step 2: Wait and navigate (capture tabId)
sleep 2
-TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \
+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
-H "Content-Type: application/json" \
- -d '{"url":"https://example.com/login"}' | jq -r '.tabId')
+ -d '{"url":"https://example.com/login"}' | jq -r '.id')
echo "Tab: $TAB"
# Step 3: Get form fields
echo "Getting form fields..."
-curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB" | \
+curl -s "http://localhost:9867/tabs/$TAB/snapshot" | \
jq '.nodes[] | select(.role | IN("textbox", "button")) | {ref, name}'
-# Step 4: Fill email using tabId
-curl -s -X POST http://localhost:9867/instances/$INST/action \
+# Step 4: Fill email
+curl -s -X POST http://localhost:9867/tabs/$TAB/action \
-H "Content-Type: application/json" \
- -d '{"kind":"fill","ref":"e3","text":"[email protected]","tabId":"'$TAB'"}'
+ -d '{"action":"fill","ref":"e3","text":"[email protected]"}'
-# Step 5: Fill password using tabId
-curl -s -X POST http://localhost:9867/instances/$INST/action \
+# Step 5: Fill password
+curl -s -X POST http://localhost:9867/tabs/$TAB/action \
-H "Content-Type: application/json" \
- -d '{"kind":"fill","ref":"e5","text":"mypassword","tabId":"'$TAB'"}'
+ -d '{"action":"fill","ref":"e5","text":"mypassword"}'
-# Step 6: Click submit using tabId
+# Step 6: Click submit
echo "Submitting form..."
-curl -s -X POST http://localhost:9867/instances/$INST/action \
+curl -s -X POST http://localhost:9867/tabs/$TAB/action \
-H "Content-Type: application/json" \
- -d '{"kind":"click","ref":"e7","tabId":"'$TAB'"}'
+ -d '{"action":"click","ref":"e7"}'
# Step 7: Wait for page load
sleep 2
-# Step 8: Check result using tabId
+# Step 8: Check result
echo "Login result:"
-curl -s "http://localhost:9867/instances/$INST/text?tabId=$TAB" | jq '.text' | head -5
+curl -s "http://localhost:9867/tabs/$TAB/text" | jq '.text' | head -5
# Step 9: Cleanup
curl -s -X POST "http://localhost:9867/instances/$INST/stop"
@@ -384,20 +384,20 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch \
sleep 2
```
-**Step 2: Create first tab (get tabId)**
+**Step 2: Create first tab**
```bash
TAB1=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
-H "Content-Type: application/json" \
- -d '{"url":"https://github.com"}' | jq -r '.tabId')
+ -d '{"url":"https://github.com"}' | jq -r '.id')
echo "Tab 1: $TAB1"
```
-**Step 3: Create second tab (get tabId)**
+**Step 3: Create second tab**
```bash
TAB2=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
-H "Content-Type: application/json" \
- -d '{"url":"https://stackoverflow.com"}' | jq -r '.tabId')
+ -d '{"url":"https://stackoverflow.com"}' | jq -r '.id')
echo "Tab 2: $TAB2"
```
@@ -407,26 +407,26 @@ echo "Tab 2: $TAB2"
curl -s "http://localhost:9867/instances/$INST/tabs" | jq '.[] | {id, title, url}'
```
-**Step 5: Get snapshot from each tab (use tabIds)**
+**Step 5: Get snapshot from each tab**
```bash
# Get content from Tab 1
-curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB1" | jq '.nodes | length'
+curl -s "http://localhost:9867/tabs/$TAB1/snapshot" | jq '.nodes | length'
# Get content from Tab 2
-curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB2" | jq '.nodes | length'
+curl -s "http://localhost:9867/tabs/$TAB2/snapshot" | jq '.nodes | length'
```
-**Step 6: Interact with tabs (use tabIds)**
+**Step 6: Interact with tabs**
```bash
# Click on element in Tab 1
-curl -s -X POST http://localhost:9867/instances/$INST/action \
+curl -s -X POST http://localhost:9867/tabs/$TAB1/action \
-H "Content-Type: application/json" \
- -d '{"kind":"click","ref":"e5","tabId":"'$TAB1'"}'
+ -d '{"action":"click","ref":"e5"}'
# Click on element in Tab 2
-curl -s -X POST http://localhost:9867/instances/$INST/action \
+curl -s -X POST http://localhost:9867/tabs/$TAB2/action \
-H "Content-Type: application/json" \
- -d '{"kind":"click","ref":"e3","tabId":"'$TAB2'"}'
+ -d '{"action":"click","ref":"e3"}'
# Take screenshot of Tab 1
curl "http://localhost:9867/tabs/$TAB1/screenshot" -o screenshot1.png
@@ -446,15 +446,15 @@ echo "Instance: $INST"
# Step 2: Wait for initialization
sleep 2
-# Step 3: Create tabs and capture tabIds
+# Step 3: Create tabs
echo "Creating tabs..."
TAB1=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
-H "Content-Type: application/json" \
- -d '{"url":"https://github.com"}' | jq -r '.tabId')
+ -d '{"url":"https://github.com"}' | jq -r '.id')
TAB2=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
-H "Content-Type: application/json" \
- -d '{"url":"https://stackoverflow.com"}' | jq -r '.tabId')
+ -d '{"url":"https://stackoverflow.com"}' | jq -r '.id')
echo "Tab 1: $TAB1"
echo "Tab 2: $TAB2"
@@ -463,25 +463,25 @@ echo "Tab 2: $TAB2"
echo "Tabs in instance:"
curl -s "http://localhost:9867/instances/$INST/tabs" | jq '.[] | {id, title, url}'
-# Step 5: Get content from Tab 1 using tabId
+# Step 5: Get content from Tab 1
echo "Content from Tab 1:"
-curl -s "http://localhost:9867/instances/$INST/text?tabId=$TAB1" | jq '.text' | head -3
+curl -s "http://localhost:9867/tabs/$TAB1/text" | jq '.text' | head -3
# Step 6: Get snapshots from both tabs
echo "Getting snapshots..."
-echo "Tab 1 nodes: $(curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB1" | jq '.nodes | length')"
-echo "Tab 2 nodes: $(curl -s "http://localhost:9867/instances/$INST/snapshot?tabId=$TAB2" | jq '.nodes | length')"
+echo "Tab 1 nodes: $(curl -s "http://localhost:9867/tabs/$TAB1/snapshot" | jq '.nodes | length')"
+echo "Tab 2 nodes: $(curl -s "http://localhost:9867/tabs/$TAB2/snapshot" | jq '.nodes | length')"
# Step 7: Interact with elements in each tab
echo "Clicking element in Tab 1..."
-curl -s -X POST http://localhost:9867/instances/$INST/action \
+curl -s -X POST http://localhost:9867/tabs/$TAB1/action \
-H "Content-Type: application/json" \
- -d '{"kind":"click","ref":"e5","tabId":"'$TAB1'"}'
+ -d '{"action":"click","ref":"e5"}'
echo "Clicking element in Tab 2..."
-curl -s -X POST http://localhost:9867/instances/$INST/action \
+curl -s -X POST http://localhost:9867/tabs/$TAB2/action \
-H "Content-Type: application/json" \
- -d '{"kind":"click","ref":"e3","tabId":"'$TAB2'"}'
+ -d '{"action":"click","ref":"e3"}'
# Step 8: Take screenshots of each tab
echo "Taking screenshots..."
@@ -501,7 +501,7 @@ echo "Stopped instance: $INST"
### Step-by-Step
-**Step 1: Create instance and navigate (capture tabId)**
+**Step 1: Create instance and navigate to create tab**
```bash
INST=$(curl -s -X POST http://localhost:9867/instances/launch \
-H "Content-Type: application/json" \
@@ -509,9 +509,9 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch \
sleep 2
-TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \
+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
-H "Content-Type: application/json" \
- -d '{"url":"https://example.com/report"}' | jq -r '.tabId')
+ -d '{"url":"https://example.com/report"}' | jq -r '.id')
echo "Instance: $INST, Tab: $TAB"
```
@@ -536,22 +536,22 @@ echo "Instance: $INST"
# Step 2: Wait for initialization
sleep 2
-# Step 3: Navigate to report page (capture tabId)
+# Step 3: Navigate to report page
echo "Navigating to report page..."
-TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/navigate \
+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
-H "Content-Type: application/json" \
- -d '{"url":"https://example.com/report"}' | jq -r '.tabId')
+ -d '{"url":"https://example.com/report"}' | jq -r '.id')
echo "Tab: $TAB"
-# Step 4: Generate PDF with options using tabId
+# Step 4: Generate PDF with options
echo "Generating PDF..."
curl -s "http://localhost:9867/tabs/$TAB/pdf?landscape=true&displayHeaderFooter=true" \
-o report.pdf
echo "PDF saved: report.pdf"
-# Step 5: Take screenshot for preview using tabId
+# Step 5: Take screenshot for preview
echo "Taking preview screenshot..."
curl -s "http://localhost:9867/tabs/$TAB/screenshot" -o /tmp/report_preview.png
@@ -586,7 +586,7 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch \
-H "Content-Type: application/json" \
-d '{"mode":"headless"}' | jq -r '.id')
-curl -X POST http://localhost:9867/instances/$INST/navigate \
+curl -X POST http://localhost:9867/instances/$INST/tabs/open \
-d '{"url":"https://example.com"}' # Likely timeout or error
# CORRECT - wait for Chrome
@@ -611,16 +611,18 @@ INST=$(curl -s -X POST http://localhost:9867/instances/launch \
```bash
# WRONG - page changed, e5 no longer a button
-curl "http://localhost:9867/instances/$INST/snapshot" > snapshot1.json
+curl "http://localhost:9867/tabs/$TAB/snapshot" > snapshot1.json
# ... do something ...
-curl -X POST http://localhost:9867/instances/$INST/action \
- -d '{"kind":"click","ref":"e5"}'
+curl -X POST http://localhost:9867/tabs/$TAB/action \
+ -H "Content-Type: application/json" \
+ -d '{"action":"click","ref":"e5"}'
# CORRECT - get fresh snapshot before clicking
-curl "http://localhost:9867/instances/$INST/snapshot" > snapshot2.json
+curl "http://localhost:9867/tabs/$TAB/snapshot" > snapshot2.json
# Read refs from snapshot2.json
-curl -X POST http://localhost:9867/instances/$INST/action \
- -d '{"kind":"click","ref":"e7"}'
+curl -X POST http://localhost:9867/tabs/$TAB/action \
+ -H "Content-Type: application/json" \
+ -d '{"action":"click","ref":"e7"}'
```
### ❌ Mistake 5: Forgetting to stop instances