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

# Search Brand Facts

> Semantic search over a website's approved brand facts. Combines vector similarity with full-text search, so it also reaches facts not filed under any pillar. Returns fact text with confidence, source URL and quote, and the published pillar it belongs to (null when unfiled). Also available as the MCP tool `search_brand_facts`.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/knowledge-base/facts/search
openapi: 3.1.0
info:
  title: AthenaHQ API
  description: >-
    AthenaHQ API provides programmatic access to manage your websites and
    prompts for AI-powered content optimization.
  version: 1.0.0
  contact:
    email: support@athenahq.ai
servers:
  - url: https://api.athenahq.ai
    description: Production server
security:
  - apiKey: []
tags:
  - name: Basics
    description: Core API operations for managing websites and prompts
  - name: Metrics
    description: Metrics and analytics endpoints for tracking AI visibility
  - name: Billing
    description: Billing and credits endpoints for managing usage
  - name: Team Management
    description: Endpoints for managing team members and invitations
  - name: Groups
    description: Endpoints for managing groups of websites
  - name: Content
    description: >-
      Endpoints for accessing Content Hub data — tabs, tracked URLs, and per-URL
      prompt breakdowns.
  - name: Pitch Workspace
    description: >-
      Endpoints for accessing pitch workspace reports — org-scoped pitch runs
      with competitors, prompts, attributes, and aggregate metrics.
  - name: Knowledge Base
    description: >-
      Endpoints for reading the brand Knowledge Base — approved brand facts and
      the pillars that organize them.
paths:
  /api/v1/knowledge-base/facts/search:
    get:
      tags:
        - Knowledge Base
      summary: Search Brand Facts
      description: >-
        Semantic search over a website's approved brand facts. Combines vector
        similarity with full-text search, so it also reaches facts not filed
        under any pillar. Returns fact text with confidence, source URL and
        quote, and the published pillar it belongs to (null when unfiled). Also
        available as the MCP tool `search_brand_facts`.
      operationId: searchBrandFacts
      parameters:
        - name: website_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
          description: The website whose Knowledge Base to read.
        - name: query
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 200
          description: Natural-language search query.
        - name: pillar_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Restrict results to facts filed under this pillar.
        - name: top_k
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
          description: Maximum number of facts to return.
      responses:
        '200':
          description: Successful response with matching facts, best matches first
          content:
            application/json:
              schema:
                type: object
                properties:
                  facts:
                    type: array
                    items:
                      $ref: '#/components/schemas/BrandFactSearchResult'
                required:
                  - facts
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_website_id:
                  value:
                    error: website_id is required
                missing_query:
                  value:
                    error: query is required
                invalid_top_k:
                  value:
                    error: top_k must be between 1 and 50
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Forbidden - No access to this website, or the Knowledge Base is not
            enabled for the organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized_website:
                  value:
                    error: Unauthorized access to this website
                kb_not_enabled:
                  value:
                    error: Knowledge Base is not enabled for this organization
      security:
        - apiKey: []
components:
  schemas:
    BrandFactSearchResult:
      type: object
      properties:
        id:
          type: string
          format: uuid
        text:
          type: string
          description: The fact statement.
        confidence:
          type:
            - string
            - 'null'
          enum:
            - high
            - medium
            - low
            - null
          description: Confidence level assigned during ingestion, or null when unrated.
        source_url:
          type:
            - string
            - 'null'
          description: URL the fact was extracted from, stored without protocol.
        source_quote:
          type:
            - string
            - 'null'
          description: Verbatim quote from the source backing the fact.
        pillar:
          $ref: '#/components/schemas/BrandFactPillar'
      required:
        - id
        - text
        - confidence
        - source_url
        - source_quote
        - pillar
    Error:
      type: object
      description: Error response object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
          example: Unauthorized
    BrandFactPillar:
      type:
        - object
        - 'null'
      description: >-
        The published pillar the fact is filed under, or null when the fact is
        unfiled.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      required:
        - id
        - name
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key for authentication. You can create one
        [here](https://app.athenahq.ai/organization?tab=api).

````