Core Concepts
Understand the mental model behind WebUplink — PageMaps, tools, sessions, and actions.
Core Concepts
WebUplink is built around a simple mental model: browse → observe → act → repeat. This page explains the key concepts.
PageMap
When you browse a page, WebUplink returns a PageMap — a structured representation of everything the agent can see and do. A PageMap contains:
- Summary — A 1-3 sentence overview of the page for quick decisions
- Tools — Available actions the agent can perform
- Page Content (opt-in) — A detailed, curated breakdown of the page's content
The summary and tools are generated in a single LLM call, so observation is always fast.
Tools
Tools are the actions available on a page. Each tool has:
| Field | Description |
|---|---|
name | Machine-readable identifier (e.g. search_hotels) |
description | Human-readable explanation of what the tool does |
params | Array of parameter definitions with names and descriptions |
Tools are page-specific — they change based on what's currently visible. A search results page has filter_by_price and select_product; a checkout page has fill_shipping and place_order.
{
"name": "search_flights",
"description": "Search for flights with the given criteria",
"params": [
{ "name": "origin", "description": "Departure city or airport code" },
{ "name": "destination", "description": "Arrival city or airport code" },
{ "name": "departure_date", "description": "Departure date (YYYY-MM-DD)" }
]
}Sessions
A session is a persistent browser context. When you browse a URL, WebUplink creates a session with a real browser (via Browserbase). The session persists cookies, auth state, and navigation history across multiple requests.
Lifecycle
| State | Description |
|---|---|
| Creating | Browser session being provisioned |
| Ready | Waiting for the next browse call |
| Busy | Processing a request (only one at a time) |
| Expired | Cleaned up and no longer usable |
Timeouts
- Idle timeout: 2 minutes of no requests → auto-expire
- Hard cap: 15 minutes total → auto-expire regardless of activity
Always call closeSession() when done to free resources immediately.
Actions (Billing Unit)
An action is the billing unit in WebUplink. Each POST /v1/browse call consumes one action, regardless of whether it's an observe-only request or includes tool execution.
| Plan | Monthly Actions | Tool Execution | Price |
|---|---|---|---|
| Free | 100 | Browse-only | $0 |
| Builder | 1,000 | ✅ | $29/mo |
| Pro | 5,000 | ✅ | $79/mo |
Builder and Pro plans allow overage beyond the action limit. Free plans hard-cap at 100 actions.
Caching
WebUplink caches PageMap responses to avoid redundant LLM calls. Cache behavior depends on your plan:
| Plan | Cache Writes | Cache Reads |
|---|---|---|
| Free | ✅ | ❌ |
| Builder | ✅ | ✅ |
| Pro | ✅ | ✅ |
Cache hits are indicated by the X-Cache: HIT response header. Cached responses don't consume additional LLM tokens but still count as one action for billing.