High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
refactor: migrate from instance-scoped to tab-centric API endpoints
Mariob394de8bf1e7
diff --git a/docs/references/api-reference.json b/docs/references/api-reference.jsonindex 2d007d54..4f24067b 100644--- a/docs/references/api-reference.json+++ b/docs/references/api-reference.json@@ -1,7 +1,7 @@{"version": "2.0","generated": "auto-merged from code + user metadata",- "count": 63,+ "count": 60,"endpoints": [{"method": "GET",@@ -99,32 +99,6 @@"parameters": "None","payload": "N/A (GET request)"},- {- "method": "GET",- "path": "/instances/{id}/cookies",- "handler": "proxyToInstance",- "description": "Instance tab cookies",- "curl": true,- "examples": {},- "tldr": "Set cookies in instance tab",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/instances/abc123/cookies -H \"Content-Type: application/json\" -d '{\"tabId\":\"tab-1\",\"cookies\":[{\"name\":\"session\",\"value\":\"abc123\"}]}'",- "parameters": "id (string, path, required): Instance ID",- "payload": "{\"tabId\":\"tab-1\",\"cookies\":[{\"name\":\"session\",\"value\":\"abc123\"}]}"- },- {- "method": "GET",- "path": "/instances/{id}/download",- "handler": "proxyToInstance",- "description": "Download from instance",- "curl": true,- "examples": {},- "tldr": "Download a resource from instance tab",- "cli": false,- "curlExample": "curl \"http://localhost:9867/instances/abc123/download?url=https://example.com/file.pdf\"",- "parameters": "url (string, query, required): URL to download",- "payload": "N/A (GET request)"- },{"method": "GET","path": "/instances/{id}/logs",@@ -138,19 +112,6 @@"parameters": "limit (int, query, optional, default: 100)","payload": "N/A (GET request)"},- {- "method": "GET",- "path": "/instances/{id}/pdf",- "handler": "proxyToInstance",- "description": "PDF from instance",- "curl": true,- "examples": {},- "tldr": "Export a tab as PDF from instance",- "cli": false,- "curlExample": "curl \"http://localhost:9867/instances/abc123/pdf?tabId=tab-1\" > page.pdf",- "parameters": "tabId (string, query, required)",- "payload": "N/A (GET request)"- },{"method": "GET","path": "/instances/{id}/proxy/screencast",@@ -177,58 +138,6 @@"parameters": "tabId (string, query, required), format (string, optional, default: \"webm\")","payload": "N/A (GET request)"},- {- "method": "GET",- "path": "/instances/{id}/screenshot",- "handler": "proxyToInstance",- "description": "Screenshot of instance tab",- "curl": true,- "examples": {},- "tldr": "Take a screenshot of a tab in instance",- "cli": false,- "curlExample": "curl \"http://localhost:9867/instances/abc123/screenshot?tabId=tab-1\" > screenshot.jpg",- "parameters": "tabId (string, query, required), quality (int, query, optional, default: 80)",- "payload": "N/A (GET request)"- },- {- "method": "GET",- "path": "/instances/{id}/snapshot",- "handler": "proxyToInstance",- "description": "Snapshot of instance tab",- "curl": true,- "examples": {},- "tldr": "Get accessibility tree of a tab in instance",- "cli": false,- "curlExample": "curl \"http://localhost:9867/instances/abc123/snapshot?tabId=tab-1&filter=interactive\"",- "parameters": "tabId (string, query, required), filter (string, query, optional: \"interactive\" or \"all\", default: \"all\")",- "payload": "N/A (GET request)"- },- {- "method": "GET",- "path": "/instances/{id}/tabs",- "handler": "proxyToInstance",- "description": "List instance tabs",- "curl": true,- "examples": {},- "tldr": "List all tabs in an instance",- "cli": false,- "curlExample": "curl \"http://localhost:9867/instances/abc123/tabs\"",- "parameters": "id (string, path, required): Instance ID",- "payload": "N/A (GET request)"- },- {- "method": "GET",- "path": "/instances/{id}/text",- "handler": "proxyToInstance",- "description": "Text from instance tab",- "curl": true,- "examples": {},- "tldr": "Extract text content from a tab in instance",- "cli": false,- "curlExample": "curl \"http://localhost:9867/instances/abc123/text?tabId=tab-1\"",- "parameters": "tabId (string, query, required)",- "payload": "N/A (GET request)"- },{"method": "GET","path": "/pdf",@@ -357,60 +266,6 @@"curl": true,"examples": {}},- {- "method": "POST",- "path": "/instances/launch",- "handler": "handleLaunchByName",- "description": "Launch instance",- "curl": true,- "examples": {},- "tldr": "Launch/create a new Chrome instance with a profile",- "cli": true,- "curlExample": "curl -X POST http://localhost:9867/instances/launch -H \"Content-Type: application/json\" -d '{\"mode\":\"headless\",\"port\":9868}'",- "parameters": "mode (string, body, optional: \"headed\" or \"headless\", default: \"headless\"), port (int, body, optional, auto-assigned if omitted)",- "payload": "{\"mode\":\"headless\"} or {\"mode\":\"headed\",\"port\":9868}",- "cliExample": "pinchtab instance launch --mode headed --port 9868",- "defaults": "headless=true, port=auto-assigned; returns {id, profileName, port, headless, status}"- },- {- "method": "POST",- "path": "/instances/{id}/action",- "handler": "proxyToInstance",- "description": "Action on instance tab",- "curl": true,- "examples": {},- "tldr": "Perform action (click, type, fill) on element in instance tab",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/instances/abc123/action -H \"Content-Type: application/json\" -d '{\"tabId\":\"tab-1\",\"kind\":\"click\",\"ref\":\"e5\"}'",- "parameters": "id (string, path, required): Instance ID",- "payload": "{\"tabId\":\"tab-1\",\"kind\":\"click\",\"ref\":\"e5\"} or {\"tabId\":\"tab-1\",\"kind\":\"type\",\"ref\":\"e3\",\"text\":\"hello\"}"- },- {- "method": "POST",- "path": "/instances/{id}/actions",- "handler": "proxyToInstance",- "description": "Batch actions in instance",- "curl": true,- "examples": {},- "tldr": "Perform multiple actions in sequence on instance tab",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/instances/abc123/actions -H \"Content-Type: application/json\" -d '[{\"kind\":\"click\",\"ref\":\"e5\"},{\"kind\":\"type\",\"ref\":\"e3\",\"text\":\"hello\"}]'",- "parameters": "id (string, path, required): Instance ID",- "payload": "[{\"kind\":\"click\",\"ref\":\"e5\"},{\"kind\":\"type\",\"ref\":\"e3\",\"text\":\"input\"}]"- },- {- "method": "POST",- "path": "/instances/{id}/cookies",- "handler": "proxyToInstance",- "description": "Instance tab cookies",- "curl": true,- "examples": {},- "tldr": "Set cookies in instance tab",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/instances/abc123/cookies -H \"Content-Type: application/json\" -d '{\"tabId\":\"tab-1\",\"cookies\":[{\"name\":\"session\",\"value\":\"abc123\"}]}'",- "parameters": "id (string, path, required): Instance ID",- "payload": "{\"tabId\":\"tab-1\",\"cookies\":[{\"name\":\"session\",\"value\":\"abc123\"}]}"- },{"method": "POST","path": "/instances/{id}/ensure-chrome",@@ -424,32 +279,6 @@"parameters": "id (string, path, required): Instance ID","payload": "N/A"},- {- "method": "POST",- "path": "/instances/{id}/evaluate",- "handler": "proxyToInstance",- "description": "JS eval in instance",- "curl": true,- "examples": {},- "tldr": "Execute JavaScript in instance tab",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/instances/abc123/evaluate -H \"Content-Type: application/json\" -d '{\"tabId\":\"tab-1\",\"code\":\"document.title\"}'",- "parameters": "id (string, path, required): Instance ID",- "payload": "{\"tabId\":\"tab-1\",\"code\":\"document.title\"}"- },- {- "method": "POST",- "path": "/instances/{id}/navigate",- "handler": "proxyToInstance",- "description": "Navigate in instance",- "curl": true,- "examples": {},- "tldr": "Navigate a tab in instance to URL",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/instances/abc123/navigate -H \"Content-Type: application/json\" -d '{\"tabId\":\"tab-1\",\"url\":\"https://example.com\"}'",- "parameters": "id (string, path, required): Instance ID",- "payload": "{\"tabId\":\"tab-1\",\"url\":\"https://example.com\",\"timeout\":30000}"- },{"method": "POST","path": "/instances/{id}/stop",@@ -463,58 +292,6 @@"parameters": "id (string, path, required): Instance ID","payload": "N/A"},- {- "method": "POST",- "path": "/instances/{id}/tab",- "handler": "proxyToInstance",- "description": "Manage instance tab",- "curl": true,- "examples": {},- "tldr": "Create or manage tab in instance",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/instances/abc123/tab -H \"Content-Type: application/json\" -d '{\"action\":\"new\",\"url\":\"https://example.com\"}'",- "parameters": "id (string, path, required): Instance ID",- "payload": "{\"action\":\"new\",\"url\":\"https://example.com\"} or {\"action\":\"close\",\"tabId\":\"tab-1\"}"- },- {- "method": "POST",- "path": "/instances/{id}/tab/lock",- "handler": "proxyToInstance",- "description": "Lock instance tab",- "curl": true,- "examples": {},- "tldr": "Lock a tab in instance (prevent concurrent access)",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/instances/abc123/tab/lock -H \"Content-Type: application/json\" -d '{\"tabId\":\"tab-1\"}'",- "parameters": "id (string, path, required): Instance ID",- "payload": "{\"tabId\":\"tab-1\"}"- },- {- "method": "POST",- "path": "/instances/{id}/tab/unlock",- "handler": "proxyToInstance",- "description": "Unlock instance tab",- "curl": true,- "examples": {},- "tldr": "Unlock a tab in instance",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/instances/abc123/tab/unlock -H \"Content-Type: application/json\" -d '{\"tabId\":\"tab-1\"}'",- "parameters": "id (string, path, required): Instance ID",- "payload": "{\"tabId\":\"tab-1\"}"- },- {- "method": "POST",- "path": "/instances/{id}/upload",- "handler": "proxyToInstance",- "description": "Upload to instance",- "curl": true,- "examples": {},- "tldr": "Upload a file to instance tab",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/instances/abc123/upload -F \"file=@/path/to/file.txt\" -F \"tabId=tab-1\" -F \"ref=e3\"",- "parameters": "id (string, path, required): Instance ID",- "payload": "FormData with file, tabId, ref"- },{"method": "POST","path": "/navigate",@@ -710,6 +487,200 @@"payload": "{\"name\":\"chrome-work\",\"sourcePath\":\"/path/to/chrome/profile\",\"description\":\"Imported from Chrome\"}","defaults": "Copies Chrome profile directory to ~/.pinchtab/profiles/","examples": {}+ },+ {+ "method": "POST",+ "path": "/tabs/{id}/navigate",+ "handler": "proxyToTab",+ "description": "Navigate tab to URL",+ "tldr": "Navigate tab to URL",+ "cli": true,+ "curl": true,+ "cliExample": "pinchtab tab navigate <tabId> https://example.com",+ "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/navigate -d '{\"url\":\"https://example.com\",\"timeout\":30}'",+ "parameters": "url (string, body, required); timeout (int, optional); blockImages (bool, optional); blockAds (bool, optional)",+ "payload": "{\"url\":\"https://example.com\",\"timeout\":30}",+ "defaults": "timeout=30s; returns {url, title, status}"+ },+ {+ "method": "GET",+ "path": "/tabs/{id}/snapshot",+ "handler": "proxyToTab",+ "description": "Get page snapshot/structure tree",+ "tldr": "Get page structure",+ "cli": true,+ "curl": true,+ "cliExample": "pinchtab tab snapshot <tabId> -i -c",+ "curlExample": "curl 'http://localhost:9867/tabs/tab_abc/snapshot?interactive=true&compact=true'",+ "parameters": "interactive (bool, query, optional); compact (bool, query, optional); diff (bool, query, optional); depth (int, query, optional); maxTokens (int, query, optional)",+ "payload": "N/A (GET)",+ "defaults": "returns {elements: [], tree: {...}, meta: {...}}"+ },+ {+ "method": "GET",+ "path": "/tabs/{id}/screenshot",+ "handler": "proxyToTab",+ "description": "Take screenshot of tab",+ "tldr": "Take screenshot",+ "cli": true,+ "curl": true,+ "cliExample": "pinchtab tab screenshot <tabId> -o screenshot.png -q 85",+ "curlExample": "curl 'http://localhost:9867/tabs/tab_abc/screenshot?quality=85' > screenshot.png",+ "parameters": "format (string, query, optional: 'png' or 'jpeg'); quality (int, query, optional, 1-100)",+ "payload": "N/A (GET)",+ "defaults": "format=png; returns binary image data"+ },+ {+ "method": "POST",+ "path": "/tabs/{id}/action",+ "handler": "proxyToTab",+ "description": "Execute single action on tab",+ "tldr": "Execute action",+ "cli": true,+ "curl": true,+ "cliExample": "pinchtab tab click <tabId> e5",+ "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/action -d '{\"kind\":\"click\",\"ref\":\"e5\"}'",+ "parameters": "kind (string, body, required: click|type|press|fill|hover|scroll|select|focus); ref (string, conditional); text (string, conditional); key (string, conditional)",+ "payload": "{\"kind\":\"click\",\"ref\":\"e5\"}",+ "defaults": "returns {kind, result, error}"+ },+ {+ "method": "POST",+ "path": "/tabs/{id}/actions",+ "handler": "proxyToTab",+ "description": "Execute multiple actions on tab",+ "tldr": "Execute multiple actions",+ "cli": true,+ "curl": true,+ "cliExample": "pinchtab tab actions <tabId> --json '[{\"kind\":\"click\",\"ref\":\"e5\"}]'",+ "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/actions -d '{\"actions\":[{\"kind\":\"click\",\"ref\":\"e5\"},{\"kind\":\"type\",\"ref\":\"e12\",\"text\":\"hello\"}]}'",+ "parameters": "actions (array, body, required): array of action objects",+ "payload": "{\"actions\":[{\"kind\":\"click\",\"ref\":\"e5\"},{\"kind\":\"type\",\"ref\":\"e12\",\"text\":\"hello\"}]}",+ "defaults": "returns {results: [...]}"+ },+ {+ "method": "GET",+ "path": "/tabs/{id}/text",+ "handler": "proxyToTab",+ "description": "Extract visible text from tab",+ "tldr": "Get page text",+ "cli": true,+ "curl": true,+ "cliExample": "pinchtab tab text <tabId>",+ "curlExample": "curl 'http://localhost:9867/tabs/tab_abc/text'",+ "parameters": "raw (bool, query, optional): return raw innerText instead of structured",+ "payload": "N/A (GET)",+ "defaults": "returns {text: \"...\", elements: [...]}"+ },+ {+ "method": "POST",+ "path": "/tabs/{id}/evaluate",+ "handler": "proxyToTab",+ "description": "Evaluate JavaScript in tab",+ "tldr": "Run JavaScript",+ "cli": true,+ "curl": true,+ "cliExample": "pinchtab tab eval <tabId> 'document.title'",+ "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/evaluate -d '{\"expression\":\"document.title\"}'",+ "parameters": "expression (string, body, required); await (bool, body, optional)",+ "payload": "{\"expression\":\"document.querySelectorAll('a').length\"}",+ "defaults": "returns {result: any, type: string}"+ },+ {+ "method": "GET",+ "path": "/tabs/{id}/pdf",+ "handler": "proxyToTab",+ "description": "Export tab as PDF",+ "tldr": "Export as PDF",+ "cli": true,+ "curl": true,+ "cliExample": "pinchtab tab pdf <tabId> -o output.pdf --landscape",+ "curlExample": "curl 'http://localhost:9867/tabs/tab_abc/pdf?landscape=true&scale=1.0' > output.pdf",+ "parameters": "landscape (bool, query, optional); scale (float, query, optional); margins (object, query, optional); pageRanges (string, query, optional)",+ "payload": "N/A (GET)",+ "defaults": "returns binary PDF data"+ },+ {+ "method": "GET",+ "path": "/tabs/{id}/cookies",+ "handler": "proxyToTab",+ "description": "Get cookies for tab",+ "tldr": "Get cookies",+ "cli": true,+ "curl": true,+ "cliExample": "pinchtab tab cookies <tabId>",+ "curlExample": "curl 'http://localhost:9867/tabs/tab_abc/cookies'",+ "parameters": "none",+ "payload": "N/A (GET)",+ "defaults": "returns [{name, value, domain, path, ...}]"+ },+ {+ "method": "POST",+ "path": "/tabs/{id}/cookies",+ "handler": "proxyToTab",+ "description": "Set/delete cookies for tab",+ "tldr": "Set cookies",+ "cli": false,+ "curl": true,+ "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/cookies -d '{\"action\":\"set\",\"cookies\":[{\"name\":\"key\",\"value\":\"val\"}]}'",+ "parameters": "action (string, body, required: 'set' or 'delete'); cookies (array, body, required)",+ "payload": "{\"action\":\"set\",\"cookies\":[{\"name\":\"session\",\"value\":\"abc123\",\"domain\":\".example.com\"}]}",+ "defaults": "returns {set: [...], deleted: [...]}"+ },+ {+ "method": "POST",+ "path": "/tabs/{id}/lock",+ "handler": "proxyToTab",+ "description": "Lock tab for exclusive access",+ "tldr": "Lock tab",+ "cli": true,+ "curl": true,+ "cliExample": "pinchtab tab lock <tabId> --owner my-agent --ttl 60",+ "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/lock -d '{\"owner\":\"my-agent\",\"ttl\":60}'",+ "parameters": "owner (string, body, required); ttl (int, body, required)",+ "payload": "{\"owner\":\"agent-1\",\"ttl\":60}",+ "defaults": "returns {locked: true, owner, expiresAt}"+ },+ {+ "method": "POST",+ "path": "/tabs/{id}/unlock",+ "handler": "proxyToTab",+ "description": "Unlock tab",+ "tldr": "Unlock tab",+ "cli": true,+ "curl": true,+ "cliExample": "pinchtab tab unlock <tabId> --owner my-agent",+ "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/unlock -d '{\"owner\":\"my-agent\"}'",+ "parameters": "owner (string, body, required)",+ "payload": "{\"owner\":\"agent-1\"}",+ "defaults": "returns {unlocked: true}"+ },+ {+ "method": "GET",+ "path": "/tabs/{id}/locks",+ "handler": "proxyToTab",+ "description": "Check lock status",+ "tldr": "Check lock status",+ "cli": true,+ "curl": true,+ "cliExample": "pinchtab tab locks <tabId>",+ "curlExample": "curl 'http://localhost:9867/tabs/tab_abc/locks'",+ "parameters": "none",+ "payload": "N/A (GET)",+ "defaults": "returns {locked: bool, owner?, expiresAt?}"+ },+ {+ "method": "POST",+ "path": "/tabs/{id}/fingerprint/rotate",+ "handler": "proxyToTab",+ "description": "Rotate browser fingerprint",+ "tldr": "Rotate fingerprint",+ "cli": false,+ "curl": true,+ "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/fingerprint/rotate",+ "parameters": "none",+ "payload": "N/A (POST, empty body)",+ "defaults": "returns {rotated: true, userAgent, ...}"}]}