Changelog
Start typing to search…
Back to All
Deprecated

v1.5.0 - Reorganised API Structure, Headlines & Events Hierarchy

about 1 month ago by ReadMe GitHub Action

Major restructure introducing new /headlines/ and /events/ endpoint hierarchies with improved filtering, cursor pagination, and sentiment index endpoints. Multiple legacy endpoints deprecated with sunset date 2026-05-01, and several previously deprecated endpoints removed.

Added

  • New headlines taxonomy endpoints for accessing model and topic metadata:

    • /headlines/models/macro - Access to metadata related to macro topic models
    • /headlines/models/ticker - Access to metadata related to asset based topic models
    • /headlines/topics/macro/{model_id} - Access to metadata related to the topics of particular macro topic models
    • /headlines/topics/ticker/{ticker} - Access to metadata related to the topics of particular asset topic models
    • /headlines/topics/macro/presets/{model_id} - Access to presets for the macro topic models that can be used in headline endpoints

  • New events taxonomy endpoints for accessing event topic metadata:

    • /events/topics/ticker/{ticker} - Access topics used for tagging events per ticker
    • /events/topics/sector/{sector_id} - Access topics used for tagging events per sector

  • New headlines feed endpoints with improved filtering and pagination:

    • /headlines/feed/live/ticker/{ticker} - Live feed of headlines categorised by asset and topic related to that asset
      • Features: Filter by probability thresholds, sentiment thresholds, sources and languages by preset, and match type (explicit or implicit asset mention)
      • Benefits: Tagged with sentiment associated with that asset and topic
    • /headlines/feed/historical/ticker/{ticker} - Historical feed of headlines categorised by asset and topic related to that asset
      • Features: Same filtering as live endpoint with cursor pagination for crawling through results
    • /headlines/feed/live/macro/{model_id} - Live feed of headlines categorised by macroeconomic topic and tagged with sentiment
      • Features: Filter by source, language and source country presets
    • /headlines/feed/historical/macro/{model_id} - Historical feed of headlines categorised by macroeconomic topic and tagged with sentiment
      • Features: Same filtering as live endpoint with cursor pagination for crawling through results

  • New events entity endpoint:

    • /events/entities/{event_id} - Get entities (assets, people, places, organisations etc.) associated with a particular event_id

  • New asset headline sentiment index endpoints:

    • /headlines/index/ticker/live/{ticker} - Get live hourly aggregation of the headlines feed per ticker
      • Features: Aggregation can be customised per type of match with the asset (explicit or implicit)
    • /headlines/index/ticker/historical/{ticker} - Get historical hourly aggregation of the headlines feed per ticker
      • Features: Aggregation can be customised per type of match with the asset (explicit or implicit), with cursor pagination for iterating through results

  • New macro headline sentiment index endpoints (global) - No consideration of location, aligns index to end of hour:

    • /headlines/index/macro/live/global/{model_id} - Get live hourly aggregation of the macro-related headlines feed per model_id
    • /headlines/index/macro/historical/global/{model_id} - Get historical hourly aggregation of the macro-related headlines feed per model_id
    • /headlines/index/macro/query/global - Get historical hourly aggregation of the macro-related headlines feed according to a custom query

  • New macro headline sentiment index endpoints (regional) - Results aggregated by country mentioned and source country, aligns index to end of hour:

    • /headlines/index/macro/live/regional/{model_id} - Get live hourly aggregation of the macro-related headlines feed per model_id
    • /headlines/index/macro/historical/regional/{model_id} - Get historical hourly aggregation of the macro-related headlines feed per model_id
    • /headlines/index/macro/query/regional - Get historical hourly aggregation of the macro-related headlines feed according to a custom query

  • New event sentiment index endpoints - Defaults to aligning index to end of hour:

    • /events/index/live/ticker/batch - Get live hourly aggregated index for events per batch of tickers
    • /events/index/live/ticker/{ticker} - Get live hourly aggregated index for events per ticker
    • /events/index/historical/ticker/{ticker} - Get historical hourly aggregated index for events per ticker, with cursor pagination for iterating through results
    • /events/index/query - Get historical hourly aggregated index for events with a custom query, with cursor pagination for iterating through results

Changed

  • Default align_to_period_end behaviour - New index endpoints default to align_to_period_end=True (aligns to end of hour). When migrating from deprecated endpoints, explicitly set align_to_period_end=False to maintain previous behaviour.

Deprecated

Note: All deprecated endpoints below remain fully functional until their removal date of 2026-05-01.

  • Headlines feed endpoints - replaced by new feed endpoints with improved performance, filtering, and pagination:

    • /headlines/ticker/{ticker} → Use /headlines/feed/live/ticker/{ticker} for live data or /headlines/feed/historical/ticker/{ticker} for historical data
    • /headlines/macro/{model_id} → Use /headlines/feed/live/macro/{model_id} for live data or /headlines/feed/historical/macro/{model_id} for historical data

  • Macro global sentiment endpoints - replaced by new headline index endpoints (set align_to_period_end=False to maintain previous behaviour):

    • /macro/live/sentiment/{model_id} → Use /headlines/index/macro/live/global/{model_id}
    • /macro/historical/sentiment/{model_id} → Use /headlines/index/macro/historical/global/{model_id}
    • /macro/query/sentiment → Use /headlines/index/macro/query/global

  • Macro regional sentiment endpoints - replaced by new headline index endpoints (set align_to_period_end=False to maintain previous behaviour):

    • /macro/live/regional/{model_id} → Use /headlines/index/macro/live/regional/{model_id}
    • /macro/historical/regional/{model_id} → Use /headlines/index/macro/historical/regional/{model_id}
    • /macro/query/regional → Use /headlines/index/macro/query/regional

  • Event metrics endpoints - replaced by new event index endpoints (set align_to_period_end=False to maintain previous behaviour):

    • /event_metrics/live/ticker/batch → Use /events/index/live/ticker/batch
    • /event_metrics/live/ticker/{ticker} → Use /events/index/live/ticker/{ticker}
    • /event_metrics/historical/ticker/{ticker} → Use /events/index/historical/ticker/{ticker}
    • /event_metrics/query → Use /events/index/query

Removed

  • /headlines/events - Replaced by /headlines/event/{event_id}. Query individual event_ids instead of batch
  • /events/entities - Replaced by /events/entities/{event_id}. Query individual event_ids instead of batch
  • /macro/models - Replaced by /headlines/models/macro
  • /macro/topics/{model_id} - Replaced by /headlines/topics/macro/{model_id}
  • /macro/topics/presets/{model_id} - Replaced by /headlines/topics/macro/presets/{model_id}
  • /ticker/{ticker}/topics - Replaced by /events/topics/ticker/{ticker}
  • /sector/{sector_id}/topics - Replaced by /events/topics/sector/{sector_id}