Documentation

Everything you need to integrate BabelWrap into your AI agents and applications.

Getting Started

Introduction

What is BabelWrap, how it works, how it compares to alternatives, and pricing.

Quickstart

Create a session, navigate, and extract data in 3 API calls. Includes Python, JavaScript, and curl examples.

The Snapshot Format

Understand BabelWrap's core innovation: structured, LLM-readable page representations.

API Reference

REST API Reference

Complete endpoint documentation for sessions, actions, usage, and health check.

MCP Server

Set up BabelWrap as an MCP server for Claude Desktop, Cursor, or any MCP-compatible agent.

Site Mapping

Map any website into typed tools your agent can call directly. Understand the pipeline, recipes, self-healing, and the public catalog.

Sites & Catalog API

Complete endpoint reference for site mapping, tool execution, and the public catalog.

Using Mapped Sites

Step-by-step guide: browse the catalog, execute generated tools, and request new site mappings.

Guides

Practical Guides

Step-by-step walkthroughs: login flows, form submission, data extraction, and multi-step checkout.

Code Examples

Real-world automation scenarios with full working code in Python, JavaScript, and curl.

Architecture

How BabelWrap works under the hood: the proxy layer, Playwright engine, session manager, and element resolver.

Quick Reference

Base URL

https://api.babelwrap.com/v1

Authentication

All API requests (except /v1/health) require a Bearer token:

Authorization: Bearer bw_your_api_key_here

Endpoints at a Glance

Method	Path	Description
POST	`/v1/sessions`	Create a browser session
GET	`/v1/sessions/:id`	Get session info
DEL	`/v1/sessions/:id`	Close session
POST	`/v1/sessions/:id/navigate`	Navigate to URL
POST	`/v1/sessions/:id/snapshot`	Read current page
POST	`/v1/sessions/:id/click`	Click element
POST	`/v1/sessions/:id/fill`	Fill input field
POST	`/v1/sessions/:id/submit`	Submit form
POST	`/v1/sessions/:id/extract`	Extract structured data
POST	`/v1/sessions/:id/screenshot`	Take screenshot
POST	`/v1/sessions/:id/press`	Press keyboard key
POST	`/v1/sessions/:id/upload`	Upload file to input
POST	`/v1/sessions/:id/hover`	Hover over element
POST	`/v1/sessions/:id/back`	Navigate back
POST	`/v1/sessions/:id/forward`	Navigate forward
POST	`/v1/sessions/:id/scroll`	Scroll page
POST	`/v1/sessions/:id/wait_for`	Wait for condition
POST	`/v1/sessions/:id/batch`	Execute multiple actions
GET	`/v1/sessions/:id/pages`	List open pages/tabs
POST	`/v1/sessions/:id/switch_page`	Switch to different tab
POST	`/v1/sessions/:id/cookies`	Add cookies to session
GET	`/v1/sessions/:id/history`	Get action history
GET	`/v1/usage`	Get usage stats
GET	`/v1/health`	Health check (no auth)
Site Mapping & Catalog
POST	`/v1/sites/map`	Map a website
POST	`/v1/sites/:id/refresh`	Re-map a site
GET	`/v1/sites`	List mapped sites
GET	`/v1/sites/:id`	Get site details
GET	`/v1/sites/:id/tools`	List generated tools
POST	`/v1/sites/:id/tools/:name`	Execute generated tool
GET	`/v1/catalog`	Browse public catalog
GET	`/v1/catalog/search`	Search catalog by domain
GET	`/v1/catalog/:id`	Get catalog entry

MCP Tools

Tool	Description
`babelwrap_new_session`	Create a new browser session
`babelwrap_close_session`	Close and clean up a session
`babelwrap_navigate`	Navigate to a URL
`babelwrap_snapshot`	Get current page state
`babelwrap_click`	Click element by description
`babelwrap_fill`	Fill input field
`babelwrap_submit`	Submit form
`babelwrap_extract`	Extract structured data
`babelwrap_screenshot`	Take screenshot
`babelwrap_press`	Press keyboard key (Enter, Tab, etc.)
`babelwrap_scroll`	Scroll page up or down
`babelwrap_hover`	Hover over element by description
`babelwrap_upload`	Upload file to file input
`babelwrap_wait_for`	Wait for text, element, or URL change
`babelwrap_back`	Navigate back in history
`babelwrap_forward`	Navigate forward in history
`babelwrap_list_pages`	List open pages (tabs/popups)
`babelwrap_switch_page`	Switch to a different tab or popup

Mapped sites generate additional dynamic tools beyond the 18 built-in tools above. For example, a mapped LinkedIn site adds linkedin_search_jobs, linkedin_view_job, etc. These appear in your MCP client alongside the built-in tools. See Site Mapping for details.