Hanzi Browse Documentation

npx hanzi-browse setup

# Claude Code
claude mcp add browser -- npx -y hanzi-browse

# Cursor / Windsurf (mcp.json)
{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "hanzi-browse"]
    }
  }
}

"Go to Hacker News and tell me the top 3 stories right now"

Add browser automation to this project using the Hanzi Browse API. Read the codebase first, then ask me:

1. What browser task should Hanzi Browse automate? (e.g. "read patient chart", "fill out a form", "extract data from a web portal")
2. Where in the UI should the browser pairing flow go? (e.g. settings page, onboarding, a dedicated page)
3. Where should task results appear? (e.g. inline in the app, a chat interface, a dashboard)

Then build the integration using this API reference:

## Hanzi Browse API (base URL: https://api.hanzilla.co)

Auth: `Authorization: Bearer hic_live_...` header on all requests.

### Core flow
1. Create pairing token → show user a link → they connect their browser
2. Run tasks against their connected browser → poll for results
3. Show the answer in your app

### Endpoints

POST /v1/browser-sessions/pair
  Body: {"label": "User Name", "external_user_id": "your_user_id"}
  Returns: {"pairing_token": "hic_pair_...", "expires_in_seconds": 300}
  → Build a link: https://api.hanzilla.co/pair/{pairing_token}
  → User clicks it, their Chrome auto-pairs. Token expires in 5 min.

GET /v1/browser-sessions
  Returns: {"sessions": [{"id": "...", "status": "connected", "label": "..."}]}

POST /v1/tasks
  Body: {"task": "description", "browser_session_id": "...", "url": "optional", "context": "optional"}
  Returns: {"id": "task_id", "status": "running"}
  → task: what to do (max 10K chars). Be specific.
  → url: starting page (optional). If set, agent navigates there first.
  → context: extra info like form data, preferences (max 50K chars).

GET /v1/tasks/:id
  Returns: {"status": "running|complete|error", "answer": "...", "steps": 4}
  → Poll every 2s until status != "running". Typical task takes 10-60s.

POST /v1/tasks/:id/cancel
  → Stops a running task.

GET /v1/tasks/:id/steps
  Returns: {"steps": [{"step": 1, "status": "tool_use", "toolName": "navigate", ...}]}
  → Full execution log for debugging.

GET /v1/tasks/:id/screenshots/:step
  Returns: {"screenshot": "iVBORw0KGgo..."}
  → Base64 JPEG screenshot at a specific step. Prefix with data:image/jpeg;base64, to display.

GET /v1/billing/credits
  Returns: {"free_remaining": 20, "credit_balance": 0, "free_tasks_per_month": 20}

### Key details
- 20 free tasks/month, then $0.05 per completed task. Errors are free.
- Tasks timeout after 30 min. Use cancel to stop early.
- Browser sessions last 30 days and auto-reconnect.
- Two key types: secret (hic_live_) for server-side, publishable (hic_pub_) for client-side embed widget.
- POST /v1/tasks accepts optional webhook_url — Hanzi Browse POSTs the result to your URL on completion.
- Embed widget: <script src="https://browse.hanzilla.co/embed.js"></script> + HanziConnect.mount()
- The user needs the Hanzi Browse Chrome extension installed.
  Install link: https://chromewebstore.google.com/detail/iklpkemlmbhemkiojndpbhoakgikpmcd

### Example: Express + SDK (full integration)
  See: https://github.com/hanzili/hanzi-browse/tree/main/examples/partner-quickstart

Read the codebase to understand the stack and project structure, then ask me the 3 questions above. After I answer, build the full integration.

npm install @hanzi-browse/sdk

import { HanziClient } from '@hanzi-browse/sdk';

const client = new HanziClient({ apiKey: 'hic_live_...' });

// 1. Create a pairing token (give the URL to your user)
const { pairingToken } = await client.createPairingToken({
  label: 'Dr. Smith',
  externalUserId: 'user_123',
});
// Send user to: https://api.hanzilla.co/pair/{pairingToken}

// 2. Check for a connected session
const sessions = await client.listSessions();
const connected = sessions.find(s => s.status === 'connected');

// 3. Run a task (polls until complete, 5 min timeout)
const result = await client.runTask({
  browserSessionId: connected.id,
  task: 'Go to example.com and read the page title',
});
console.log(result.answer);
console.log(result.status); // 'complete' | 'error' | 'cancelled'

curl https://api.hanzilla.co/v1/api-keys \
  -H "Authorization: Bearer hic_live_your_key_here"

# Request
curl -X POST https://api.hanzilla.co/v1/api-keys \
  -H "Authorization: Bearer hic_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "production"}'

# Response (201)
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "hic_live_a1b2c3d4e5f6...",
  "name": "production",
  "workspace_id": "...",
  "_warning": "Save this key now. It will not be shown again."
}

# Create a publishable key
curl -X POST https://api.hanzilla.co/v1/api-keys \
  -H "Authorization: Bearer hic_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "frontend-widget", "type": "publishable"}'

# Request
curl -X POST https://api.hanzilla.co/v1/browser-sessions/pair \
  -H "Authorization: Bearer hic_live_..." \
  -H "Content-Type: application/json" \
  -d '{"label": "Dr. Smith", "external_user_id": "user_123"}'

# Response (201)
{
  "pairing_token": "hic_pair_a1b2c3...",
  "expires_at": 1710000000000,
  "expires_in_seconds": 300
}

# Response (200)
{
  "sessions": [
    {
      "id": "550e8400-...",
      "status": "connected",
      "label": "Dr. Smith",
      "external_user_id": "user_123",
      "connected_at": 1710000000000,
      "last_heartbeat": 1710000060000
    }
  ]
}

curl -X DELETE https://api.hanzilla.co/v1/browser-sessions/550e8400-... \
  -H "Authorization: Bearer hic_live_..."

# Request
curl -X POST https://api.hanzilla.co/v1/tasks \
  -H "Authorization: Bearer hic_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Read the patient chart on the current page",
    "browser_session_id": "550e8400-...",
    "url": "https://example.com/chart",
    "context": "Extract: name, medications, allergies"
  }'

# Response (201)
{
  "id": "task_abc123",
  "status": "running",
  "task": "Read the patient chart on the current page",
  "browser_session_id": "550e8400-..."
}

# Response (200) — completed task
{
  "id": "task_abc123",
  "status": "complete",
  "task": "Read the patient chart on the current page",
  "answer": "Patient: Jane Doe. Medications: Lisinopril 10mg...",
  "steps": 4,
  "usage": { "inputTokens": 12000, "outputTokens": 800, "apiCalls": 5 },
  "browser_session_id": "550e8400-...",
  "created_at": 1710000000000,
  "completed_at": 1710000120000
}

# Response (200)
{
  "steps": [
    {"step": 1, "status": "tool_use", "toolName": "navigate", "url": "https://example.com"},
    {"step": 2, "status": "tool_use", "toolName": "read_page"}
  ]
}

# Response (200)
{
  "screenshot": "iVBORw0KGgo..."
}

# Create a task with webhook
curl -X POST https://api.hanzilla.co/v1/tasks \
  -H "Authorization: Bearer hic_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Read the current page title",
    "browser_session_id": "550e8400-...",
    "webhook_url": "https://yourapp.com/api/hanzi-callback"
  }'

# Hanzi Browse POSTs to your URL on completion:
{
  "event": "task.completed",
  "task": {
    "id": "task_abc123",
    "status": "complete",
    "answer": "The page title is...",
    "steps": 3,
    "usage": { "inputTokens": 8000, "outputTokens": 500, "apiCalls": 4 },
    "created_at": 1710000000000,
    "completed_at": 1710000030000
  }
}

# Response (200)
{
  "totalInputTokens": 150000,
  "totalOutputTokens": 12000,
  "totalApiCalls": 45,
  "totalCostUsd": 0.082,
  "taskCount": 8
}

# Your backend generates the link:
curl -X POST https://api.hanzilla.co/v1/browser-sessions/pair \
  -H "Authorization: Bearer hic_live_..." \
  -H "Content-Type: application/json" \
  -d '{"label": "Dr. Smith", "external_user_id": "user_123"}'

# Response:
# { "pairing_token": "hic_pair_abc123...", "expires_in_seconds": 300 }

# Give your user this link:
# https://api.hanzilla.co/pair/hic_pair_abc123...

<script src="https://browse.hanzilla.co/embed.js"></script>
<div id="hanzi-connect"></div>
<script>
  HanziConnect.mount('#hanzi-connect', {
    apiKey: 'hic_pub_...',  // publishable key — safe for client-side
    purpose: 'read your EHR on your behalf',
    onConnected: (sessionId) => {
      // Send sessionId to your backend to run tasks
      fetch('/api/set-session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ sessionId }),
      });
    },
    onDisconnected: () => {
      // Browser disconnected — show re-pair UI
    },
  });
</script>

POST /v1/browser-sessions/pair
{
  "label": "Dr. Smith's browser",
  "external_user_id": "user_abc123"
}

# Error response format
{
  "error": "Browser session is not connected. The extension must be running and registered.",
  "request_id": "a1b2c3d4"
}