Complete REST API reference for WebUplink — all endpoints, schemas, and response codes.

API Reference

Base URL: https://api.webuplink.ai

All endpoints (except /health) require a Bearer token:

Authorization: Bearer wup_your_key_here

Endpoints

POST /v1/browse

Browse a page or execute tools. The unified endpoint for all interactions.

Request Body:

Field	Type	Required	Description
`url`	`string`	One of `url` or `session_id`	URL to browse (creates a new session)
`session_id`	`string`	One of `url` or `session_id`	Existing session to resume
`tool`	`string`	No	Single tool to execute
`params`	`object`	No	Parameters for the single tool
`tools`	`array`	No	Batch of tools to execute sequentially
`include_page_content`	`boolean`	No	Include detailed page content

Response (200):

Field	Type	Description
`session_id`	`string`	Session ID for follow-up requests
`url`	`string`	Current page URL (after redirects)
`title`	`string`	Page title
`summary`	`string`	AI-generated page summary (1-3 sentences)
`tools`	`Tool[]`	Available actions on this page
`page_content`	`string?`	Detailed page content (opt-in)
`results`	`ToolResult[]?`	Tool execution results (if tools were executed)
`stopped_reason`	`"navigation" \| "timeout"?`	Why batch stopped early

Response Headers:

Header	Description
`X-Cache`	`HIT` or `MISS` — PageMap cache status
`X-Usage-Action-Count`	Actions consumed this billing period
`X-Usage-Action-Limit`	Action limit for current plan
`X-Usage-Period-Start`	Billing period start (ISO 8601)

DELETE /v1/session/{id}

Close a browser session and free resources.

Response (200):

{ "status": "closed" }

Response (404):

{ "error": "SESSION_NOT_FOUND", "message": "Session not found or already expired" }

GET /v1/usage

Get exact cross-instance usage for the authenticated tenant. Requires a full API key (playground tokens cannot access this endpoint).

Response (200):

{
  "plan": "builder",
  "actions": { "used": 423, "limit": 1000 },
  "period": {
    "start": "2026-06-01T00:00:00.000Z",
    "end": "2026-07-01T00:00:00.000Z"
  },
  "billing": {
    "has_subscription": true,
    "portal_url": "/v1/billing/portal"
  }
}

GET /health

Unauthenticated health check for load balancer probes. Add ?deep=true for component-level checks.

Response (200):

{
  "status": "ok",
  "uptime_s": 3142,
  "active_sessions": 5,
  "checks": {
    "browserbase": "ok",
    "gemini": "ok",
    "firestore": "ok"
  }
}

Schemas

Tool

{
  "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" }
  ]
}

ToolResult

{
  "tool": "search_flights",
  "success": true,
  "error": null
}

API Reference

On this page