Skip to main content
GET
/
v1
/
api
/
conversations
List conversations
curl --request GET \
  --url https://api.hq.zone/v1/api/conversations \
  --header 'Authorization: Bearer <token>'
{
  "conversations": [
    {
      "agent": {
        "display_name": "<string>",
        "avatar_url": "<string>",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "slug": "<string>"
      },
      "artifact_count": 123,
      "channel_kind": "<string>",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "last_activity_at": "2023-11-07T05:31:56Z",
      "mode": "<string>",
      "app": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "slug": "<string>",
        "state": "<string>"
      },
      "email_from": "<string>",
      "email_subject": "<string>",
      "email_to": [
        "<string>"
      ],
      "last_text": "<string>",
      "title": "<string>"
    }
  ],
  "page": 123,
  "page_size": 123,
  "total": 123,
  "viewing_as": "<string>"
}

Authorizations

​
Authorization
string
header
required

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

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

Conversation list (paginated)

​
conversations
object[]
required
​
page
integer<int64>
required

Echo of the resolved page + page size (after clamping) so the SPA renders the same window it asked for.

​
page_size
integer<int64>
required
​
total
integer<int64>
required

Total rows matching the (search + ACL) filter, before LIMIT/OFFSET - drives the SPA's pagination control.

​
viewing_as
string
required

"participant" (default) or "admin" - tells the SPA whether to render the "Admin view" banner. Admin view is audited via conversation_access_audit; the SPA showing the banner is the visible half of that observability.