openapi: 3.2.0
info:
  title: VoyantIO Enhanced RAG API
  description: '

    ## Brand Context Intelligence Platform


    VoyantIO provides AI-powered brand context management for GTM teams.


    ### Core Capabilities


    - **Context Streams** - Centralized brand knowledge that any AI tool can use

    - **Telemetry** - Visitor tracking with IP geolocation and company enrichment

    - **Signals** - Social listening across 10+ platforms: GitHub, Reddit, HackerNews, LinkedIn, Twitter/X, Discord, ProductHunt, YouTube, G2, Slack, and government sources

    - **Target Graph** - Account and contact intelligence with engagement tracking

    - **RAG** - Retrieval-augmented content generation with brand awareness


    ### Authentication


    Most endpoints require a Bearer token from Clerk authentication.

    Public endpoints (telemetry ingestion, well-known files) are clearly marked.


    ### Rate Limits


    - Telemetry ingestion: 100 req/min per IP

    - API endpoints: 1000 req/min per org

    '
  version: 1.0.0
servers:
- url: https://voice-forge-production.up.railway.app
  description: Production
tags:
- name: Enhanced RAG
  description: Advanced RAG with multi-source retrieval, re-ranking, and context fusion.
paths:
  /api/rag/search:
    post:
      tags:
      - Enhanced RAG
      summary: Hybrid Search
      description: 'Enhanced search endpoint using hybrid retrieval strategies.


        Accepts EITHER a Clerk session OR an org-scoped API key (vio_...), so

        server-to-server callers (e.g. the agency-os strategy agents) can ground

        against a specific org''s context. org_id is taken from the auth context —

        an API key is bound to exactly one org, so retrieval stays tenant-isolated.'
      operationId: hybrid_search_api_rag_search_post
      parameters:
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HybridSearchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HybridSearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/rag/generate-stream:
    post:
      tags:
      - Enhanced RAG
      summary: Generate Content Stream
      description: 'Stream content generation with real-time output like Jasper.


        Returns a streaming response where content appears word-by-word

        as it''s being generated by Claude.'
      operationId: generate_content_stream_api_rag_generate_stream_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateWithHybridRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/rag/generate:
    post:
      tags:
      - Enhanced RAG
      summary: Generate With Hybrid Rag
      description: 'Enhanced content generation using hybrid RAG for context retrieval.


        This endpoint uses the hybrid search to gather relevant context,

        then generates content using the retrieved information.'
      operationId: generate_with_hybrid_rag_api_rag_generate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateWithHybridRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateWithHybridResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/rag/generate-with-gypsum:
    post:
      tags:
      - Enhanced RAG
      summary: Generate With Gypsum And Rag Non Stream
      description: 'NON-STREAMING content generation using Gypsum + RAG.

        Returns complete content in a single response.'
      operationId: generate_with_gypsum_and_rag_non_stream_api_rag_generate_with_gypsum_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateWithGypsumRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateWithGypsumResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/rag/strategies:
    get:
      tags:
      - Enhanced RAG
      summary: Get Available Strategies
      description: Get information about available search strategies.
      operationId: get_available_strategies_api_rag_strategies_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/rag/stats/{org_id}:
    get:
      tags:
      - Enhanced RAG
      summary: Get Rag Statistics
      description: 'Get RAG statistics for an organization.


        Returns information about content availability, embeddings, and readiness.'
      operationId: get_rag_statistics_api_rag_stats__org_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          title: Org Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/rag/debug/search:
    post:
      tags:
      - Enhanced RAG
      summary: Debug Search Strategies
      description: 'Debug endpoint to test individual search strategies.


        Returns results from each strategy separately for comparison and debugging.'
      operationId: debug_search_strategies_api_rag_debug_search_post
      security:
      - HTTPBearer: []
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
          description: Search query to debug
          title: Query
        description: Search query to debug
      - name: org_id
        in: query
        required: true
        schema:
          type: string
          description: Organization ID
          title: Org Id
        description: Organization ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/rag/generate-with-gypsum-stream:
    post:
      tags:
      - Enhanced RAG
      summary: Generate With Gypsum And Rag Stream
      description: Enhanced streaming content generation using both Gypsum and RAG with real-time output.
      operationId: generate_with_gypsum_and_rag_stream_api_rag_generate_with_gypsum_stream_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateWithGypsumRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/rag/sync-gypsum:
    post:
      tags:
      - Enhanced RAG
      summary: Sync Gypsum To Rag
      description: 'Sync Gypsum messaging framework data into RAG pipeline.


        This creates the messaging foundation by indexing:

        - Brand messaging and positioning

        - Product information and use cases

        - Personas and testimonials


        This data becomes the core knowledge base that''s supplemented

        by website crawls, PDFs, and other content.'
      operationId: sync_gypsum_to_rag_api_rag_sync_gypsum_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/rag/gypsum-sync-status:
    get:
      tags:
      - Enhanced RAG
      summary: Get Gypsum Sync Status
      description: Check if Gypsum data has been synced to RAG and when.
      operationId: get_gypsum_sync_status_api_rag_gypsum_sync_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
components:
  schemas:
    GenerateWithGypsumRequest:
      properties:
        query:
          type: string
          title: Query
          description: Query or topic for content generation
        platform:
          type: string
          title: Platform
          description: Target platform (twitter, linkedin, etc.)
        tone:
          type: string
          title: Tone
          description: Desired tone (professional, casual, etc.)
        persona_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Persona Id
          description: Specific persona to target
        use_gypsum_context:
          type: boolean
          title: Use Gypsum Context
          description: Include Gypsum marketing data
          default: true
        strategy:
          type: string
          enum:
          - hybrid
          - semantic
          - keyword
          - domain
          title: Strategy
          description: Search strategy for RAG context retrieval
          default: hybrid
        top_k:
          type: integer
          maximum: 20.0
          minimum: 1.0
          title: Top K
          description: Number of context chunks to retrieve
          default: 5
        domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
          description: Filter context by domain
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
          description: Filter context by content type
      type: object
      required:
      - query
      - platform
      - tone
      title: GenerateWithGypsumRequest
      description: Request model for content generation with Gypsum + RAG integration.
    HybridSearchRequest:
      properties:
        query:
          type: string
          maxLength: 1000
          minLength: 1
          title: Query
          description: Search query
        strategy:
          type: string
          enum:
          - hybrid
          - semantic
          - keyword
          - domain
          title: Strategy
          description: Search strategy to use
          default: hybrid
        top_k:
          type: integer
          maximum: 50.0
          minimum: 1.0
          title: Top K
          description: Number of results to return
          default: 10
        domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
          description: Filter by specific domain
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
          description: Filter by content type
      type: object
      required:
      - query
      title: HybridSearchRequest
      description: Request model for hybrid search.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    GenerateWithGypsumResponse:
      properties:
        query:
          type: string
          title: Query
        generated_content:
          type: string
          title: Generated Content
        context_sources:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Context Sources
        gypsum_context:
          additionalProperties: true
          type: object
          title: Gypsum Context
        retrieval_stats:
          additionalProperties: true
          type: object
          title: Retrieval Stats
        generation_metadata:
          additionalProperties: true
          type: object
          title: Generation Metadata
        timestamp:
          type: string
          title: Timestamp
      type: object
      required:
      - query
      - generated_content
      - context_sources
      - gypsum_context
      - retrieval_stats
      - generation_metadata
      - timestamp
      title: GenerateWithGypsumResponse
      description: Response model for Gypsum + RAG content generation.
    GenerateWithHybridResponse:
      properties:
        query:
          type: string
          title: Query
        generated_content:
          type: string
          title: Generated Content
        context_sources:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Context Sources
        retrieval_stats:
          additionalProperties: true
          type: object
          title: Retrieval Stats
        generation_metadata:
          additionalProperties: true
          type: object
          title: Generation Metadata
        timestamp:
          type: string
          title: Timestamp
      type: object
      required:
      - query
      - generated_content
      - context_sources
      - retrieval_stats
      - generation_metadata
      - timestamp
      title: GenerateWithHybridResponse
      description: Response model for hybrid RAG content generation.
    GenerateWithHybridRequest:
      properties:
        query:
          type: string
          title: Query
          description: Query or topic for content generation
        platform:
          type: string
          title: Platform
          description: Target platform (twitter, linkedin, etc.)
        tone:
          type: string
          title: Tone
          description: Desired tone (professional, casual, etc.)
        strategy:
          type: string
          enum:
          - hybrid
          - semantic
          - keyword
          - domain
          title: Strategy
          description: Search strategy for context retrieval
          default: hybrid
        top_k:
          type: integer
          maximum: 20.0
          minimum: 1.0
          title: Top K
          description: Number of context chunks to retrieve
          default: 5
        domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
          description: Filter context by domain
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
          description: Filter context by content type
      type: object
      required:
      - query
      - platform
      - tone
      title: GenerateWithHybridRequest
      description: Request model for content generation with hybrid RAG.
    HybridSearchResponse:
      properties:
        query:
          type: string
          title: Query
        results:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Results
        retrieval_stats:
          additionalProperties: true
          type: object
          title: Retrieval Stats
        timestamp:
          type: string
          title: Timestamp
        strategy_used:
          type: string
          title: Strategy Used
      type: object
      required:
      - query
      - results
      - retrieval_stats
      - timestamp
      - strategy_used
      title: HybridSearchResponse
      description: Response model for hybrid search.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer