ASasknews
stories

Filter and search for top news narratives

Changed on

Filter on our custom, in-house written, stories/events/narratives.

These stories are based on clusters of articles (which come through this endpoint as well, so you can consider this a clustering endpoint). We write stories and track them through time.

The enrichments include a full Reddit overview (including all the thread metadata), as well as descriptions of the reporting voice, the key takeaways, contradictions, all the entities, and much, much more.

You can see this data in action, and filter it similarly at https://asknews.app/stories

get/v1/stories

Request

Query parameters

querystring nullable

Query to be used for the search. If method='nl', then this will beused as a natural language query. If method='kw', then this willbe used as a direct keyword query.

categoriesstring[]

Categories to use for filtering the stories search

uuidsstring[]

A list of UUIDs to retrieve.

start_timestampinteger nullable

Start timestamp to filter results on.

end_timestampinteger nullable

End timestamp to filter results on.

sort_by'published' | 'coverage' | 'sentiment' | 'relevance' | 'confidence' nullable

Which type of sorting to perform. published: Sort by published date. coverage: Sort by coverage. sentiment: Sort by sentiment. relevance: Sort by relevance of similarity score/ranking.

sort_type'asc' | 'desc' nullable

Whether to sort results in ascending or descending order.

string[]
OR
string
integer
OR
string
limitinteger

Limit to use

expand_updatesboolean

Whether to expand updates

max_updatesinteger

Max updates to use

max_articlesinteger

Max articles to use per update

method'nl' | 'kw' | 'both'

Method to use for query, 'nl' means natural language, and will run a semantic search on the stories database. 'kw' means keyword, and will search by keyword on the stories database. 'both' means that both methods will be used and results will be ranked according to IRR.

obj_typestring[]

Object type to filter by, can be a list with 'story' and/or 'story_update'

redditinteger

Whether or not to include Reddit analysiswhere the integer indicates the number of threadsto include in the response. 0 is default. Requirespaid plan to access.

citation_method'brackets' | 'urls' | 'none'

Method to use for citation filtering.

similarity_score_thresholdnumber

Similarity score threshold to use when using query

provocative'unknown' | 'low' | 'medium' | 'high' | 'all'

Filter stories based on how provocative the underlying articles are deemed based on the use of provocative language and emotional vocabulary.

strategy'default' | 'topstories' | 'topstories_categories' | 'topstories_continents'

Strategy to use for automatically controlling the search. 'default' is the default strategy, which follows all filters faithfully. 'topstories' aims to give a diverse look at top news stories that are relevant to the current filter combination.'topstories_categories' aims to give the top stories for each category. 'topstories_continents' aims to give the top stories for each continent.

Response

A list of stories with updates

Changes

  • 6513c99e2917Revision changes
    • info

      added the optional property ////////// to the response with the status

    • info

      added the optional property ////////// to the response with the status

  • f1818f4f772bRevision changes
    • breaking

      the response property ////// became optional for the status

    • breaking

      the response property ////// became optional for the status

    • breaking

      the response property ////// became optional for the status

    • breaking

      the response property ////// became optional for the status

    • breaking

      response property stories/items/updates/items/cluster_articles/items/centroid_distance list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      response property stories/items/updates/items/cluster_articles/items/cluster_probability list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      response property stories/items/updates/items/prompt_articles/items/centroid_distance list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      response property stories/items/updates/items/prompt_articles/items/cluster_probability list-of-types was widened by adding types null to media type application/json of response 200