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

# Get a conversation

> Returns metadata for a single conversation the caller can access, including its
title, mode (standard or fast), originating channel, surface type, whether it is
read-only, the associated agent (id, slug, display name, avatar), and a directory of
participants referenced in the thread. Scoped to the caller's own workspace and the
conversations they participate in. Workspace admins may pass view=admin to read
another member's conversation, which is reflected in the returned viewing_as field.
Returns 404 if the conversation is not found.



## OpenAPI

````yaml GET /v1/api/conversations/{id}
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/{id}:
    get:
      tags:
        - conversations
      summary: Get a conversation
      description: >-
        Returns metadata for a single conversation the caller can access,
        including its

        title, mode (standard or fast), originating channel, surface type,
        whether it is

        read-only, the associated agent (id, slug, display name, avatar), and a
        directory of

        participants referenced in the thread. Scoped to the caller's own
        workspace and the

        conversations they participate in. Workspace admins may pass view=admin
        to read

        another member's conversation, which is reflected in the returned
        viewing_as field.

        Returns 404 if the conversation is not found.
      operationId: get_conversation
      parameters:
        - name: id
          in: path
          description: Conversation id
          required: true
          schema:
            type: string
            format: uuid
        - 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 metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvMetaResp'
        '404':
          description: Not found
      security:
        - bearer_pat:
            - conversations:read
        - oauth2:
            - conversations:read
components:
  schemas:
    ConvMetaResp:
      type: object
      required:
        - conversation_id
        - agent
        - viewing_as
        - mode
        - channel_kind
        - surface
        - read_only
        - participants
      properties:
        agent:
          $ref: '#/components/schemas/AgentLite'
        channel_kind:
          type: string
          description: |-
            Origin channel: `web` / `slack` / `teams` / `schedule`. Studio
            renders `schedule` threads read-only (a record of a scheduled run,
            not a live chat) and offers "start a fresh conversation" instead.
        conversation_id:
          type: string
          format: uuid
        mode:
          type: string
          description: |-
            `standard` (sandbox agent thread) or `fast` (no-VM "ask" thread).
            Studio shows a "Convert to agent" affordance on fast threads.
        participants:
          description: >-
            Directory of every user the thread references (message authors +

            `<@U…>` mentions), keyed by UID -> { name, avatar_url }. The SPA
            renders

            `<@U…>` mention chips from this. `{}` for single-party (web/DM)
            convs.
        read_only:
          type: boolean
          description: >-
            True when this conversation is read-only from web/extension: a

            multi-party Slack/Teams channel thread (owned by Slack/Teams). The
            SPA

            disables the composer + shows a "happening in the channel" hint. The

            API enforces this independently (prepare_turn refuses such turns).
        surface:
          type: string
          description: |-
            Conversation surface: `channel` (multi-party Slack/Teams thread) /
            `dm` / `web` / `extension`. Drives `read_only`.
        title:
          type:
            - string
            - 'null'
          description: |-
            Display label for the conversation. User-set (Studio rename) or
            auto-derived (title.derive worker); NULL until one exists, in
            which case the SPA falls back to a message preview / "Untitled".
        viewing_as:
          type: string
          description: |-
            `"participant"` (default) or `"admin"` when the caller
            elevated via `?view=admin` AND is `workspace_users.is_admin`.
            The SPA renders an "Admin view" banner when this is `admin`
            so the user knows they're looking at someone else's conv.
    AgentLite:
      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):
            no agent owns it. `display_name` is then a synthesized label ("Q" /
            "Quick reply"), not a stored agent.
        slug:
          type:
            - string
            - 'null'
  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

````