Skip to content

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.json
index 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, ...}"
}
]
}