# News by Hottub > The world's news, for agents and people. Formerly Hottub News. Headlines, short summaries and links from thousands of sources — news organizations, wires, governments, space agencies, research and community sites — normalized into one flat schema with stable ids, ISO language/country codes and an incremental sync cursor. Paid press releases are always labeled. No key needed to read. Everything is GET, cached at the edge, and available in six formats. ## Fastest paths - Latest, cheapest to read: https://hottub.news/v1/items?format=lines&limit=100 - Only what's new since you last looked: https://hottub.news/v1/items?after=&format=ndjson (start with after=0; reuse the `X-Cursor` header / `cursor` field) - Search (by meaning and keyword, any language): https://hottub.news/v1/items?q=central+bank+rate+decisions&since=2d&format=md (match=keyword|semantic to force one; results carry `score`) - Is it in the news now? Keyword match counts for the last 24 and 48 hours: https://hottub.news/v1/items/count?q=election+results&lang=en (paid placements not counted; `capped`: true means the counts are lower bounds) - One item per story: add collapse=story. All reports of a story: https://hottub.news/v1/stories/ (JSON includes a neutral multi-source `brief` for widely covered stories) - Top stories now, with briefs: https://hottub.news/v1/stories?format=md (filters: lang, country, category, entity) - Reader sections, matched by meaning across languages: https://hottub.news/v1/sections/save-money, https://hottub.news/v1/sections/make-money, https://hottub.news/v1/sections/entertainment (list: https://hottub.news/v1/sections; pages at https://hottub.news/save-money etc.) - People, companies, places: https://hottub.news/v1/entities?q=tesla → Wikidata id → https://hottub.news/v1/items?entity=Q478214 - Push instead of polling: live Server-Sent Events https://hottub.news/v1/stream?category=politics&lang=en (resume with Last-Event-ID), or a webhook: POST https://hottub.news/v1/subscriptions {"query":"entity=Q312&lang=en","webhook":"https://…"} (needs a free key) - Free key (optional; higher limits, usage): POST https://hottub.news/v1/keys {"name":"my agent"} → send `Authorization: Bearer hn_…` - Bulk: daily gzip NDJSON of every item: https://hottub.news/v1/exports - Web pages (all also serve Markdown with Accept: text/markdown): the front page https://hottub.news/, the latest https://hottub.news/latest, one article with its prospects https://hottub.news/articles/, stories at https://hottub.news/stories/- (the `page` field on story objects), categories at https://hottub.news/categories/, entities at https://hottub.news/entities/-, search at https://hottub.news/search?q=…; sitemap index https://hottub.news/sitemap.xml - The live news map (the last 24 hours, country by country, like an election map: each country's leading story by its own outlets, the stories leading in the most countries, countries too quiet to call): https://hottub.news/v1/map; one country's stories: https://hottub.news/v1/map/?sort=popular|cited|relevant (popular: its outlets; cited: stories that broke there, by how far outlets elsewhere picked them up; relevant: what it covers more than the world). Pages: https://hottub.news/map and https://hottub.news/map/ (also .md and a .png share card). A country's list may carry one labeled paid placement - Newsmaps (what the news covered, by day, ISO week or month, worldwide or by region; reports counted by publisher country plus the most widely covered stories): https://hottub.news/maps/[/][.md|.json|.svg|.png] with period 2026-10-17 | 2026-w42 | 2026-10 and region africa | asia | europe | middle-east | north-america | latin-america | oceania (index: https://hottub.news/maps; final maps never change and stay online after items expire) - What everyone is covering: https://hottub.news/v1/items?sort=hot&format=md (last 48h, one item per story; `related` counts other items on the same story) - Filter: lang=en,es · country=US,IN · topic=space · kind=official · source= · since=6h · until=2026-09-26 - Variety: per_source=1 keeps at most one item per publisher (browse only; sync is always complete) - Classified: category=politics,economy-business · sentiment=negative · political=false · tone_min=0.3 · sort=positive|negative e.g. https://hottub.news/v1/items?category=science-technology&political=false&sort=positive&format=lines - One item: https://hottub.news/v1/items/ (append .md for Markdown) - Prospects for CRM by Hottub (the companies and people in an article or story): https://hottub.news/v1/items//prospects, https://hottub.news/v1/stories//prospects (format=md too). Each has add_url (CRM by Hottub's add form, filled in; a person presses Add) and propose (arguments for CRM by Hottub's propose_relationship MCP tool at https://crm.joinhottub.com/api/crm/mcp; an owner approves). MCP: find_prospects, also with q= to gather who is named across recent news on a subject - MCP (Streamable HTTP, stateless): https://hottub.news/mcp — tools: search_news, sync_news, list_stories, get_story, find_entities, find_prospects, live_map, get_news_item, list_sources, news_stats, newsmap, quote_placement. Server card: https://hottub.news/.well-known/mcp.json ## Formats (`format=` or Accept header) - json — {schema, count, cursor, next, sponsored, items[]} - ndjson — one item per line - lines — TSV: seq, id, published, kind, lang, country, source, title, url (fewest tokens) - md — Markdown bullets with summaries - rss, jsonfeed — for feed readers ## Item fields (hottub-news/item/v1) id (n_… news, s_… sponsored) · seq (sync cursor) · kind (article | press_release | official | community | research | sponsored) · title · url · summary (≤480 chars, plain text) · published · seen (RFC 3339 UTC) · lang (ISO 639-1) · country (ISO 3166-1 alpha-2, publisher's) · source {id, name, domain} · via (source we fetched through) · topics[] · authors[] · image · category (IPTC top level) · category_p (confidence 0..1) · category2 (runner-up, when ≥ 20% likely) · sentiment (negative | neutral | positive) · tone (-1..1) · political (0..1) · title_en (machine English translation, non-English items) · entities[{id: Wikidata Q-id, name, type}] · source.outlet {wikidata, type, country, designations} (Wikidata's own statements about the outlet) · story (st_… id shared by every report of the same event, across outlets and languages) · score (q= relevance) · mentions (sources that linked this exact URL, when > 1) · related (sort=hot only) · disclosure (sponsored only). Empty fields are omitted, never null. ## Stories Every served title is embedded (bge-m3, multilingual) and indexed. An item joins the story of its most similar earlier item from the last 48 hours when their similarity is ≥ 0.80 (calibrated on 9,000 headlines), otherwise it founds a new story; so a story gathers the same event across outlets and languages. Assignment runs about a minute after ingest; `story` is absent until then. sort=hot ranks stories by distinct outlets with a 12-hour half-life. ## Classification Every title is embedded once with a multilingual model (bge-m3) and scored by small linear heads trained on 8,843 headlines labeled by Llama 3.3 70B, with tone also trained on GDELT's document tone and blended with it for GDELT items. Measured on a hand-labeled multilingual gold set: category 72% top-1 / 92% top-2, sentiment 76%, political 94%. Use category_p and category2 when precision matters. Categories: arts-culture-entertainment, conflict-war, crime-law, disaster-accident, economy-business, education, environment, health, human-interest, labour, lifestyle-leisure, politics, religion, science-technology, society, sport, weather. ## Paid placements Businesses can pay through Hottub Business to place press releases in the mix. Every one has kind="sponsored" and disclosure {paid: true, label, sponsor {id, name, url, verified}, campaign}; text formats prefix the title with "[SPONSORED PRESS RELEASE · paid by …]". At most 3 per page, never first, never adjacent, never on searches or sensitive topics. Add sponsored=exclude to omit them. All running placements: https://hottub.news/v1/sponsored Pricing is public and explained: https://hottub.news/v1/pricing (rate card and formula) and https://hottub.news/v1/pricing/quote?topics=ai&days=7&lang=en. A day's price is base × topic tier × topic interest (share of the current news flow) × demand (other bookings) × targeting reach, with duration discounts. ## Coverage Thousands of RSS/Atom/JSON Feed sources in 50+ languages, the GDELT Global Knowledge Graph (every article GDELT sees, every 15 minutes, 65 languages), space and science agencies, governments and regulators, community rankings, and press wires. Some sources' terms don't allow redistribution; those are used only to weight stories (mentions, sort=hot) and topics, and are never served. ## Reference - [OpenAPI](https://hottub.news/openapi.json) - [Item JSON Schema](https://hottub.news/schema/item.json) - [Sources and their health](https://hottub.news/v1/sources) - [Coverage stats](https://hottub.news/v1/stats) ## Provider News by Hottub is provided by Hottub, Inc. — https://joinhottub.com ## Limits No key: 120 uncached requests/minute, 60 MCP calls/minute per IP. Free key: 1200/minute. Cached responses (use ETags / If-None-Match) are unlimited. Model-generated fields (title_en, category, sentiment, political, entities, briefs) can be wrong; check the linked reports. ## Terms Summaries are short excerpts supplied by publishers; the url is the story. Respect each source's terms (listed on /v1/sources). Please keep to about 1 request per second per client; cached responses are free to reuse for their max-age.