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

> Returns the documents visible to the caller, newest first, along with the distinct
categories and tags across that visible set for building filter sidebars. Visibility
is enforced per request: team-scoped documents are seen by everyone in the
workspace, private ones only by their owner, and channel-scoped ones only by members
of that channel. Optional query parameters scope, category, channel, and tags
(comma-separated, matching documents that carry all listed tags) narrow the results,
and limit defaults to 50 and is capped at 200. Requires the documents:read scope.



## OpenAPI

````yaml GET /v1/api/documents
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/documents:
    get:
      tags:
        - documents
      summary: List documents
      description: >-
        Returns the documents visible to the caller, newest first, along with
        the distinct

        categories and tags across that visible set for building filter
        sidebars. Visibility

        is enforced per request: team-scoped documents are seen by everyone in
        the

        workspace, private ones only by their owner, and channel-scoped ones
        only by members

        of that channel. Optional query parameters scope, category, channel, and
        tags

        (comma-separated, matching documents that carry all listed tags) narrow
        the results,

        and limit defaults to 50 and is capped at 200. Requires the
        documents:read scope.
      operationId: list_documents
      parameters:
        - name: scope
          in: query
          description: Filter to one scope; omit for "everything I can see".
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: category
          in: query
          description: Filter to one category; omit for all.
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: tags
          in: query
          description: Filter to docs that have ALL listed tags. Comma-separated.
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: channel
          in: query
          description: Filter to one channel (only useful with `scope=channel`).
          required: false
          schema:
            type:
              - string
              - 'null'
            format: uuid
        - name: folder
          in: query
          description: Filter to documents directly inside this folder.
          required: false
          schema:
            type:
              - string
              - 'null'
            format: uuid
        - name: root
          in: query
          description: |-
            When true, only documents at the root of their scope (`folder_id IS
            NULL`). Ignored when `folder` is set.
          required: false
          schema:
            type:
              - boolean
              - 'null'
        - name: trash
          in: query
          description: |-
            When true, return the caller's Trash (their soft-deleted documents)
            instead of live ones. Overrides scope/folder/root filters.
          required: false
          schema:
            type:
              - boolean
              - 'null'
        - name: limit
          in: query
          description: Default 50, max 200.
          required: false
          schema:
            type:
              - integer
              - 'null'
            format: int64
      responses:
        '200':
          description: Documents visible to the caller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentsListResp'
      security:
        - bearer_pat:
            - documents:read
        - oauth2:
            - documents:read
components:
  schemas:
    DocumentsListResp:
      type: object
      required:
        - documents
        - categories
        - tags
      properties:
        categories:
          type: array
          items:
            type: string
          description: |-
            Distinct categories across the caller's visible set - drives
            the category-filter sidebar in the UI.
        documents:
          type: array
          items:
            $ref: '#/components/schemas/DocumentRow'
        tags:
          type: array
          items:
            type: string
          description: Distinct tags across the caller's visible set.
    DocumentRow:
      type: object
      required:
        - id
        - owner_user_id
        - scope
        - filename
        - content_type
        - size_bytes
        - sha256
        - tags
        - created_at
        - updated_at
        - download_url
        - is_owner
        - classification_status
        - auto_categorized
        - reference_numbers
        - profile_version
      properties:
        analysis_strategy:
          type:
            - string
            - 'null'
          description: |-
            Which classifier pipeline produced this row
            (TextOnly / VisionDirect / Hybrid / Image / PassThroughText).
            NULL on rows from before the smart-strategy slice.
        auto_categorized:
          type: boolean
          description: |-
            True once the classifier worker has written back the
            auto-derived category/summary/tags. Distinct from `category
            IS NOT NULL` because users can set categories manually too.
        caption:
          type:
            - string
            - 'null'
        category:
          type:
            - string
            - 'null'
        channel_id:
          type:
            - string
            - 'null'
          format: uuid
        channel_name:
          type:
            - string
            - 'null'
        classification_confidence:
          type:
            - number
            - 'null'
          format: float
          description: |-
            Self-reported model certainty (0..1) about the classification.
            UI flags rows below 0.6 as "needs review".
        classification_status:
          type: string
          description: |-
            `pending` / `queued` / `processing` / `completed` / `failed` /
            `skipped`. UI shows a pill until this hits `completed`.
        content_type:
          type: string
        created_at:
          type: string
          format: date-time
        document_date:
          type:
            - string
            - 'null'
          format: date-time
          description: |-
            What the doc refers to (issue / publication / statement date),
            not when we ingested it. NULL when not determinable.
        download_url:
          type: string
        entities:
          description: >-
            LLM-extracted entities ({person_names, company_names, identifiers,
            amounts, dates}).

            JSONB blob; UI renders selectively.
        filename:
          type: string
        folder_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Folder this document lives in. NULL = the root of its scope.
        id:
          type: string
          format: uuid
        is_owner:
          type: boolean
          description: |-
            True iff the caller is the document's owner. Drives "Delete /
            Edit" affordances in the UI.
        language:
          type:
            - string
            - 'null'
          description: ISO 639-1 code (`en`, `sv`, ...). NULL when not determinable.
        owner_display:
          type:
            - string
            - 'null'
        owner_user_id:
          type: string
          format: uuid
        profile_version:
          type: string
          description: |-
            Schema version - `hq-document-classify-v1` for legacy rows,
            `hq-document-classify-v2` once the classifier writes back
            the entities + dates surface.
        reference_numbers:
          type: array
          items:
            type: string
          description: Document-specific IDs (invoice/case/order numbers). Free-form.
        scope:
          type: string
        sha256:
          type: string
        size_bytes:
          type: integer
          format: int64
        source_ref:
          type:
            - string
            - 'null'
        source_url:
          type:
            - string
            - 'null'
        summary:
          type:
            - string
            - 'null'
        tags:
          type: array
          items:
            type: string
        updated_at:
          type: string
          format: date-time
  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

````