> ## 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 inbox messages

> Returns a paginated page of the caller's personal in-app inbox messages
(agent-delivered notifications such as scheduled-task digests), with each message's
title, body, source and read state, plus the total matching count, the
workspace-wide unread count for the nav badge, and the current page and page size.
Scoped to the caller's own inbox; admins do not see other users' inboxes. Supports
an unread-only filter, a case-insensitive free-text search over title, body and
schedule name, paging (page and page_size 1-100, default 25), and a sort of recent
(default) or oldest.



## OpenAPI

````yaml GET /v1/api/inbox
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/inbox:
    get:
      tags:
        - notifications
      summary: List inbox messages
      description: >-
        Returns a paginated page of the caller's personal in-app inbox messages

        (agent-delivered notifications such as scheduled-task digests), with
        each message's

        title, body, source and read state, plus the total matching count, the

        workspace-wide unread count for the nav badge, and the current page and
        page size.

        Scoped to the caller's own inbox; admins do not see other users'
        inboxes. Supports

        an unread-only filter, a case-insensitive free-text search over title,
        body and

        schedule name, paging (page and page_size 1-100, default 25), and a sort
        of recent

        (default) or oldest.
      operationId: list_inbox
      parameters:
        - name: unread
          in: query
          description: '`true` filters to read_at IS NULL.'
          required: false
          schema:
            type:
              - boolean
              - 'null'
        - name: q
          in: query
          description: |-
            Free-text filter: case-insensitive substring over the message
            title, body, and (for schedule digests) the schedule name.
          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 delivery first) or `oldest`.'
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: limit
          in: query
          description: |-
            Back-compat: an old SPA build calls `?limit=`. Used as the
            page_size fallback so the pre-pagination client still works.
          required: false
          schema:
            type:
              - integer
              - 'null'
            format: int64
      responses:
        '200':
          description: The caller's inbox page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxListResp'
      security:
        - bearer_pat: []
        - oauth2: []
components:
  schemas:
    InboxListResp:
      type: object
      required:
        - messages
        - unread_count
        - total
        - page
        - page_size
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/InboxMessageJson'
        page:
          type: integer
          format: int64
        page_size:
          type: integer
          format: int64
        total:
          type: integer
          format: int64
          description: Total rows matching the unread + search filter, before paging.
        unread_count:
          type: integer
          format: int64
          description: |-
            Unread across the whole inbox (drives the nav badge) - independent
            of the current page / search / sort.
    InboxMessageJson:
      type: object
      required:
        - id
        - source_kind
        - title
        - body_markdown
        - ui_strings
        - delivered_at
      properties:
        body_markdown:
          type: string
        delivered_at:
          type: string
          format: date-time
        id:
          type: string
          format: uuid
        read_at:
          type:
            - string
            - 'null'
          format: date-time
        schedule_id:
          type:
            - string
            - 'null'
          format: uuid
        schedule_name:
          type:
            - string
            - 'null'
          description: |-
            Set when source_kind = 'schedule_fire' - the originating
            schedule's user-facing label, so the inbox can group + link.
        source_kind:
          type: string
        title:
          type: string
        ui_strings: {}
  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

````