API Documentation

BTW API Access (30-day free trial)

Authentication

BTW API endpoints require authentication, which you can do with a free trial API key. This key works across both APIs and should be included in the Authorization header of your requests.

For ongoing access to our API or to inquire about a custom endpoint, email us at support@btw.co.

Authorization: Bearer YourApiKey

Get API Key

Endpoints

LiveLM Creator

POST https://btw.co/api/creator sample response

Discovers timely BTW stories tailored to a creator's niche and returns a short explanation for why each story is relevant to that creator. Use this endpoint when you want customized content ideas based on a creator background such as a beat, audience, or persona.

POST Request Body (JSON)
{
  "CreatorBackground": "tech gadget streamer",  // required
  "DateRange": "Now"                            // optional: Now, Week
}

                            Where CreatorBackground is required and describes the creator's niche, audience, or content persona. DateRange is optional and controls whether the endpoint looks at stories from the current moment or the past week.
                        
Required Headers
Authorization: Bearer YourApiKey
Content-Type: application/json
Optional Headers
Accept: application/json

                        Data Dictionary
                    
                        CreatorBackgroundThe creator niche, beat, or audience description submitted in the request.
DiscoveredStoriesThe collection of stories BTW selected as relevant content opportunities for the creator.
ReasonAn explanation of why the story is a good fit for that creator and their audience.
StoryIdThe BTW story ID for the recommended story.
TitleThe headline or short title of the recommended story.
BodyA summary paragraph describing the recommended story.
TimestampThe UTC timestamp for when the response was generated.

CreatorBackground	The creator niche, beat, or audience description submitted in the request.
DiscoveredStories	The collection of stories BTW selected as relevant content opportunities for the creator.
Reason	An explanation of why the story is a good fit for that creator and their audience.
StoryId	The BTW story ID for the recommended story.
Title	The headline or short title of the recommended story.
Body	A summary paragraph describing the recommended story.
Timestamp	The UTC timestamp for when the response was generated.

LiveLM Developer

GET or POST https://btw.co/api/trends/list sample response

Returns the current live list of trending stories. Use this endpoint when you want a lightweight list view of stories and their core metadata. If no parameters are specified, all results are returned.

POST Request Body (JSON)
{
  "StoryIds": [12345, 67890],                   // optional
  "CategoryKeys": ["Technology", "Science"],    // optional
  "Num": 10                                     // optional
}
Alternately, this endpoint can also be called with GET using query string parameters.
GET https://btw.co/api/trends/list?
StoryIds=12345&StoryIds=67890
&CategoryKeys=Technology&CategoryKeys=Science
&Num=10

                            Where CategoryKeys can be any of the following values:
                        
New,ArtsEntertainment,Business,
Culture,Law,Politics,Science,
Sports,Technology,World
                            Where StoryIds is an array of BTW story IDs and Num limits the number of returned stories.
                        
Required Headers
Authorization: Bearer YourApiKey
Optional Headers
Content-Type: application/json
Accept: application/json

                        Data Dictionary
                    
                        TimestampThe UTC timestamp for when the cached feed was last updated.
StoriesThe collection of trending stories returned by the request.
TitleThe headline or main title of the story.
PositionThe story's rank in the full live feed before any request filtering is applied.
StoryIdThe BTW story ID that can be used to look up the same story in other endpoints.
ViralityScoreA numerical score representing how strongly the story is trending.
ThemeA short thematic label for the story.
CategoryKeysA list of top-level category keys associated with the story.
SubcategoriesA dictionary of subcategory groups and their associated values for the story.
BodyA short summary paragraph describing the story.

Timestamp	The UTC timestamp for when the cached feed was last updated.
Stories	The collection of trending stories returned by the request.
Title	The headline or main title of the story.
Position	The story's rank in the full live feed before any request filtering is applied.
StoryId	The BTW story ID that can be used to look up the same story in other endpoints.
ViralityScore	A numerical score representing how strongly the story is trending.
Theme	A short thematic label for the story.
CategoryKeys	A list of top-level category keys associated with the story.
Subcategories	A dictionary of subcategory groups and their associated values for the story.
Body	A short summary paragraph describing the story.

GET or POST https://btw.co/api/trends/detailed sample response

Returns the full story objects for current live trends, including key dates, discourse notes, sentiment analysis, entity breakdown, and source article coverage. Use this endpoint when you want deep access to individual stories. If no parameters are specified, all results are returned.

POST Request Body (JSON)
{
  "StoryIds": [12345, 67890],                   // optional
  "CategoryKeys": ["Technology", "Science"],    // optional
  "Num": 10                                     // optional
}
Alternately, this endpoint can also be called with GET using query string parameters.
GET https://btw.co/api/trends/detailed?
StoryIds=12345&StoryIds=67890
&CategoryKeys=Technology&CategoryKeys=Science
&Num=10

                            Where CategoryKeys can be any of the following values:
                        
New,ArtsEntertainment,Business,
Culture,Law,Politics,Science,
Sports,Technology,World
                            Where StoryIds is an array of BTW story IDs and Num limits the number of returned stories.
                        
Required Headers
Authorization: Bearer YourApiKey
Optional Headers
Content-Type: application/json
Accept: application/json

                        Data Dictionary
                    
                        TimestampThe UTC timestamp for when the cached feed was last updated.
StoriesThe collection of detailed trending stories returned by the request.
TitleThe headline or main title of the story.
PositionThe story's rank in the full live feed before any request filtering is applied.
PositionChangeHow much the story's position has moved since the last update.
StoryIdThe BTW story ID for the story.
ViralityScoreA numerical score representing how strongly the story is trending.
ThemeA short thematic label for the story.
CategoryKeysA list of top-level category keys associated with the story.
SubcategoriesA dictionary of subcategory groups and their associated values for the story.
BodyA short summary paragraph describing the story.
RegionsA list of geographic regions or places associated with the story.
KeyPointsA list of the most important factual takeaways from the story.
DiscourseNotesA list of notable discussion or discourse themes surrounding the story.
EntitiesA list of relevant people, organizations, places, or other entities associated with the story.
KeyDatesA collection of important dates and the events associated with them.
SentimentLeftA short summary of how left-leaning sources are reacting to the story.
SentimentRightA short summary of how right-leaning sources are reacting to the story.
ArticleCountThe total number of source articles associated with the story.
ArticlesA collection of source articles for the story, including title, body, URL, and timestamp.
DiscoveredUtcThe approximate UTC timestamp for when the story was first identified by BTW.

Timestamp	The UTC timestamp for when the cached feed was last updated.
Stories	The collection of detailed trending stories returned by the request.
Title	The headline or main title of the story.
Position	The story's rank in the full live feed before any request filtering is applied.
PositionChange	How much the story's position has moved since the last update.
StoryId	The BTW story ID for the story.
ViralityScore	A numerical score representing how strongly the story is trending.
Theme	A short thematic label for the story.
CategoryKeys	A list of top-level category keys associated with the story.
Subcategories	A dictionary of subcategory groups and their associated values for the story.
Body	A short summary paragraph describing the story.
Regions	A list of geographic regions or places associated with the story.
KeyPoints	A list of the most important factual takeaways from the story.
DiscourseNotes	A list of notable discussion or discourse themes surrounding the story.
Entities	A list of relevant people, organizations, places, or other entities associated with the story.
KeyDates	A collection of important dates and the events associated with them.
SentimentLeft	A short summary of how left-leaning sources are reacting to the story.
SentimentRight	A short summary of how right-leaning sources are reacting to the story.
ArticleCount	The total number of source articles associated with the story.
Articles	A collection of source articles for the story, including title, body, URL, and timestamp.
DiscoveredUtc	The approximate UTC timestamp for when the story was first identified by BTW.

GET or POST https://btw.co/api/trends/search sample response

Searches BTW trend data using free-text input and returns matching stories grouped into currently live and historical datasets. Use this endpoint when you want search-driven discovery instead of filtering by story ID or category.

POST Request Body (JSON)
{
  "Query": "Weather anomalies in California"
}
Alternately, this endpoint can also be called with GET using query string parameters.
GET https://btw.co/api/trends/search?
Query=Weather anomalies in California

                            Where Query is required and should contain the free-text search you want BTW to match against live and historical stories.
                        
Required Headers
Authorization: Bearer YourApiKey
Optional Headers
Content-Type: application/json
Accept: application/json

                        Data Dictionary
                    
                        QueryThe exact search text submitted in the request.
TimestampThe UTC timestamp for when the search response was generated.
LiveStoriesThe collection of matching stories that are currently active in the live BTW trends feed.
HistoricalStoriesThe collection of matching stories found in historical BTW trend data.
TitleThe headline or main title of the story.
PositionChangeHow much the story's position has moved since the last update, when available.
StoryIdThe BTW story ID for the story.
ViralityScoreA numerical score representing how strongly the story is trending.
CategoryKeysA list of top-level category keys associated with the story.
SubcategoriesA dictionary of subcategory groups and their associated values for the story.
ThemeA short thematic label for the story.
BodyA short summary paragraph describing the story.
RegionsA list of primary places or geographic regions associated with the story.
KeyPointsA list of bullet points summarizing the most important facts or takeaways from the story.
DiscourseNotesA list of notable discourse or discussion themes associated with the story.
EntitiesA list of relevant people, organizations, places, or other entities associated with the story.
KeyDatesA collection of important dates and the events associated with them.
SentimentLeftA short summary of how left-leaning sources are reacting to the story.
SentimentRightA short summary of how right-leaning sources are reacting to the story.
ArticleCountThe total number of source articles associated with the story.
ArticlesA collection of source articles for the story, including title, body, URL, and timestamp.
DiscoveredUtcThe approximate UTC timestamp for when the story was first identified by BTW.

Query	The exact search text submitted in the request.
Timestamp	The UTC timestamp for when the search response was generated.
LiveStories	The collection of matching stories that are currently active in the live BTW trends feed.
HistoricalStories	The collection of matching stories found in historical BTW trend data.
Title	The headline or main title of the story.
PositionChange	How much the story's position has moved since the last update, when available.
StoryId	The BTW story ID for the story.
ViralityScore	A numerical score representing how strongly the story is trending.
CategoryKeys	A list of top-level category keys associated with the story.
Subcategories	A dictionary of subcategory groups and their associated values for the story.
Theme	A short thematic label for the story.
Body	A short summary paragraph describing the story.
Regions	A list of primary places or geographic regions associated with the story.
KeyPoints	A list of bullet points summarizing the most important facts or takeaways from the story.
DiscourseNotes	A list of notable discourse or discussion themes associated with the story.
Entities	A list of relevant people, organizations, places, or other entities associated with the story.
KeyDates	A collection of important dates and the events associated with them.
SentimentLeft	A short summary of how left-leaning sources are reacting to the story.
SentimentRight	A short summary of how right-leaning sources are reacting to the story.
ArticleCount	The total number of source articles associated with the story.
Articles	A collection of source articles for the story, including title, body, URL, and timestamp.
DiscoveredUtc	The approximate UTC timestamp for when the story was first identified by BTW.

DEPRECIATED GET https://btw.co/api/trends/feed sample response

Returns the current top 10 trending stories.

Query Parameters (optional)
GET https://btw.co/api/trends/feed?
include=Technology,Science
&exclude=Politics
&num=10

                            Where include and exclude can be any of the following category keys separated by commas:
                        
New,ArtsEntertainment,Business,
Culture,Law,Politics,Science,
Sports,Technology,World
                            Where num can be a number from 1 - 100.
                        


                    
Required Headers

                        Authorization: Bearer YourApiKey
                    
Optional Headers

                        Accept: application/json
                    

                        Data Dictionary
                    
                        TitleThe headline or main title of the news story.
PositionThe story's rank or placement among trending stories (e.g., 1 = most viral).
PositionChangeHow much the story's global rank (before any category filtering) has changed since the last update (e.g., +2 means it moved up two spots).
ScoreA numerical value showing how viral or significant the story is based on trend signals.
CategoryKeysA list of topic categories the story belongs to (e.g., "Business," "Technology").
BodyA short paragraph summarizing the main details of the story.
KeywordsKey terms or phrases extracted from the story to help with search, tagging, or discovery.
KeyPointsA list of bullet points summarizing the most important facts or takeaways from the story.
KeyFiguresList of important people, companies, or organizations mentioned in the story (empty if none detected).
SentimentLeftA short summary of how left-leaning sources are reacting to the story.
SentimentRightA short summary of how right-leaning sources are reacting to the story.
ArticleCountThe total number of individual articles associated with the story.
ArticlesA collection of individual articles associated with the story.
QasA collection of question-and-answer pairs providing additional context, background, or analysis related to the story.

Title	The headline or main title of the news story.
Position	The story's rank or placement among trending stories (e.g., 1 = most viral).
PositionChange	How much the story's global rank (before any category filtering) has changed since the last update (e.g., +2 means it moved up two spots).
Score	A numerical value showing how viral or significant the story is based on trend signals.
CategoryKeys	A list of topic categories the story belongs to (e.g., "Business," "Technology").
Body	A short paragraph summarizing the main details of the story.
Keywords	Key terms or phrases extracted from the story to help with search, tagging, or discovery.
KeyPoints	A list of bullet points summarizing the most important facts or takeaways from the story.
KeyFigures	List of important people, companies, or organizations mentioned in the story (empty if none detected).
SentimentLeft	A short summary of how left-leaning sources are reacting to the story.
SentimentRight	A short summary of how right-leaning sources are reacting to the story.
ArticleCount	The total number of individual articles associated with the story.
Articles	A collection of individual articles associated with the story.
Qas	A collection of question-and-answer pairs providing additional context, background, or analysis related to the story.

Break The Web presents the Live Language Model: AI in sync with the world as it moves. Powered by our breakthrough CT-X data engine, it fuses the capabilities of an LLM with continuously updating world knowledge to unlock real-time product experiences no static model or web search system can match.