> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hq.zone/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser connect

## WebSocket endpoint

This is **not** a plain HTTP `GET` — it's a **WebSocket upgrade**. It's the channel the HQ browser extension dials out on so a remote agent can drive the user's local browser; you don't normally call it yourself.

* **Subprotocol:** `hq-agent-browser.v1`.
* **Auth:** a browser can't set an `Authorization` header on a WebSocket, so the PAT rides in `Sec-WebSocket-Protocol` as `hq-pat.<token>`, alongside the subprotocol.
* **Heartbeat:** \~20 s application-level ping (also keeps idle proxies open).
* **Presence:** one live connection per user. The server relays `computer.*` commands down this socket and awaits each result.

```text theme={null}
GET /v1/agent-browser/connect
Upgrade: websocket
Sec-WebSocket-Protocol: hq-agent-browser.v1, hq-pat.hq_pat_xxx
```

Once connected, the agent reaches this browser via [Ask using the user's browser](/api-reference/integrations/browser-ask).


## OpenAPI

````yaml GET /v1/agent-browser/connect
openapi: 3.1.0
info:
  title: HQ API
  description: >-
    Public HTTP API for HQ. Authenticate with a Personal Access Token
    (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an
    OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's
    behalf. Both grant from the same resource:action scope vocabulary; an
    endpoint's required scope is listed under its `security`.
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  version: 1.0.0
servers:
  - url: https://api.hq.zone
    description: HQ API (production)
security: []
tags:
  - name: me
    description: The signed-in user's own account
  - name: conversations
    description: Conversations and their messages
  - name: documents
    description: The content-addressed documents library
  - name: schedules
    description: Scheduled prompts and recurring tasks
  - name: agents
    description: Agents, their skills and integrations
  - name: memory
    description: What the assistant remembers (L5 governance)
  - name: tokens
    description: Personal Access Token management
  - name: billing
    description: Usage and billing
  - name: notifications
    description: In-app notification center
  - name: admin
    description: Workspace administration
  - name: integrations
    description: Workspace integrations (Slack, MCP, skills)
  - name: onboarding
    description: New-workspace onboarding wizard
  - name: auth
    description: Sign-in, sessions, and OAuth
paths:
  /v1/agent-browser/connect:
    get:
      tags:
        - integrations
      operationId: browser_connect
      responses:
        '101':
          description: >-
            WebSocket upgrade. The HQ extension dials out here (PAT in
            Sec-WebSocket-Protocol as `hq-pat.<token>`) to receive `computer.*`
            commands. Frames are the WebDriver-BiDi-shaped
            local_browser_protocol (see docs/local-browser-control.md); OpenAPI
            cannot describe the per-frame protocol.
      security:
        - bearer_pat: []
components:
  securitySchemes:
    bearer_pat:
      type: http
      scheme: bearer
      bearerFormat: hq_pat
      description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.'

````