webspeed 0.1.0

Python SDK for the Web Speed API — machine-readable maps of any web page for AI agents.

Web Speed — Python SDK

The machine-readable layer for the web. Give your AI agent a clean, structured map of any page — what it is, what's on it, and what it can do (search, add-to-cart, log in, paginate) — instead of dumping raw HTML or screenshots.

pip install webspeed

Quickstart

from webspeed import WebSpeed

ws = WebSpeed(api_key="wsp_...")          # or set the WEBSPEED_API_KEY env var

page = ws.map("https://example.com/product")
print(page["page_type"])                   # e.g. "product"
for action in page.get("actions", []):     # what the agent can do here
    print(action["intent"], action["selector"])   # e.g. "add_to_cart" "#add-btn"

That's the whole integration. Get a key at https://getwebspeed.io.

What you can call

ws.map(url, js=None, fresh=False, max_age=None)   # structured map of a page
ws.site_map(root_url, max_pages=25)               # crawl + combined map
ws.extract(html, base_url="")                     # map raw HTML you already have
ws.click(url, selector)                           # click, return the resulting map
ws.fill_and_submit(url, fields, submit_selector=None)
ws.submit_form(url, method="GET", fields={...})
ws.evaluate(url, js)                              # run JS, return the result
ws.inspect(url, selector)                         # structured data for a selector
ws.usage()                                        # credit balance + lifetime usage

js=None lets your account default decide; pass js=True for SPA/React sites.

Errors are typed

from webspeed import (
    WebSpeedError, AuthError, PaymentRequiredError, RateLimitError,
    FetchError, NetworkError,
)

try:
    page = ws.map("https://example.com")
except PaymentRequiredError as e:
    print("Out of credits / over plan limit:", e.code)   # e.g. "out_of_credits"
except FetchError as e:
    print("The target page couldn't be mapped (you're not charged):", e.code)
except WebSpeedError as e:
    print("API error:", e.status, e.message)

Transient errors (429 / 5xx / network) are retried automatically with backoff.

Use it as an agent tool

OpenAI / Anthropic function-calling:

from webspeed import WebSpeed, tools

ws = WebSpeed()
resp = openai_client.chat.completions.create(
    model="gpt-4o", messages=[...], tools=tools.openai_tools(),
)
# when the model calls a tool:
result = tools.call_tool(ws, tool_call.function.name,
                         json.loads(tool_call.function.arguments))

LangChain:

from webspeed import WebSpeed, tools
agent_tool = tools.make_langchain_tool(WebSpeed())   # pip install 'webspeed[langchain]'

Notes

• Auth is sent as a header (X-Web-Speed-Key) — your key never appears in a URL.
• Works with any MCP-less stack. (For MCP-native hosts like Claude/Cursor, add the Web Speed MCP server instead — same engine, zero code.)

Docs: https://api.getwebspeed.io/docs