Using Mapped Sites

What Are Mapped Sites?

BabelWrap can map any website into a set of typed tools. Once mapped, your agent calls functions like linkedin_search_jobs(query="python developer") instead of manually navigating page by page. Mapped sites are stored in a public catalog — if someone already mapped a site, you can use it for free.

Browsing the Catalog

Browse and search the catalog to find sites that are already mapped.

import httpx

BASE = "https://api.babelwrap.com/v1"

# Browse all available sites
resp = httpx.get(f"{BASE}/catalog")
for site in resp.json()["sites"]:
    print(f"{site['domain']} — {site['recipe_count']} tools")

# Search for a specific domain
resp = httpx.get(f"{BASE}/catalog/search", params={"domain": "linkedin"})
for site in resp.json()["results"]:
    print(f"{site['domain']} ({site['recipe_count']} tools)")

# Browse catalog
curl -s https://api.babelwrap.com/v1/catalog | jq '.sites[] | {domain, recipe_count}'

# Search by domain
curl -s "https://api.babelwrap.com/v1/catalog/search?domain=linkedin" | jq .results

Viewing a Site's Tools

Once you find a site, get its available tools:

HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Get tools for a mapped site
resp = httpx.get(f"{BASE}/sites/{site_id}/tools", headers=HEADERS)
for tool in resp.json()["tools"]:
    params = ", ".join(f"{p['name']}: {p['type']}" for p in tool["params"])
    print(f"{tool['name']}({params}) — {tool['description']}")

Executing Tools via REST API

Execute a generated tool by posting parameters to its endpoint:

import httpx, os

API_KEY = os.environ["BABELWRAP_API_KEY"]
BASE = "https://api.babelwrap.com/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Execute a mapped site tool
resp = httpx.post(
    f"{BASE}/sites/{site_id}/tools/linkedin_search_jobs",
    headers=HEADERS,
    json={"params": {"query": "python developer", "location": "New York"}},
    timeout=60.0,
)
result = resp.json()

if result["success"]:
    print(f"Found results in {result['duration_ms']}ms ({result['steps_executed']} steps)")
    for job in result["data"]:
        print(f"  {job['title']} at {job['company']} — {job['location']}")
else:
    print(f"Error: {result['error']}")

curl -s -X POST https://api.babelwrap.com/v1/sites/$SITE_ID/tools/linkedin_search_jobs \
  -H "Authorization: Bearer $BABELWRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params": {"query": "python developer", "location": "New York"}}' | jq .

Using Tools via MCP

When a site is mapped, its tools automatically appear in your MCP client alongside the 16 built-in BabelWrap tools. No extra configuration needed.

For example, in Claude Desktop, you might see:

• babelwrap_navigate (built-in)
• babelwrap_click (built-in)
• linkedin_search_jobs (generated from mapped site)
• linkedin_view_job (generated from mapped site)

Your agent can call the generated tools directly:

"Search LinkedIn for Python developer jobs in New York"

Claude would call linkedin_search_jobs(query="python developer", location="New York") and return the results — no manual navigation needed.

Requesting a New Mapping

If the site you need isn't in the catalog, you can request a new mapping:

1. Check if the site exists — call POST /v1/sites/map with the start URL. If it's already mapped, you get an immediate response.
2. Complete payment — if the site is new, you receive a checkout URL. Complete the $10 payment via Stripe.
3. Wait for mapping — the pipeline runs asynchronously (typically 2–5 minutes). Check status via GET /v1/sites/orders.

# 1. Check if the site exists (may return immediately if already mapped)
resp = httpx.post(
    f"{BASE}/sites/map",
    headers=HEADERS,
    json={"start_url": "https://example.com"},
)
data = resp.json()

if data.get("status") == "ready":
    # Site already in catalog!
    print(f"Site ready with tools: {data['tools']}")
elif data.get("status") == "pending_payment":
    # New site — complete checkout
    print(f"Complete payment at: {data['checkout_url']}")
    print(f"Cost: ${data['amount_cents'] / 100:.2f}")

Authentication with Mapped Sites

If the site requires login, provide auth cookies when requesting a mapping:

# Provide auth cookies when requesting a mapping
resp = httpx.post(
    f"{BASE}/sites/map",
    headers=HEADERS,
    json={
        "start_url": "https://example.com",
        "auth_cookies": [
            {
                "name": "session_id",
                "value": "abc123",
                "domain": ".example.com",
                "path": "/",
            }
        ],
    },
)

The mapper will:

• Use these cookies during exploration
• Discover and store a login recipe if one exists
• Inject cookies into tool executions automatically
• Re-authenticate when cookies expire (Layer 4 auth)

Tips

• Check the catalog first — always call POST /v1/sites/map before manual exploration. If the site is mapped, you save significant time.
• Use MCP for agents — generated tools via MCP are the most natural interface for AI agents.
• Self-healing — mapped sites auto-correct when websites update. Major overhauls may need a re-map.
• Execution time — generated tools typically take 3–10 seconds (they run a full browser flow).