openapi: 3.2.0
info:
  title: VoyantIO Lusha Intelligence 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: lusha-intelligence
  description: Lusha contact enrichment for lead data.
paths:
  /api/lusha-intelligence/enrich/person:
    post:
      tags:
      - lusha-intelligence
      summary: Enrich Person
      description: 'Enrich a person with Lusha data and AI insights


        This endpoint provides:

        - Complete contact information (email, phone, social)

        - AI-powered insights on decision authority and pain points

        - Buying signal detection

        - Personalized outreach recommendations'
      operationId: enrich_person_api_lusha_intelligence_enrich_person_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonEnrichmentRequest'
        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/lusha-intelligence/enrich/company:
    post:
      tags:
      - lusha-intelligence
      summary: Enrich Company
      description: 'Enrich a company with predictive AI intelligence


        Features:

        - Complete firmographic data

        - AI-powered account intelligence

        - Expansion opportunity identification

        - Competitive landscape analysis

        - Account scoring and prioritization'
      operationId: enrich_company_api_lusha_intelligence_enrich_company_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyEnrichmentRequest'
        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/lusha-intelligence/prospect/ai-discover:
    post:
      tags:
      - lusha-intelligence
      summary: Ai Powered Prospecting
      description: 'AI-powered prospecting to find and score ideal prospects


        Features:

        - Smart filtering based on ICP

        - AI scoring and ranking

        - Personalized insights for each prospect

        - Outreach prioritization

        - Prospecting strategy recommendations'
      operationId: ai_powered_prospecting_api_lusha_intelligence_prospect_ai_discover_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProspectingRequest'
        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/lusha-intelligence/champion/track:
    post:
      tags:
      - lusha-intelligence
      summary: Track Champion Changes
      description: 'Track champion changes at target accounts


        Features:

        - Detect when champions leave companies

        - Identify new champions automatically

        - Risk assessment

        - Retention strategy recommendations'
      operationId: track_champion_changes_api_lusha_intelligence_champion_track_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChampionTrackingRequest'
        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/lusha-intelligence/enrich/bulk:
    post:
      tags:
      - lusha-intelligence
      summary: Bulk Enrichment
      description: 'Bulk enrichment for multiple contacts or companies


        Features:

        - Process up to 100 records at once

        - Parallel processing for speed

        - Reduced API credit usage

        - Batch AI insights generation'
      operationId: bulk_enrichment_api_lusha_intelligence_enrich_bulk_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkEnrichmentRequest'
        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/lusha-intelligence/insights/summary:
    get:
      tags:
      - lusha-intelligence
      summary: Get Enrichment Insights
      description: 'Get insights from enrichment activities


        Returns:

        - Enrichment statistics

        - Top buying signals detected

        - Champion movement trends

        - AI-generated recommendations'
      operationId: get_enrichment_insights_api_lusha_intelligence_insights_summary_get
      security:
      - HTTPBearer: []
      parameters:
      - name: time_period
        in: query
        required: false
        schema:
          type: string
          description: 'Time period: 1d, 7d, 30d'
          default: 7d
          title: Time Period
        description: 'Time period: 1d, 7d, 30d'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/lusha-intelligence/usage/stats:
    get:
      tags:
      - lusha-intelligence
      summary: Get Usage Statistics
      description: Get Lusha API usage statistics
      operationId: get_usage_statistics_api_lusha_intelligence_usage_stats_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/lusha-intelligence/enrichment-queue/status:
    get:
      tags:
      - lusha-intelligence
      summary: Get Enrichment Queue Status
      description: Get the status of the automatic organization enrichment queue
      operationId: get_enrichment_queue_status_api_lusha_intelligence_enrichment_queue_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/lusha-intelligence/enrichment-queue/process:
    post:
      tags:
      - lusha-intelligence
      summary: Process Enrichment Queue
      description: 'Process the organization enrichment queue.


        This enriches organizations that were discovered through signals

        but haven''t been enriched yet.'
      operationId: process_enrichment_queue_api_lusha_intelligence_enrichment_queue_process_post
      security:
      - HTTPBearer: []
      parameters:
      - name: batch_size
        in: query
        required: false
        schema:
          type: integer
          description: Number of organizations to enrich
          default: 10
          title: Batch Size
        description: Number of organizations to enrich
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    EnrichmentType:
      type: string
      enum:
      - person
      - company
      - prospecting
      title: EnrichmentType
    PersonEnrichmentRequest:
      properties:
        identifier:
          type: string
          title: Identifier
          description: Email or LinkedIn URL
        identifier_type:
          type: string
          title: Identifier Type
          description: 'Type of identifier: email or linkedin'
          default: email
        enable_ai_insights:
          type: boolean
          title: Enable Ai Insights
          description: Generate AI-powered insights
          default: true
        detect_buying_signals:
          type: boolean
          title: Detect Buying Signals
          description: Detect buying signals
          default: true
        generate_outreach:
          type: boolean
          title: Generate Outreach
          description: Generate personalized outreach strategy
          default: true
      type: object
      required:
      - identifier
      title: PersonEnrichmentRequest
      description: Request model for person enrichment
    ChampionTrackingRequest:
      properties:
        company_domain:
          type: string
          title: Company Domain
          description: Company domain to track
        alert_on_changes:
          type: boolean
          title: Alert On Changes
          description: Send alerts on champion changes
          default: true
      type: object
      required:
      - company_domain
      title: ChampionTrackingRequest
      description: Request model for champion tracking
    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
    BulkEnrichmentRequest:
      properties:
        identifiers:
          items:
            type: string
          type: array
          title: Identifiers
          description: List of identifiers to enrich
        identifier_type:
          type: string
          title: Identifier Type
          description: Type of identifiers
          default: email
        enrichment_type:
          $ref: '#/components/schemas/EnrichmentType'
          description: Type of enrichment
          default: person
      type: object
      required:
      - identifiers
      title: BulkEnrichmentRequest
      description: Request model for bulk enrichment
    CompanyEnrichmentRequest:
      properties:
        identifier:
          type: string
          title: Identifier
          description: Domain or company name
        identifier_type:
          type: string
          title: Identifier Type
          description: 'Type of identifier: domain or name'
          default: domain
        enable_predictive_intelligence:
          type: boolean
          title: Enable Predictive Intelligence
          description: Generate predictive intelligence
          default: true
        analyze_competition:
          type: boolean
          title: Analyze Competition
          description: Analyze competitive landscape
          default: true
        identify_opportunities:
          type: boolean
          title: Identify Opportunities
          description: Identify expansion opportunities
          default: true
      type: object
      required:
      - identifier
      title: CompanyEnrichmentRequest
      description: Request model for company enrichment
    ProspectingRequest:
      properties:
        job_titles:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Job Titles
          description: Target job titles
        seniority_levels:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Seniority Levels
          description: Target seniority levels
        company_sizes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Company Sizes
          description: Company size ranges
        industries:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Industries
          description: Target industries
        locations:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Locations
          description: Target locations
        technologies:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Technologies
          description: Companies using these technologies
        limit:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Limit
          description: Maximum prospects to return
          default: 10
        enable_ai_scoring:
          type: boolean
          title: Enable Ai Scoring
          description: Score and rank prospects with AI
          default: true
      type: object
      title: ProspectingRequest
      description: Request model for AI prospecting
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer