openapi: 3.0.3
info:
  title: StockData Entities News API
  description: StockData.org provides free real-time, intraday, and historical stock, forex, and cryptocurrency market data along with global financial news and sentiment analysis. The API delivers market data for US-listed stocks including OHLCV data, splits, dividends, and entity-level news sentiment from 5,000+ sources in 30+ languages. All endpoints require an api_token parameter.
  version: '1.0'
  contact:
    url: https://www.stockdata.org/
  termsOfService: https://www.stockdata.org/terms
servers:
- url: https://api.stockdata.org/v1
  description: Production Server
security:
- ApiToken: []
tags:
- name: News
  description: Global financial news with sentiment analysis
paths:
  /news/all:
    get:
      operationId: getFinancialNews
      summary: Get Financial News
      description: Get all the latest global financial news filtered by entities identified within articles, with sentiment analysis for each entity.
      tags:
      - News
      parameters:
      - name: api_token
        in: query
        required: true
        schema:
          type: string
        description: Your API token from the StockData dashboard.
      - name: symbols
        in: query
        required: false
        schema:
          type: string
        description: Filter news by comma-separated ticker symbols.
      - name: entity_types
        in: query
        required: false
        schema:
          type: string
        description: Filter by entity types (e.g., index, equity, etf).
      - name: industries
        in: query
        required: false
        schema:
          type: string
        description: Filter by industry classification.
      - name: countries
        in: query
        required: false
        schema:
          type: string
        description: Filter by country code.
      - name: sentiment_gte
        in: query
        required: false
        schema:
          type: number
          format: float
        description: Minimum sentiment score filter.
      - name: sentiment_lte
        in: query
        required: false
        schema:
          type: number
          format: float
        description: Maximum sentiment score filter.
      - name: search
        in: query
        required: false
        schema:
          type: string
        description: Full-text search query across article titles and descriptions.
      - name: language
        in: query
        required: false
        schema:
          type: string
        description: Filter by language code (e.g., en, de, fr).
      - name: page
        in: query
        required: false
        schema:
          type: integer
        description: Page number for pagination.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Number of results per page (max 50).
      responses:
        '200':
          description: News articles returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsResponse'
        '401':
          description: Invalid or missing API token.
        '429':
          description: Rate limit exceeded.
  /news/similar/{uuid}:
    get:
      operationId: getSimilarNews
      summary: Get Similar News Articles
      description: Find articles similar to a specific article identified by its UUID, with relevance scores and entity data.
      tags:
      - News
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
        description: UUID of the reference article.
      - name: api_token
        in: query
        required: true
        schema:
          type: string
        description: Your API token from the StockData dashboard.
      - name: symbols
        in: query
        required: false
        schema:
          type: string
        description: Filter similar articles by ticker symbols.
      - name: language
        in: query
        required: false
        schema:
          type: string
        description: Filter by language code.
      responses:
        '200':
          description: Similar articles returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsResponse'
        '401':
          description: Invalid or missing API token.
        '404':
          description: Article not found.
  /news/uuid/{uuid}:
    get:
      operationId: getNewsByUuid
      summary: Get News Article By UUID
      description: Retrieve a specific news article by its unique identifier.
      tags:
      - News
      parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: string
        description: UUID of the article to retrieve.
      - name: api_token
        in: query
        required: true
        schema:
          type: string
        description: Your API token from the StockData dashboard.
      responses:
        '200':
          description: News article returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsArticle'
        '401':
          description: Invalid or missing API token.
        '404':
          description: Article not found.
  /news/stats/intraday:
    get:
      operationId: getNewsStatsIntraday
      summary: Get Entity News Stats Intraday
      description: Get an intraday time-series view of entity performance based on news sentiment, grouped by intervals.
      tags:
      - News
      parameters:
      - name: api_token
        in: query
        required: true
        schema:
          type: string
        description: Your API token from the StockData dashboard.
      - name: interval
        in: query
        required: false
        schema:
          type: string
          enum:
          - minute
          - hour
          - day
          - week
          - month
          - quarter
          - year
        description: Aggregation interval for the time series.
      - name: group_by
        in: query
        required: false
        schema:
          type: string
        description: Field to group results by (e.g., symbol).
      - name: symbols
        in: query
        required: false
        schema:
          type: string
        description: Filter by comma-separated ticker symbols.
      - name: sentiment_gte
        in: query
        required: false
        schema:
          type: number
          format: float
        description: Minimum sentiment score filter.
      - name: min_doc_count
        in: query
        required: false
        schema:
          type: integer
        description: Minimum number of articles required to include an entity.
      responses:
        '200':
          description: Intraday entity news stats returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsStatsResponse'
        '401':
          description: Invalid or missing API token.
  /news/stats/aggregation:
    get:
      operationId: getNewsStatsAggregation
      summary: Get Entity News Stats Aggregation
      description: Get a single-timeframe aggregation showing best and worst performing entities based on news sentiment.
      tags:
      - News
      parameters:
      - name: api_token
        in: query
        required: true
        schema:
          type: string
        description: Your API token from the StockData dashboard.
      - name: group_by
        in: query
        required: false
        schema:
          type: string
        description: Field to group results by.
      - name: symbols
        in: query
        required: false
        schema:
          type: string
        description: Filter by comma-separated ticker symbols.
      - name: sentiment_gte
        in: query
        required: false
        schema:
          type: number
          format: float
        description: Minimum sentiment score filter.
      - name: min_doc_count
        in: query
        required: false
        schema:
          type: integer
        description: Minimum number of articles required.
      responses:
        '200':
          description: Aggregated entity news stats returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsAggregationResponse'
        '401':
          description: Invalid or missing API token.
  /news/stats/trending:
    get:
      operationId: getTrendingEntities
      summary: Get Trending Entities
      description: Identify trending entities based on news volume and sentiment within a specified timeframe.
      tags:
      - News
      parameters:
      - name: api_token
        in: query
        required: true
        schema:
          type: string
        description: Your API token from the StockData dashboard.
      - name: group_by
        in: query
        required: false
        schema:
          type: string
        description: Field to group results by.
      - name: sentiment_gte
        in: query
        required: false
        schema:
          type: number
          format: float
        description: Minimum sentiment score filter.
      - name: date_from
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Start date/time for the trending window.
      - name: date_to
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: End date/time for the trending window.
      - name: min_doc_count
        in: query
        required: false
        schema:
          type: integer
        description: Minimum number of articles required.
      responses:
        '200':
          description: Trending entities returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrendingResponse'
        '401':
          description: Invalid or missing API token.
  /news/sources:
    get:
      operationId: getNewsSources
      summary: Get News Sources
      description: View all available news sources that can be used to filter other API requests. Sources span 5,000+ outlets in 30+ languages.
      tags:
      - News
      parameters:
      - name: api_token
        in: query
        required: true
        schema:
          type: string
        description: Your API token from the StockData dashboard.
      - name: distinct_domain
        in: query
        required: false
        schema:
          type: boolean
        description: Return only distinct domains.
      - name: language
        in: query
        required: false
        schema:
          type: string
        description: Filter sources by language code.
      - name: page
        in: query
        required: false
        schema:
          type: integer
        description: Page number for pagination.
      responses:
        '200':
          description: News sources returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourcesResponse'
        '401':
          description: Invalid or missing API token.
components:
  schemas:
    NewsSource:
      type: object
      properties:
        source_id:
          type: string
          description: Unique source identifier.
        domain:
          type: string
          description: Source domain name.
        language:
          type: string
          description: Primary language of the source.
    NewsResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/NewsArticle'
    EntityStats:
      type: object
      properties:
        entity_key:
          type: string
          description: Entity identifier (symbol or key).
        total_documents:
          type: integer
          description: Total number of articles mentioning this entity.
        sentiment_avg:
          type: number
          format: float
          description: Average sentiment score across all articles.
    TrendingResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/TrendingEntity'
    SourcesResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/NewsSource'
    Meta:
      type: object
      properties:
        found:
          type: integer
          description: Total number of records matching the query.
        returned:
          type: integer
          description: Number of records returned in this response.
        limit:
          type: integer
          description: Maximum records per page.
        page:
          type: integer
          description: Current page number.
    NewsEntity:
      type: object
      properties:
        symbol:
          type: string
          description: Entity ticker symbol.
        name:
          type: string
          description: Entity name.
        exchange:
          type: string
          description: Exchange name.
        exchange_long:
          type: string
          description: Exchange full name.
        mic_code:
          type: string
          description: Market identifier code.
        country:
          type: string
          description: Country code.
        type:
          type: string
          description: Entity type.
        industry:
          type: string
          description: Industry classification.
        match_score:
          type: number
          format: float
          description: Entity match confidence score.
        sentiment_score:
          type: number
          format: float
          description: Entity sentiment score for this article (-1 to 1).
        highlights:
          type: array
          items:
            $ref: '#/components/schemas/Highlight'
    Highlight:
      type: object
      properties:
        highlight:
          type: string
          description: Highlighted text excerpt.
        sentiment:
          type: number
          format: float
          description: Sentiment score for this highlight.
        highlighted_in:
          type: string
          description: Article section where highlight appears.
    NewsAggregationResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/EntityStats'
    NewsStatsResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: object
          description: Date-keyed time series of entity stats.
    TrendingEntity:
      type: object
      properties:
        entity_key:
          type: string
          description: Entity identifier.
        document_count:
          type: integer
          description: Number of articles mentioning this entity.
        sentiment_avg:
          type: number
          format: float
          description: Average sentiment score.
        relevance_score:
          type: number
          format: float
          description: Trending relevance score.
    NewsArticle:
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for the article.
        title:
          type: string
          description: Article headline.
        description:
          type: string
          description: Article summary or excerpt.
        keywords:
          type: string
          description: Keywords associated with the article.
        snippet:
          type: string
          description: Short snippet from the article body.
        url:
          type: string
          format: uri
          description: URL of the original article.
        image_url:
          type: string
          format: uri
          description: URL of the article's featured image.
        language:
          type: string
          description: Language code of the article.
        published_at:
          type: string
          format: date-time
          description: Publication timestamp.
        source:
          type: string
          description: News source domain.
        relevance_score:
          type: number
          format: float
          description: Relevance score for the query.
        entities:
          type: array
          items:
            $ref: '#/components/schemas/NewsEntity'
        similar:
          type: array
          items:
            $ref: '#/components/schemas/NewsArticle'
  securitySchemes:
    ApiToken:
      type: apiKey
      in: query
      name: api_token
      description: API token obtained from the StockData dashboard.