Skip to main content
GET
/
v1
/
api
/
conversations
/
{id}
/
surfaces
List conversation surfaces
curl --request GET \
  --url https://api.hq.zone/v1/api/conversations/{id}/surfaces \
  --header 'Authorization: Bearer <token>'
{
  "surfaces": [
    {
      "auth_mode": "<string>",
      "declared_port": 123,
      "dev_url": "<string>",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "run_mode": "<string>",
      "slug": "<string>",
      "state": "<string>",
      "url": "<string>"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
id
string<uuid>
required

Conversation id

Query Parameters

​
view
string | null

?view=admin opts into "see every conv in tenant", honored only when the caller is workspace_users.is_admin = true. Falls back silently to participant view otherwise so a crafted URL from a non-admin doesn't leak the existence of admin mode via a 403.

​
q
string | null

Free-text filter. Case-insensitive substring match over the conv title, the agent display name, and the latest-message preview (the three things a row shows). Empty/blank = no filter.

​
page
integer<int64> | null

1-based page index. Clamped to >= 1.

​
page_size
integer<int64> | null

Rows per page. Clamped to 1..=100; defaults to 25.

​
sort
string | null

recent (default, newest activity first), oldest, or title (A-Z, untitled convs sink to the end).

​
mode
string | null

Which lane: fast lists only the no-VM "ask" threads; anything else (default) lists the standard agent threads. The two lanes are surfaced as separate tabs in Studio.

​
channel_kind
string | null

Optional channel filter. When set to a known channel kind (e.g. email) the list returns ONLY threads of that kind - this backs the admin Email > Threads tab. When unset, the default list EXCLUDES email so external-correspondence threads don't bleed into the main Home conversation list (they live under the Email section instead). Unknown values yield an empty set rather than an error.

Response

200 - application/json

Surfaces (apps) attached to the conversation

​
surfaces
object[]
required