openapi: 3.1.0
info:
  title: Finlight Financial News Articles API
  description: Real-time financial news API aggregating market-moving news, earnings reports, analyst upgrades, and corporate announcements for equities, currencies, and commodities. Delivers AI-driven sentiment analysis, entity extraction, and sub-second latency streaming.
  version: 2.0.0
  contact:
    name: Finlight Support
    email: info@finlight.me
    url: https://finlight.me
  license:
    name: Proprietary
    url: https://finlight.me
servers:
- url: https://api.finlight.me
  description: Finlight Production API
security:
- ApiKeyAuth: []
tags:
- name: Articles
  description: Financial news articles with sentiment analysis and entity extraction
paths:
  /v2/articles:
    post:
      summary: Search Financial News Articles
      description: Retrieve financial news articles with advanced filtering by tickers, sources, dates, countries, categories, and custom queries. Supports boolean query language with field filters. Returns paginated results with sentiment scores, entity tags, and article metadata.
      operationId: searchArticles
      tags:
      - Articles
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetArticlesParams'
            examples:
              byTicker:
                summary: Search by ticker
                value:
                  tickers:
                  - AAPL
                  - NVDA
                  from: '2024-01-01'
                  pageSize: 20
                  includeContent: true
                  includeEntities: true
              advancedQuery:
                summary: Advanced boolean query
                value:
                  query: (ticker:AAPL OR ticker:NVDA) AND NOT source:www.reuters.com AND "Elon Musk"
                  language: en
                  pageSize: 50
                  page: 1
      responses:
        '200':
          description: Paginated list of financial news articles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetArticleApiResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/articles/by-link:
    get:
      summary: Get Article by URL
      description: Retrieve a single financial news article by its original URL. Returns full article metadata including sentiment analysis and company entity tags.
      operationId: getArticleByLink
      tags:
      - Articles
      parameters:
      - name: link
        in: query
        required: true
        description: The full URL of the article to retrieve
        schema:
          type: string
          format: uri
        example: https://example.com/news/apple-earnings-beat
      - name: includeContent
        in: query
        required: false
        description: Whether to include full article content in the response
        schema:
          type: boolean
      - name: includeEntities
        in: query
        required: false
        description: Whether to include tagged company entity data
        schema:
          type: boolean
      responses:
        '200':
          description: The requested article
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
        '400':
          description: Invalid or missing link parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Article not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Company:
      type: object
      description: A company entity extracted and tagged from a financial news article
      required:
      - companyId
      - name
      - ticker
      properties:
        companyId:
          type: integer
          description: Finlight internal company identifier
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Confidence score for entity extraction (0.0 to 1.0)
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code of the company
        exchange:
          type: string
          description: Primary exchange where the company is listed
        industry:
          type: string
          description: Industry classification of the company
        sector:
          type: string
          description: Sector classification of the company
        name:
          type: string
          description: Company name
        ticker:
          type: string
          description: Primary stock ticker symbol
          example: AAPL
        isin:
          type: string
          description: International Securities Identification Number
          example: US0378331005
        openfigi:
          type: string
          description: OpenFIGI identifier
        primaryListing:
          $ref: '#/components/schemas/Listing'
        isins:
          type: array
          items:
            type: string
          description: All ISIN identifiers associated with the company
        otherListings:
          type: array
          items:
            $ref: '#/components/schemas/Listing'
          description: Other exchange listings for the company
    ErrorResponse:
      type: object
      description: API error response
      properties:
        message:
          type: string
          description: Human-readable error description
        error:
          type: string
          description: Error type or code
        statusCode:
          type: integer
          description: HTTP status code
    Article:
      type: object
      description: A financial news article enriched with sentiment analysis and company entity tags
      required:
      - link
      - title
      - publishDate
      - source
      - language
      properties:
        link:
          type: string
          format: uri
          description: Original URL of the article
        title:
          type: string
          description: Article headline
        publishDate:
          type: string
          format: date-time
          description: Date and time when the article was published
        source:
          type: string
          description: Domain of the news source
        language:
          type: string
          description: ISO 639-1 language code of the article
          example: en
        sentiment:
          type: string
          description: AI-generated sentiment classification
          enum:
          - positive
          - negative
          - neutral
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Confidence score for the sentiment classification (0.0 to 1.0)
        summary:
          type: string
          description: AI-generated article summary
        images:
          type: array
          items:
            type: string
            format: uri
          description: URLs of images associated with the article
        content:
          type: string
          description: Full article content (available when includeContent is true)
        companies:
          type: array
          items:
            $ref: '#/components/schemas/Company'
          description: Companies mentioned and tagged in the article (available when includeEntities is true)
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the article was ingested by Finlight
        revisedDate:
          type: string
          format: date-time
          description: Timestamp when the article was last revised
        isUpdate:
          type: boolean
          description: Whether this article is an update to a previously published piece
        categories:
          type: array
          items:
            $ref: '#/components/schemas/ArticleCategory'
          description: Content categories assigned to the article
        countries:
          type: array
          items:
            type: string
            description: ISO 3166-1 alpha-2 country code
          description: Countries relevant to the article
    GetArticleApiResponse:
      type: object
      description: Paginated response containing financial news articles
      required:
      - status
      - page
      - pageSize
      - articles
      properties:
        status:
          type: string
          description: Response status indicator
          example: ok
        page:
          type: integer
          description: Current page number
        pageSize:
          type: integer
          description: Number of articles per page
        articles:
          type: array
          items:
            $ref: '#/components/schemas/Article'
          description: Array of financial news articles
    Listing:
      type: object
      description: A stock exchange listing for a company
      required:
      - ticker
      - exchangeCode
      - exchangeCountry
      properties:
        ticker:
          type: string
          description: Ticker symbol on this exchange
          example: AAPL
        exchangeCode:
          type: string
          description: Exchange code
          example: XNAS
        exchangeCountry:
          type: string
          description: ISO 3166-1 alpha-2 country code of the exchange
          example: US
    ArticleCategory:
      type: string
      description: Content category for financial news articles
      enum:
      - markets
      - economy
      - business
      - politics
      - geopolitics
      - regulation
      - technology
      - energy
      - commodities
      - crypto
      - health
      - climate
      - security
    GetArticlesParams:
      type: object
      description: Parameters for searching financial news articles
      properties:
        query:
          type: string
          description: Advanced boolean query string. Supports field filters (ticker:AAPL, source:reuters.com), boolean operators (AND, OR, NOT), and phrase matching ("exact phrase").
          example: (ticker:AAPL OR ticker:NVDA) AND NOT source:www.reuters.com AND "Elon Musk"
        sources:
          type: array
          items:
            type: string
          description: Limit results to specific news source domains. Overrides the default source set.
        tickers:
          type: array
          items:
            type: string
          description: Filter by company ticker symbols
          example:
          - AAPL
          - NVDA
          - MSFT
        optInSources:
          type: array
          items:
            type: string
          description: Additional sources to include beyond the default source set
        excludeSources:
          type: array
          items:
            type: string
          description: Source domains to exclude from results
        includeContent:
          type: boolean
          description: Whether to include full article content in results
          default: false
        includeEntities:
          type: boolean
          description: Whether to include tagged company entity data
          default: false
        excludeEmptyContent:
          type: boolean
          description: Whether to exclude articles with no available content
          default: false
        from:
          type: string
          description: Start date filter in YYYY-MM-DD format or ISO 8601 date-time string
          example: '2024-01-01'
        to:
          type: string
          description: End date filter in YYYY-MM-DD format or ISO 8601 date-time string
          example: '2024-12-31'
        language:
          type: string
          description: ISO 639-1 language code to filter articles
          default: en
          example: en
        orderBy:
          type: string
          description: Field to sort results by
          enum:
          - publishDate
          - createdAt
          - revisedDate
          default: publishDate
        order:
          type: string
          description: Sort direction
          enum:
          - ASC
          - DESC
          default: DESC
        pageSize:
          type: integer
          minimum: 1
          maximum: 1000
          description: Number of articles to return per page
          default: 20
        page:
          type: integer
          minimum: 1
          description: Page number for pagination
          default: 1
        countries:
          type: array
          items:
            type: string
          description: Filter by ISO 3166-1 alpha-2 country codes
          example:
          - US
          - GB
          - DE
        categories:
          type: array
          items:
            $ref: '#/components/schemas/ArticleCategory'
          description: Filter by article content categories
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key obtained from https://app.finlight.me
externalDocs:
  description: Finlight API Documentation
  url: https://docs.finlight.me/v2/