API Reference

Browserful provides two APIs: MCP Tools for AI agents via Claude Desktop and similar clients, and a REST API for direct integration.

Overview

Browserful uses a session-based architecture. Each session represents a browser tab that persists across requests. You can create multiple sessions, perform actions in them, and read their state.

Authentication

All API requests require an API key. Create one by running:

context-cloud init --name "my-workspace"

For the REST API, include your key in the X-API-Key header or as a Bearer token:

# Header
curl -H "X-API-Key: cb_your_api_key" https://api.browserful.com/api/v1/sessions

# Bearer token
curl -H "Authorization: Bearer cb_your_api_key" https://api.browserful.com/api/v1/sessions

Quick Start

Here's a complete example using the MCP tools:

# 1. Create a session and navigate to a page
create_session(url="https://news.ycombinator.com")
# Returns: session_id="abc123" + page state

# 2. Click on an article (element 5)
perform_action(session_id="abc123", action="click", element_id=5)
# Returns: new page state after click

# 3. Read the current state
read_session(session_id="abc123")
# Returns: URL, title, all interactive elements

# 4. Clean up
delete_session(session_id="abc123")

MCP Tools

These tools are exposed via the Model Context Protocol for use with Claude Desktop, Cursor, and other MCP clients.

list_sessions

Active sessions: 2

- [abc123] Hacker News
  URL: https://news.ycombinator.com/

- [def456] GitHub
  URL: https://github.com/

create_session

Session created: abc123

URL: https://news.ycombinator.com/
Title: Hacker News
Scroll: 0/1214 (viewport: 581px)

Interactive Elements:
  [0]<a href="...">Hacker News</a>
  [1]<a href="...">new</a>
  [2]<a href="...">past</a>
  ...

read_session

URL: https://news.ycombinator.com/
Title: Hacker News
Scroll: 0/1214 (viewport: 581px)

Interactive Elements:
  [0]<a href="...">Hacker News</a>
  [1]<a href="...">new</a>
  [2]<input type="text" placeholder="Search...">
  [3]<button>Login</button>
  ...

perform_action

# Navigate to a URL
perform_action(session_id="abc123", action="navigate", url="https://google.com")

# Click an element
perform_action(session_id="abc123", action="click", element_id=5)

# Type text into an input
perform_action(session_id="abc123", action="type", element_id=2, text="search query")

# Scroll down
perform_action(session_id="abc123", action="scroll", direction="down", amount=500)

# Take a screenshot
perform_action(session_id="abc123", action="screenshot")

delete_session

Session abc123 deleted.

REST API

The REST API provides the same functionality as the MCP tools, but for direct HTTP integration. All endpoints are prefixed with /api/v1.

Sessions

{
  "sessions": [
    {
      "id": "abc123",
      "url": "https://news.ycombinator.com/",
      "title": "Hacker News",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "last_action_at": "2024-01-15T10:35:00Z"
    }
  ],
  "count": 1
}

{
  "url": "https://news.ycombinator.com"  // optional
}

{
  "session": {
    "id": "abc123",
    "url": "https://news.ycombinator.com/",
    "title": "Hacker News",
    "status": "active"
  },
  "state": {
    "url": "https://news.ycombinator.com/",
    "title": "Hacker News",
    "elements": [...]
  }
}

{
  "session_id": "abc123",
  "state": {
    "url": "https://news.ycombinator.com/",
    "title": "Hacker News",
    "scroll_x": 0,
    "scroll_y": 0,
    "scroll_height": 1214,
    "viewport_height": 581,
    "elements": [
      {
        "id": 0,
        "tag": "a",
        "type": "link",
        "text": "Hacker News",
        "attributes": { "href": "..." }
      },
      ...
    ]
  }
}

Actions

{
  "action": "click",
  "params": {
    "element_id": 5
  }
}

{
  "deleted": "abc123"
}

Stats

{
  "total_sessions": 42,
  "active_sessions": 3,
  "total_actions": 1337
}

Page State

Every action returns the current page state. This includes all interactive elements the AI can interact with.

Errors

Errors are returned with appropriate HTTP status codes and a JSON body.

{
  "error": "Session not found: abc123"
}