Skip to main content
POST
/
v1
/
agent-browser
/
ask
Ask using the user's browser
curl --request POST \
  --url https://api.hq.zone/v1/agent-browser/ask \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "<string>",
  "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{
  "conversation_id": "<string>",
  "reply": "<string>"
}

​
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).
The user’s browser extension must already hold a live WebSocket connection. With no connected browser this returns 403 instead of running a turn that couldn’t do anything.
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.

Authorizations

​
Authorization
string
header
required

Personal Access Token. Send as Authorization: Bearer hq_pat_....

Body

application/json
​
text
string
required

The user's request (e.g. "what is this page" / "fill in my name").

​
conversation_id
string<uuid> | null

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.

Response

The agent's reply, run against the caller's connected local browser (computer_* tools + browser prompt)

​
conversation_id
string
required

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
string
required

The agent's reply text.