> ## 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.

# Ask using the user's browser

> The dedicated browser path. The extension's "use my browser" button POSTs
here, PAT-authed (the same token the WebSocket uses). This is the ONLY entry
that runs an agent scoped to the local-browser tools (computer_*) + the
browser prompt - normal chat (web / Slack) never sees them, because
hq:computer is `default_enabled = FALSE` and the gateway only widens the
scope when this turn's `browser_session` flag is set. Runs synchronously and
returns the agent's reply.

## Requires a connected browser

Runs an agent turn against the caller's **own local browser** using the `computer_*` tools — the only entry point where those tools are enabled. It runs **synchronously** and returns the reply directly (no event stream).

<Warning>The user's browser extension must already hold a live [WebSocket connection](/api-reference/integrations/browser-connect). With no connected browser this returns `403` instead of running a turn that couldn't do anything.</Warning>

Pass `conversation_id` to continue a thread; omit it on the first ask to create one. Store the returned `conversation_id` and send it back on the next ask — the same pattern as the normal turn endpoints.


## OpenAPI

````yaml POST /v1/agent-browser/ask
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/ask:
    post:
      tags:
        - integrations
      summary: Ask using the user's browser
      description: >-
        The dedicated browser path. The extension's "use my browser" button
        POSTs

        here, PAT-authed (the same token the WebSocket uses). This is the ONLY
        entry

        that runs an agent scoped to the local-browser tools (computer_*) + the

        browser prompt - normal chat (web / Slack) never sees them, because

        hq:computer is `default_enabled = FALSE` and the gateway only widens the

        scope when this turn's `browser_session` flag is set. Runs synchronously
        and

        returns the agent's reply.
      operationId: browser_ask
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskReq'
        required: true
      responses:
        '200':
          description: >-
            The agent's reply, run against the caller's connected local browser
            (computer_* tools + browser prompt)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResp'
        '403':
          description: Missing/invalid PAT, or no live browser connection for this user
      security:
        - bearer_pat: []
components:
  schemas:
    AskReq:
      type: object
      required:
        - text
      properties:
        conversation_id:
          type:
            - string
            - 'null'
          format: uuid
          description: |-
            The conversation the user is viewing. The browser ask runs in THIS
            thread (per-thread browser session), so a new thread = a fresh agent
            session - no inherited stuck-session state. Omit only for legacy
            clients, which fall back to a deprecated stable per-user thread.
        text:
          type: string
          description: The user's request (e.g. "what is this page" / "fill in my name").
    AskResp:
      type: object
      required:
        - conversation_id
        - reply
      properties:
        conversation_id:
          type: string
          description: >-
            The conversation the ask ran in. The client stores this and sends it

            back as `conversation_id` on the next ask - exactly like the normal
            /

            fast turn endpoints. (First ask with no id creates the thread.)
        reply:
          type: string
          description: The agent's reply text.
  securitySchemes:
    bearer_pat:
      type: http
      scheme: bearer
      bearerFormat: hq_pat
      description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.'

````