openapi: 3.1.0
info:
  title: InsightsAPI
  description: >-
    A microservice to provide rollups, leaderboards, and breadth metrics across
    entities.
  version: 0.1.0
paths:
  /insights/health:
    get:
      tags:
        - Utility
        - Utility
      summary: Health check endpoint
      operationId: health_check_insights_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /insights/ticker/{symbol}:
    get:
      tags:
        - tickers
      summary: Get Ticker Key Highlights and Unusual Flow Events
      description: |-
        Retrieves key qualitative highlights and flags unusual flow events 
        for the specified ticker.
      operationId: get_ticker_insights_insights_ticker__symbol__get
      security:
        - HTTPBearer: []
      parameters:
        - name: symbol
          in: path
          required: true
          schema:
            type: string
            title: Symbol
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TickerInsights'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /insights/theme/{theme}:
    get:
      tags:
        - themes
      summary: Get Contextual Notes for Themes
      description: |-
        Provides qualitative contextual notes and narratives explaining recent 
        trends and flow within the specified theme.
      operationId: get_theme_notes_insights_theme__theme__get
      security:
        - HTTPBearer: []
      parameters:
        - name: theme
          in: path
          required: true
          schema:
            type: string
            title: Theme
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityContextualNotes'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /insights/sector/{sector}:
    get:
      tags:
        - sectors
      summary: Get Contextual Notes for Sector Aggregates
      description: >-
        Provides qualitative contextual notes and narratives that explain
        recent 

        aggregate movements in the specified sector.
      operationId: get_sector_notes_insights_sector__sector__get
      security:
        - HTTPBearer: []
      parameters:
        - name: sector
          in: path
          required: true
          schema:
            type: string
            title: Sector
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityContextualNotes'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ContextualNote:
      properties:
        date:
          type: string
          format: date
          title: Date
        title:
          type: string
          title: Title
        content:
          type: string
          title: Content
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
      type: object
      required:
        - date
        - title
        - content
      title: ContextualNote
      description: Model for a single contextual note (used for sector and theme).
    EntityContextualNotes:
      properties:
        entityId:
          type: string
          title: Entityid
        entityType:
          type: string
          title: Entitytype
        notes:
          items:
            $ref: '#/components/schemas/ContextualNote'
          type: array
          title: Notes
      type: object
      required:
        - entityId
        - entityType
        - notes
      title: EntityContextualNotes
      description: Generic model for sector or theme contextual notes.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Highlight:
      properties:
        date:
          type: string
          format: date
          title: Date
        title:
          type: string
          title: Title
        summary:
          type: string
          title: Summary
        tags:
          items:
            type: string
          type: array
          title: Tags
          default: []
      type: object
      required:
        - date
        - title
        - summary
      title: Highlight
      description: Model for a single key highlight or unusual event.
    TickerInsights:
      properties:
        symbol:
          type: string
          title: Symbol
        highlights:
          items:
            $ref: '#/components/schemas/Highlight'
          type: array
          title: Highlights
        flow_events:
          items:
            $ref: '#/components/schemas/Highlight'
          type: array
          title: Flow Events
      type: object
      required:
        - symbol
        - highlights
        - flow_events
      title: TickerInsights
      description: Model for the ticker-specific insights response.
    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:
    HTTPBearer:
      type: http
      scheme: bearer
