BrowserGateway
REST API

REST API Reference

Every HTTP endpoint the gateway exposes, grouped by resource, auto-generated from source.

The gateway exposes three categories of HTTP endpoints:

  • Action endpoints (/v1/screenshot, /v1/content, /v1/scrape): one-shot browser actions, no client code needed.
  • Control endpoints (/v1/providers, /v1/config, /v1/profiles, /v1/replays, /v1/sessions, /v1/status): manage the gateway itself.
  • Compat + dashboard (/health, /json/version, /web/*): Chrome-compat endpoints and the dashboard.
  • MCP (/mcp, /mcp/setup.md): the MCP server for AI agents over HTTP. See MCP.

When BG_TOKEN is set, every /v1/* endpoint on this page requires either an Authorization: Bearer <BG_TOKEN> header or the dashboard's session cookie. A ?token= query parameter is not accepted here, because query strings end up in the access logs of any proxy in front of the gateway. The WebSocket endpoint /v1/connect still takes ?token=, since CDP clients cannot set headers on a WebSocket handshake. /health and /json/version are always public. /mcp accepts the token only as an Authorization: Bearer header. /mcp/setup.md needs no token, so an agent can read the setup steps before it has one; both are refused from a foreign browser Origin, and, when BG_TOKEN is unset, from any non-loopback Host not listed in BG_ALLOWED_HOSTS.

Requests that change something (POST, PUT, PATCH, DELETE) must send Content-Type: application/json when they carry a body, or the gateway answers 415. A request arriving with a Sec-Fetch-Site: cross-site header, which browsers add when one site calls another, is answered 403.

All endpoints

MethodPathResource
GET/v1/auth/infoAuth Info
GET/v1/configConfig
PUT/v1/configConfig
PUT/v1/config/strategyConfig
POST/v1/config/validateConfig
POST/v1/contentContent
GET/healthHealth
GET/json/versionChrome Compat
POST/mcpMCP
GET/mcpMCP
DELETE/mcpMCP
GET/mcp/setup.mdMCP
GET/v1/profilesProfiles
DELETE/v1/profiles/:idProfiles
GET/v1/profiles/:idProfiles
GET/v1/profiles/:id/exportProfiles
POST/v1/profiles/createProfiles
POST/v1/profiles/disableProfiles
POST/v1/profiles/importProfiles
POST/v1/profiles/setupProfiles
GET/v1/providersProviders
POST/v1/providersProviders
DELETE/v1/providers/:idProviders
PUT/v1/providers/:idProviders
GET/v1/providers/:id/capabilitiesProviders
POST/v1/providers/:id/capabilities/revalidateProviders
POST/v1/providers/:id/testProviders
POST/v1/providers/probeProviders
GET/v1/replaysReplays
DELETE/v1/replays/:idReplays
GET/v1/replays/:idReplays
GET/v1/replays/:id/frames/:frameReplays
GET/v1/replays/:id/manifestReplays
GET/v1/replays/:id/parts/:partReplays
POST/v1/scrapeScrape
POST/v1/screenshotScreenshot
GET/v1/sessionsSessions
GET/v1/sessions/parkedSessions
GET/v1/statusStatus
GET/webDashboard
GET/web/*Dashboard
POST/web/authDashboard
GET/web/auth/checkDashboard
POST/web/logoutDashboard
GET/v1/webhookswebhooks
POST/v1/webhookswebhooks
DELETE/v1/webhooks/:indexwebhooks
PUT/v1/webhooks/:indexwebhooks
POST/v1/webhooks/testwebhooks

By resource

  • Auth Info: Report whether the gateway requires an auth token.
  • Config: Read, validate, and update gateway.yml over HTTP.
  • Content: Extract page content (HTML, markdown, or text) from any URL.
  • Health: Liveness probe. Always public, no auth required.
  • Chrome Compat: Chrome-compatible /json/version endpoint.
  • Profiles: Create, export, import, delete stored browser profiles.
  • Providers: CRUD for provider entries in gateway.yml.
  • Replays: List, fetch, delete session replay frames.
  • Scrape: Structured data extraction from a page.
  • Screenshot: One-shot screenshot of any URL, no client code required.
  • Sessions: Read-only view of active WebSocket sessions.
  • Status: Aggregate gateway status (providers, sessions, pool).
  • Dashboard: Dashboard static files + login endpoints.
  • webhooks:

Live Playground

An in-browser CDP viewer at /web/playground. Click into a live browser session from the dashboard, exercise a page, and optionally save the resulting state to a profile.

Auth Info

Report whether the gateway requires an auth token.

On this page

All endpointsBy resource