Skip to main content

Relay HTTP Control API

The relay service exposes a small authenticated HTTP API for direct browser-tool control of a connected Vibe Browser extension.

This API is intended for server-side automations that already know the extension uuid and secret and want a simple request/response surface without speaking the raw WebSocket protocol.

Authentication​

Pass the extension secret using either:

  • Authorization: Bearer <secret>
  • X-Vibe-Secret: <secret>

If the UUID is unknown, the relay returns 404. If the UUID is known but the extension is currently offline, tool endpoints return 409. If the secret is wrong, the relay returns 401.

Endpoints​

Assume base URL https://relay.api.vibebrowser.app.

Get extension status​

curl -H "Authorization: Bearer $VIBE_BROWSER_SECRET" \
  "https://relay.api.vibebrowser.app/api/v1/extensions/$VIBE_BROWSER_UUID/status"

Returns connection state, tool cache status, pending request count, and extension version.

List tools​

Return cached tools:

curl -H "Authorization: Bearer $VIBE_BROWSER_SECRET" \
  "https://relay.api.vibebrowser.app/api/v1/extensions/$VIBE_BROWSER_UUID/tools"

Refresh tools from the live extension first:

curl -H "Authorization: Bearer $VIBE_BROWSER_SECRET" \
  "https://relay.api.vibebrowser.app/api/v1/extensions/$VIBE_BROWSER_UUID/tools?refresh=1"

Call one browser tool​

curl -X POST \
  -H "Authorization: Bearer $VIBE_BROWSER_SECRET" \
  -H "Content-Type: application/json" \
  "https://relay.api.vibebrowser.app/api/v1/extensions/$VIBE_BROWSER_UUID/call-tool" \
  -d '{
    "name": "navigate_to_url",
    "arguments": {"url": "https://example.com"}
  }'

Snapshot tools​

curl -X POST \
  -H "Authorization: Bearer $VIBE_BROWSER_SECRET" \
  -H "Content-Type: application/json" \
  "https://relay.api.vibebrowser.app/api/v1/extensions/$VIBE_BROWSER_UUID/call-tool" \
  -d '{
    "name": "take_a11y_snapshot",
    "arguments": {}
  }'

Notes​

  • This API exposes browser tools, not the internal copilot chat/task loop.
  • Tool names and argument schemas come from the connected extension.
  • Call tools?refresh=1 before the first tool call in a new session when the tool surface may have changed.

CDP Compatibility Facade​

The relay also exposes a small CDP-shaped compatibility facade for remote clients that prefer Chrome DevTools style verbs.

This is not a raw CDP tunnel. It is a narrow allowlisted mapping onto Vibe browser tools.

Version​

curl -H "Authorization: Bearer $VIBE_BROWSER_SECRET" \
  "https://relay.api.vibebrowser.app/api/v1/extensions/$VIBE_BROWSER_UUID/cdp/json/version"

List targets​

curl -H "Authorization: Bearer $VIBE_BROWSER_SECRET" \
  "https://relay.api.vibebrowser.app/api/v1/extensions/$VIBE_BROWSER_UUID/cdp/json/list"

Execute a CDP-compatible command​

curl -X POST \
  -H "Authorization: Bearer $VIBE_BROWSER_SECRET" \
  -H "Content-Type: application/json" \
  "https://relay.api.vibebrowser.app/api/v1/extensions/$VIBE_BROWSER_UUID/cdp/execute" \
  -d '{
    "id": 1,
    "method": "Page.navigate",
    "params": {
      "pageId": 123,
      "url": "https://example.com"
    }
  }'

Supported methods​

  • Browser.getVersion
  • Target.getTargets
  • Target.createTarget
  • Target.closeTarget
  • Page.navigate
  • Page.reload
  • Page.captureScreenshot
  • Runtime.evaluate

Notes​

  • Use Authorization: Bearer <secret> or X-Vibe-Secret for auth; query-string tokens are intentionally not supported.
  • Target.getTargets and cdp/json/list are backed by list_pages.
  • Page.captureScreenshot is backed by take_screenshot.
  • Runtime.evaluate is backed by evaluate_script and returns JSON-RPC style results.