> ## 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. # List conversations > Returns a paginated list of the caller's conversations within their workspace, by default newest-activity first. Each row includes the conversation id, channel, mode, last-activity time, title, a short preview of the latest message, the associated agent, an optional attached app, a delivered-artifact count, and, for email threads, from/to/subject. Supports a free-text query over title/agent/preview, sort (recent, oldest, or title), a mode filter (fast vs standard, or all), and a channel filter (email is excluded by default unless explicitly requested). Workspace admins may pass view=admin to list every conversation in the workspace; the response echoes the viewing mode, total match count, and page window. ## OpenAPI ````yaml GET /v1/api/conversations 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/api/conversations: get: tags: - conversations summary: List conversations description: >- Returns a paginated list of the caller's conversations within their workspace, by default newest-activity first. Each row includes the conversation id, channel, mode, last-activity time, title, a short preview of the latest message, the associated agent, an optional attached app, a delivered-artifact count, and, for email threads, from/to/subject. Supports a free-text query over title/agent/preview, sort (recent, oldest, or title), a mode filter (fast vs standard, or all), and a channel filter (email is excluded by default unless explicitly requested). Workspace admins may pass view=admin to list every conversation in the workspace; the response echoes the viewing mode, total match count, and page window. operationId: list_conversations parameters: - name: view in: query description: |- `?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. required: false schema: type: - string - 'null' - name: q in: query description: |- 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. required: false schema: type: - string - 'null' - name: page in: query description: 1-based page index. Clamped to >= 1. required: false schema: type: - integer - 'null' format: int64 - name: page_size in: query description: Rows per page. Clamped to 1..=100; defaults to 25. required: false schema: type: - integer - 'null' format: int64 - name: sort in: query description: |- `recent` (default, newest activity first), `oldest`, or `title` (A-Z, untitled convs sink to the end). required: false schema: type: - string - 'null' - name: mode in: query description: |- 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. required: false schema: type: - string - 'null' - name: channel_kind in: query description: |- 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. required: false schema: type: - string - 'null' responses: '200': description: Conversation list (paginated) content: application/json: schema: $ref: '#/components/schemas/ConvListResp' security: - bearer_pat: - conversations:read - oauth2: - conversations:read components: schemas: ConvListResp: type: object required: - conversations - viewing_as - total - page - page_size properties: conversations: type: array items: $ref: '#/components/schemas/ConvListItem' page: type: integer format: int64 description: |- Echo of the resolved page + page size (after clamping) so the SPA renders the same window it asked for. page_size: type: integer format: int64 total: type: integer format: int64 description: |- Total rows matching the (search + ACL) filter, before LIMIT/OFFSET - drives the SPA's pagination control. viewing_as: type: string description: |- `"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. ConvListItem: type: object required: - id - channel_kind - mode - last_activity_at - agent - artifact_count properties: agent: $ref: '#/components/schemas/ConvAgent' app: oneOf: - type: 'null' - $ref: '#/components/schemas/ConvApp' artifact_count: type: integer format: int64 description: |- How many delivered artifacts this conversation has - the delete modal uses it to show + gate the "also delete delivered files" checkbox (hidden when 0). channel_kind: type: string email_from: type: - string - 'null' description: >- Latest email message on this thread (from / to / subject). Only set for email-channel conversations; NULL elsewhere. Backs the Email > Threads list so it shows the same From/To/Subject as every other email row. email_subject: type: - string - 'null' email_to: type: - array - 'null' items: type: string id: type: string format: uuid last_activity_at: type: string format: date-time last_text: type: - string - 'null' mode: type: string description: |- `standard` (sandbox agent thread) or `fast` (no-VM quick ask). Lets the home "Continue" list (which requests `mode=all`) brand fast rows as quick asks instead of the bound agent's persona. title: type: - string - 'null' description: |- Worker-derived short label (4-7 words). NULL until the title.derive worker has processed this conv; the SPA falls back to `last_text` in that case, rendered muted so the user reads it as a placeholder. ConvAgent: type: object required: - display_name properties: avatar_url: type: - string - 'null' display_name: type: string id: type: - string - 'null' format: uuid description: '`None` for an agentless thread (fast/quick lane, email Quick-reply).' slug: type: - string - 'null' ConvApp: type: object required: - id - slug - state properties: id: type: string format: uuid slug: type: string state: type: string securitySchemes: bearer_pat: type: http scheme: bearer bearerFormat: hq_pat description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.' oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://app.hq.zone/v1/oauth/authorize tokenUrl: https://api.hq.zone/v1/oauth/token refreshUrl: https://api.hq.zone/v1/oauth/token scopes: admin: Administer the workspace (users, settings, integrations) agents:read: View the agents in your workspace agents:write: Create and configure agents billing:read: View usage and billing information conversations:read: Read your conversations and their messages conversations:write: Start conversations and send messages on your behalf documents:read: Read your documents library documents:write: Upload and manage documents in your library memory:read: Read what the assistant remembers about you memory:write: Correct or delete what the assistant remembers schedules:read: View your scheduled tasks schedules:write: Create and manage scheduled tasks tables:read: Read your tables and their rows tables:write: Create tables and add, edit, or delete rows ````