> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trynia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Unified search

> Single search endpoint with a mode discriminator.



## OpenAPI

````yaml /openapi-docs.yaml post /search
openapi: 3.1.0
info:
  title: Nia AI API
  version: 1.1.0
  description: >-
    Nia AI API provides a single, consistent `sources` resource for all indexed
    content.


    ## Core Resources


    **Sources** (`/sources`)

    - `repository`

    - `documentation`

    - `research_paper`

    - `huggingface_dataset`

    - `local_folder`


    **Search** (`/search`)

    - `mode`: query | web | deep | universal


    Legacy endpoints are deprecated and will be removed in a future version.
    Prefer `/sources` and `/search` for new integrations.
servers:
  - url: https://apigcp.trynia.ai/v2
    description: Production API
  - url: http://localhost:8000/v2
    description: Local development
security:
  - ApiKeyAuth: []
tags:
  - name: Auth
    description: API-first signup, login, and API key bootstrapping
  - name: Sources
    description: >-
      Unified source management (repositories, documentation, papers, datasets,
      local folders)
  - name: Search
    description: Unified search endpoint with mode discriminator
  - name: Context Sharing
    description: Cross-agent context management and retrieval
  - name: Categories
    description: Category management for organizing indexed sources
  - name: GitHub Search
    description: Live GitHub search and repository exploration
  - name: Advisor
    description: Context-aware code advisor against indexed documentation
  - name: Dependencies
    description: Dependency analysis and documentation subscription
  - name: Usage
    description: Usage tracking and bulk operations
paths:
  /search:
    post:
      tags:
        - Search
      summary: Unified search
      description: Single search endpoint with a mode discriminator.
      operationId: unified_search_v2_v2_search_post
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/QuerySearchRequest'
                - $ref: '#/components/schemas/WebSearchRequestWithMode'
                - $ref: '#/components/schemas/DeepResearchRequestWithMode'
                - $ref: '#/components/schemas/UniversalSearchRequestWithMode'
              title: Body
              discriminator:
                propertyName: mode
                mapping:
                  query:
                    $ref: '#/components/schemas/QuerySearchRequest'
                  web:
                    $ref: '#/components/schemas/WebSearchRequestWithMode'
                  deep:
                    $ref: '#/components/schemas/DeepResearchRequestWithMode'
                  universal:
                    $ref: '#/components/schemas/UniversalSearchRequestWithMode'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    QuerySearchRequest:
      properties:
        messages:
          items:
            additionalProperties: true
            type: object
          type: array
          minItems: 1
          title: Messages
          description: List of chat messages
        repositories:
          items:
            anyOf:
              - type: string
              - additionalProperties: true
                type: object
          type: array
          title: Repositories
          description: >-
            List of repositories to query. Can be strings (slug, display name)
            or dicts with a 'repository' field.
        data_sources:
          items:
            anyOf:
              - type: string
              - additionalProperties: true
                type: object
          type: array
          title: Data Sources
          description: >-
            List of data sources to query. Can be strings (display_name, URL, or
            source_id) or dicts with 'source_id' or 'identifier' fields
        local_folders:
          items:
            anyOf:
              - type: string
              - additionalProperties: true
                type: object
          type: array
          title: Local Folders
          description: >-
            List of local folders to query. Can be strings (display_name or
            local_folder_id) or dicts with 'local_folder_id' or 'identifier'
            fields. Local folders are private and user-scoped.
        slack_workspaces:
          items:
            type: string
          type: array
          title: Slack Workspaces
          description: List of Slack installation IDs to include in search
        slack_filters:
          anyOf:
            - $ref: '#/components/schemas/SlackSearchFilters'
            - type: 'null'
          description: Filters for Slack message results (channels, users, date range)
        category:
          anyOf:
            - type: string
            - type: 'null'
          title: Category
          description: >-
            Filter local folder results by classification category (e.g.,
            'Work', 'Personal')
        local_source_filters:
          anyOf:
            - $ref: '#/components/schemas/LocalSourceFilters'
            - type: 'null'
          description: Filters for local/personal sources (messages, contacts, etc.)
        source_trust_filter:
          anyOf:
            - $ref: '#/components/schemas/SourceTrustFilter'
            - type: 'null'
          description: Optional trust-aware filtering for curated source results
        search_mode:
          type: string
          title: Search Mode
          description: 'Search mode: ''repositories'', ''sources'', or ''unified'''
          default: unified
        stream:
          type: boolean
          title: Stream
          description: Whether to stream the response
          default: false
        include_sources:
          type: boolean
          title: Include Sources
          description: Whether to include source texts in the response
          default: true
        fast_mode:
          type: boolean
          title: Fast Mode
          description: >-
            Skip LLM processing for faster results (100-500ms vs 2-8s). Set to
            false for deeper analysis.
          default: true
        skip_llm:
          type: boolean
          title: Skip Llm
          description: >-
            Return raw search results without any LLM processing. Returns only
            sources with scores.
          default: false
        reasoning_strategy:
          type: string
          title: Reasoning Strategy
          description: >-
            Retrieval strategy: 'vector' (default similarity search), 'tree'
            (LLM-guided tree navigation for PDFs), or 'hybrid' (both combined)
          default: vector
        max_tokens:
          anyOf:
            - type: integer
              maximum: 100000
              minimum: 100
            - type: 'null'
          title: Max Tokens
          description: Maximum tokens in response. Results truncated when budget reached.
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: >-
            Synthesis model override. Allowed: claude-sonnet-4-5,
            gpt-5.2-2025-12-11, claude-haiku-4-5-20251001
        semantic_cache_threshold:
          type: number
          maximum: 1
          minimum: 0.8
          title: Semantic Cache Threshold
          description: Minimum similarity for semantic cache hit (non-streaming only)
          default: 0.92
        bypass_semantic_cache:
          type: boolean
          title: Bypass Semantic Cache
          description: Skip semantic cache (L2) lookup
          default: false
        include_follow_ups:
          type: boolean
          title: Include Follow Ups
          description: >-
            Generate follow-up questions (adds ~500-1000ms LLM latency).
            Disabled by default for speed.
          default: false
        e2e_session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: E2E Session Id
          description: >-
            Active E2E decrypt session ID. When provided, encrypted local folder
            results are decrypted through the desktop bridge before synthesis.
        mode:
          type: string
          const: query
          title: Mode
          description: Search mode discriminator
          default: query
      type: object
      required:
        - messages
      title: QuerySearchRequest
    WebSearchRequestWithMode:
      properties:
        query:
          type: string
          title: Query
          description: Search query
        num_results:
          type: integer
          maximum: 10
          minimum: 1
          title: Num Results
          description: Number of results
          default: 5
        category:
          anyOf:
            - type: string
            - type: 'null'
          title: Category
          description: >-
            Filter by category: github, company, research, news, tweet, pdf,
            blog
        days_back:
          anyOf:
            - type: integer
            - type: 'null'
          title: Days Back
          description: Only show results from last N days
        find_similar_to:
          anyOf:
            - type: string
            - type: 'null'
          title: Find Similar To
          description: URL to find similar content to
        mode:
          type: string
          const: web
          title: Mode
          description: Search mode discriminator
          default: web
      type: object
      required:
        - query
      title: WebSearchRequestWithMode
    DeepResearchRequestWithMode:
      properties:
        query:
          type: string
          title: Query
          description: Research question
        output_format:
          anyOf:
            - type: string
            - type: 'null'
          title: Output Format
          description: Optional structure hint
        verbose:
          type: boolean
          title: Verbose
          description: Include verbose trace output
          default: false
        mode:
          type: string
          const: deep
          title: Mode
          description: Search mode discriminator
          default: deep
      type: object
      required:
        - query
      title: DeepResearchRequestWithMode
    UniversalSearchRequestWithMode:
      properties:
        query:
          type: string
          title: Query
          description: Natural language search query
        top_k:
          type: integer
          maximum: 100
          minimum: 1
          title: Top K
          description: Total number of results
          default: 20
        include_repos:
          type: boolean
          title: Include Repos
          description: Include repository sources
          default: true
        include_docs:
          type: boolean
          title: Include Docs
          description: Include documentation sources
          default: true
        include_huggingface_datasets:
          type: boolean
          title: Include Huggingface Datasets
          description: >-
            Include HuggingFace dataset sources (excluded by default to prevent
            search pollution)
          default: false
        alpha:
          type: number
          maximum: 1
          minimum: 0
          title: Alpha
          description: Weight for vector search (0.7 = 70% vector)
          default: 0.7
        compress_output:
          type: boolean
          title: Compress Output
          description: Use AI to compress results
          default: false
        max_sources:
          type: integer
          maximum: 30
          minimum: 1
          title: Max Sources
          description: Max source namespaces to deep search
          default: 5
        sources_for_answer:
          type: integer
          maximum: 30
          minimum: 1
          title: Sources For Answer
          description: Number of results to use for AI answer
          default: 10
        bypass_cache:
          type: boolean
          title: Bypass Cache
          description: Skip cache and force fresh search results
          default: false
        max_tokens:
          anyOf:
            - type: integer
              maximum: 100000
              minimum: 100
            - type: 'null'
          title: Max Tokens
          description: Maximum tokens in response. Results truncated when budget reached.
        boost_source_types:
          additionalProperties:
            type: number
          type: object
          title: Boost Source Types
          description: Source type boosts (override to customize or set {} to disable)
          default:
            repository: 1.2
            documentation: 1
            research_paper: 0.9
            huggingface_dataset: 0.85
        boost_languages:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Boost Languages
          description: Programming languages to boost (e.g., ['python', 'typescript'])
        language_boost_factor:
          type: number
          maximum: 5
          minimum: 1
          title: Language Boost Factor
          description: Boost multiplier for preferred languages
          default: 1.5
        use_native_boosting:
          type: boolean
          title: Use Native Boosting
          description: Use TurboPuffer FTS v2 native Sum/Product boosting
          default: true
        semantic_cache_threshold:
          type: number
          maximum: 1
          minimum: 0.8
          title: Semantic Cache Threshold
          description: Minimum similarity for semantic cache hit (0.8-1.0)
          default: 0.92
        bypass_semantic_cache:
          type: boolean
          title: Bypass Semantic Cache
          description: Skip semantic cache (L2) lookup
          default: false
        expand_symbols:
          type: boolean
          title: Expand Symbols
          description: >-
            Extract function/class names from results and search for usages
            (cAST-inspired)
          default: false
        mode:
          type: string
          const: universal
          title: Mode
          description: Search mode discriminator
          default: universal
      type: object
      required:
        - query
      title: UniversalSearchRequestWithMode
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SlackSearchFilters:
      properties:
        channels:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Channels
          description: Filter by channel names or IDs
        users:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Users
          description: Filter by Slack user names or IDs
        date_from:
          anyOf:
            - type: string
            - type: 'null'
          title: Date From
          description: Oldest message timestamp (ISO 8601)
        date_to:
          anyOf:
            - type: string
            - type: 'null'
          title: Date To
          description: Newest message timestamp (ISO 8601)
        include_threads:
          type: boolean
          title: Include Threads
          description: Include threaded messages in results
          default: true
      type: object
      title: SlackSearchFilters
      description: Filters for Slack message search within query endpoint.
    LocalSourceFilters:
      properties:
        source_subtype:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Subtype
          description: Filter by source subtype (e.g., 'database', 'telegram_export')
        db_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Db Type
          description: >-
            Filter by database type (e.g., 'imessage', 'telegram',
            'safari_history')
        connector_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Connector Type
          description: Filter by connector type (e.g., 'imessage', 'whatsapp', 'contacts')
        conversation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversation Id
          description: Filter to a specific conversation/chat
        contact_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Contact Id
          description: Filter to messages with a specific contact
        sender_role:
          anyOf:
            - type: string
            - type: 'null'
          title: Sender Role
          description: 'Filter by sender role: ''self'' or ''contact'''
        time_after:
          anyOf:
            - type: string
            - type: 'null'
          title: Time After
          description: Only return results with timestamp after this ISO datetime
        time_before:
          anyOf:
            - type: string
            - type: 'null'
          title: Time Before
          description: Only return results with timestamp before this ISO datetime
      type: object
      title: LocalSourceFilters
      description: Filters for local/personal source retrieval (messages, contacts, etc.).
    SourceTrustFilter:
      properties:
        minimum_trust_tier:
          anyOf:
            - type: string
              enum:
                - low
                - medium
                - high
                - verified
            - type: 'null'
          title: Minimum Trust Tier
          description: Only include sources at or above this effective trust tier
        verified_only:
          type: boolean
          title: Verified Only
          description: Only include Nia-verified sources
          default: false
        require_overlay:
          type: boolean
          title: Require Overlay
          description: Only include sources with curated overlays
          default: false
      type: object
      title: SourceTrustFilter
      description: Filtering preferences for trust-aware retrieval.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key must be provided in the Authorization header

````