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

# Search documents

> Performs a case-insensitive substring search over the filename, caption, summary,
and tags of documents the caller can see, returning matches newest first. Visibility
rules are the same as the list endpoint (private, channel, and team scopes). Accepts
a required q query parameter and an optional limit (default 50, max 200); the
categories and tags rollup fields are returned empty for this endpoint. Requires the
documents:read scope.



## OpenAPI

````yaml GET /v1/api/documents/search
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/search:
    get:
      tags:
        - documents
      summary: Search documents
      description: >-
        Performs a case-insensitive substring search over the filename, caption,
        summary,

        and tags of documents the caller can see, returning matches newest
        first. Visibility

        rules are the same as the list endpoint (private, channel, and team
        scopes). Accepts

        a required q query parameter and an optional limit (default 50, max
        200); the

        categories and tags rollup fields are returned empty for this endpoint.
        Requires the

        documents:read scope.
      operationId: search_documents
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type:
              - integer
              - 'null'
            format: int64
      responses:
        '200':
          description: Matching documents
          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

````