Skip to main content

​
Introduction

PinchTab provides a REST API for programmatic browser control. The API runs on port 9867 and allows you to manage browser instances, control tabs, navigate pages, and automate user interactions.
All API endpoints communicate with Chrome via the DevTools Protocol (CDP). PinchTab handles the complexity of CDP and exposes a simple REST interface.

​
Base URL

http://localhost:9867
All API requests use this base URL. The server listens on port 9867 by default.

​
Architecture

PinchTab uses an instance-scoped architecture:

PinchTab Server

HTTP server on port 9867 that manages all instances and routes requests

Chrome Instances

Independent Chrome processes, each with its own profile and tabs

Profiles

Chrome user data directories that store cookies, history, and settings

Tabs

Individual browser pages within an instance
HTTP Client
    │
    ↓
┌────────────────────────────┐
│  PinchTab Server :9867     │
│  - Instance management     │
│  - Profile management      │
│  - Request routing         │
└────────┬───────────────────┘
         │ DevTools Protocol
         ├──────────────────┐
         ↓                  ↓
    ┌─────────┐        ┌─────────┐
    │ Chrome 1│        │ Chrome 2│
    │ headed  │        │headless │
    │ Tab 1   │        │ Tab 1   │
    │ Tab 2   │        └─────────┘
    └─────────┘

​
API Categories

CategoryEndpointsPurpose
Instances/instances/*Create, list, and manage browser instances
Profiles/profiles/*Manage browser profiles (user data directories)
Tabs/tabs/*List and manage tabs across instances
Navigation/tabs/{id}/navigateNavigate tabs to URLs
Actions/tabs/{id}/action, /tabs/{id}/actionsClick, type, fill, press, hover, scroll
Snapshot/tabs/{id}/snapshotGet accessibility tree (page structure)
Evaluation/tabs/{id}/evaluateExecute JavaScript in pages
Screenshots/tabs/{id}/screenshotCapture page screenshots
PDF/tabs/{id}/pdfExport pages to PDF
Cookies/tabs/{id}/cookiesGet and set cookies
Stealth/stealth/status, /fingerprint/rotateStealth mode and fingerprint rotation
Metrics/metrics, /tabs/{id}/metricsPerformance and memory metrics
Downloads/tabs/{id}/download, /tabs/{id}/uploadFile download and upload handling
Screencast/screencastLive tab preview streaming

​
Quick Start Example

Here’s a complete workflow that creates an instance, navigates to a page, takes a snapshot, and captures a screenshot: 
#!/bin/bash
BASE="http://localhost:9867"

# 1. Start an instance
INST=$(curl -s -X POST $BASE/instances/start \
  -H "Content-Type: application/json" \
  -d '{"mode":"headed"}' | jq -r '.id')

echo "Instance: $INST"

# 2. Open a tab with URL
TAB=$(curl -s -X POST "$BASE/instances/$INST/tabs/open" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' | jq -r '.tabId')

echo "Tab: $TAB"

# 3. Get page structure
curl -s "$BASE/tabs/$TAB/snapshot?filter=interactive" | jq '.nodes[] | {ref, role, name}'

# 4. Take screenshot
curl -s "$BASE/tabs/$TAB/screenshot?quality=90" > screenshot.jpg

echo "Screenshot saved to screenshot.jpg"

# 5. Cleanup
curl -s -X POST "$BASE/instances/$INST/stop"

​
Response Format

All API responses use JSON format (except binary endpoints like screenshots and PDFs).

​
Success Response

{
  "tabId": "tab_abc12345",
  "url": "https://example.com",
  "title": "Example Domain"
}

​
Error Response

{
  "error": "tab not found",
  "statusCode": 404
}

​
HTTP Status Codes

CodeMeaningWhen
200OKSuccessful GET/POST request
201CreatedResource created (instance, profile)
204No ContentSuccessful DELETE
400Bad RequestInvalid JSON, missing required fields
404Not FoundInstance, profile, or tab not found
423LockedTab is locked by another owner
500Internal Server ErrorChrome error or server issue

​
Authentication

Authentication is optional. If configured, use Bearer token authentication.
Set the BRIDGE_TOKEN environment variable when starting the server: 
BRIDGE_TOKEN=your_secret_token pinchtab
Include the token in API requests: 
curl -H "Authorization: Bearer your_secret_token" \
  http://localhost:9867/instances

​
Rate Limiting

PinchTab does not enforce rate limits by default. For production use, consider implementing rate limiting at the reverse proxy level.

​
ID Formats

PinchTab uses hash-based IDs for security:
  • Profiles: prof_XXXXXXXX (8-character hash)
  • Instances: inst_XXXXXXXX (8-character hash)
  • Tabs: tab_XXXXXXXX (8-character hash)
Raw Chrome DevTools Protocol target IDs are never exposed in the API for security reasons.

​
SDKs and Libraries

PinchTab uses a standard REST API. You can use any HTTP client: 
curl -X POST http://localhost:9867/instances/start \
  -H "Content-Type: application/json" \
  -d '{"mode":"headed"}'

​
Next Steps

Authentication

Learn about API authentication and security

Instances API

Create and manage browser instances

Navigation

Navigate tabs to URLs

Actions API

Automate clicks, typing, and interactions

​
Design Principles

  1. Instance-Scoped — All operations target a specific instance
  2. Stateful — Cookies, history, and sessions persist within instances
  3. Multi-Agent Safe — Each agent can use its own isolated instance
  4. Profile-Based — Each instance uses a Chrome profile for state persistence
  5. Hash-Based IDs — Secure IDs prevent guessing and information leakage

​
Health Check

Verify the server is running: 
curl http://localhost:9867/health
Response: 
{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 3600
}

Build docs developers (and LLMs) love

Get started for freeTalk to us