Hanzi 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 API. Read the codebase first, then ask me:

1. What browser task should Hanzi 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 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/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.
- The user needs the Hanzi Chrome extension installed.
  Install link: https://chromewebstore.google.com/detail/iklpkemlmbhemkiojndpbhoakgikpmcd

### Example: Express + HTML (minimal)
  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.

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."
}

# 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
    }
  ]
}

# 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)
{
  "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...

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"
}