{"openapi":"3.1.0","info":{"title":"Hottub News","version":"0.1.0","description":"Agent-first worldwide news aggregation. See /llms.txt. Provided by Hottub, Inc.","contact":{"name":"Hottub, Inc.","url":"https://joinhottub.com"}},"servers":[{"url":"https://hottub.news"}],"paths":{"/v1/items":{"get":{"operationId":"listItems","summary":"Browse, search, or sync items","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"All words must appear in title or summary"},{"name":"lang","in":"query","schema":{"type":"string"},"description":"Comma-separated ISO 639-1"},{"name":"country","in":"query","schema":{"type":"string"},"description":"Comma-separated ISO 3166-1 alpha-2 (publisher's country)"},{"name":"topic","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string"},"description":"Source ids or publisher domains"},{"name":"kind","in":"query","schema":{"type":"string"},"description":"article, press_release, official, community, research, sponsored"},{"name":"since","in":"query","schema":{"type":"string"},"description":"RFC 3339, date, unix seconds, or age like 6h"},{"name":"until","in":"query","schema":{"type":"string"}},{"name":"after","in":"query","schema":{"type":"integer"},"description":"Sync cursor: items with seq > after, oldest first"},{"name":"before","in":"query","schema":{"type":"string"},"description":"Paging cursor from `next`"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"sponsored","in":"query","schema":{"type":"string","enum":["include","exclude","only"],"default":"include"}},{"name":"category","in":"query","schema":{"type":"string"},"description":"Comma-separated IPTC top-level categories"},{"name":"sentiment","in":"query","schema":{"type":"string"},"description":"negative, neutral, positive"},{"name":"political","in":"query","schema":{"type":"boolean"}},{"name":"tone_min","in":"query","schema":{"type":"number","minimum":-1,"maximum":1}},{"name":"tone_max","in":"query","schema":{"type":"number","minimum":-1,"maximum":1}},{"name":"match","in":"query","schema":{"type":"string","enum":["hybrid","keyword","semantic"],"default":"hybrid"},"description":"How q= matches"},{"name":"collapse","in":"query","schema":{"type":"string","enum":["story"]},"description":"One item per story"},{"name":"per_source","in":"query","schema":{"type":"integer","minimum":1,"maximum":20},"description":"At most N items per publisher (browse only)"},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","hot","positive","negative"],"default":"newest"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","ndjson","lines","md","rss","jsonfeed"],"default":"json"}}],"responses":{"200":{"description":"A page of items","headers":{"X-Cursor":{"schema":{"type":"integer"}},"Link":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}},"application/x-ndjson":{},"text/tab-separated-values":{},"text/markdown":{},"application/rss+xml":{},"application/feed+json":{}}},"400":{"$ref":"#/components/responses/Error"}}}},"/v1/items/{id}":{"get":{"operationId":"getItem","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"One item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/stories":{"get":{"operationId":"listStories","summary":"Top stories now, with briefs","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":50}},{"name":"lang","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"entity","in":"query","schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"hottub-news/stories/v1"}}}},"/v1/entities":{"get":{"operationId":"findEntities","summary":"Wikidata ids for people, organizations, places","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"hottub-news/entities/v1"}}}},"/v1/stream":{"get":{"operationId":"stream","summary":"Server-Sent Events of new matching items (same filters as /v1/items)","responses":{"200":{"description":"text/event-stream"}}}},"/v1/keys":{"post":{"operationId":"createKey","summary":"Create a free API key (optional)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"contact":{"type":"string"}},"required":["name"]}}}},"responses":{"201":{"description":"The key (shown once)"}}}},"/v1/subscriptions":{"get":{"operationId":"listSubscriptions","security":[{"key":[]}],"responses":{"200":{"description":"Subscriptions"}}},"post":{"operationId":"createSubscription","security":[{"key":[]}],"summary":"Webhook delivery for a saved query","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"webhook":{"type":"string","format":"uri"}},"required":["query","webhook"]}}}},"responses":{"201":{"description":"Subscription with signing secret"}}}},"/v1/exports":{"get":{"operationId":"listExports","summary":"Daily gzip NDJSON exports","responses":{"200":{"description":"Available days"}}}},"/v1/sections":{"get":{"operationId":"listSections","summary":"Reader sections (save money, make money, entertainment)","responses":{"200":{"description":"Sections with their interests and URLs"}}}},"/v1/sections/{section}":{"get":{"operationId":"getSection","summary":"A section's recent reports, one per story, most relevant first","parameters":[{"name":"section","in":"path","required":true,"schema":{"type":"string","enum":["save-money","make-money","entertainment"]}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":60}}],"responses":{"200":{"description":"Items"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/stories/{story}":{"get":{"operationId":"getStory","summary":"Every report of one story, newest first","parameters":[{"name":"story","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Items in the story"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/sources":{"get":{"operationId":"listSources","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"country","in":"query","schema":{"type":"string"}},{"name":"lang","in":"query","schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","lines"]}}],"responses":{"200":{"description":"Sources with health"}}}},"/v1/stats":{"get":{"operationId":"stats","responses":{"200":{"description":"Coverage over the last 24h and the current cursor"}}}},"/v1/pricing":{"get":{"operationId":"pricing","summary":"Rate card and pricing formula for paid placements","responses":{"200":{"description":"Rate card"}}}},"/v1/pricing/quote":{"get":{"operationId":"quote","parameters":[{"name":"topics","in":"query","schema":{"type":"string"}},{"name":"lang","in":"query","schema":{"type":"string"}},{"name":"country","in":"query","schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":31}},{"name":"starts","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Itemized quote (hottub-news/quote/v1)"},"422":{"$ref":"#/components/responses/Error"}}}},"/v1/sponsored":{"get":{"operationId":"listSponsored","summary":"Every paid placement currently running","responses":{"200":{"description":"Paid items"}}}},"/mcp":{"post":{"operationId":"mcp","summary":"Model Context Protocol (Streamable HTTP, stateless JSON responses)","responses":{"200":{"description":"JSON-RPC response"}}}}},"components":{"securitySchemes":{"key":{"type":"http","scheme":"bearer","description":"Optional free key from POST /v1/keys"}},"schemas":{"Item":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://hottub.news/schema/item.json","title":"hottub-news/item/v1","type":"object","required":["id","kind","title","url","published","seen","source","via"],"properties":{"id":{"type":"string","pattern":"^[ns]_[a-z2-7]{20}$","description":"n_ news (derived from canonical URL), s_ sponsored"},"seq":{"type":"integer","description":"Monotonic sync cursor"},"kind":{"enum":["article","press_release","official","community","research","sponsored"]},"title":{"type":"string","maxLength":300},"url":{"type":"string","format":"uri"},"summary":{"type":"string","maxLength":480},"published":{"type":"string","format":"date-time"},"seen":{"type":"string","format":"date-time"},"lang":{"type":"string","pattern":"^[a-z]{2}$"},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"source":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"}}},"via":{"type":"string"},"topics":{"type":"array","items":{"type":"string"}},"authors":{"type":"array","items":{"type":"string"}},"image":{"type":"string","format":"uri"},"mentions":{"type":"integer","minimum":2,"description":"Sources that linked this exact URL (omitted when 1)"},"story":{"type":"string","pattern":"^st_[a-z2-7]{20}$"},"related":{"type":"integer","description":"sort=hot / collapse=story: other reports of this story"},"score":{"type":"number","description":"q= relevance"},"category":{"enum":["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"]},"category_p":{"type":"number","minimum":0,"maximum":1},"category2":{"type":"string"},"sentiment":{"enum":["negative","neutral","positive"]},"tone":{"type":"number","minimum":-1,"maximum":1},"political":{"type":"number","minimum":0,"maximum":1},"disclosure":{"type":"object","required":["paid","label","sponsor","campaign"],"properties":{"paid":{"const":true},"label":{"type":"string"},"campaign":{"type":"string"},"sponsor":{"type":"object","required":["id","name","verified"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"verified":{"type":"boolean"}}}}}},"if":{"properties":{"kind":{"const":"sponsored"}}},"then":{"required":["disclosure"]},"else":{"not":{"required":["disclosure"]}}},"List":{"type":"object","properties":{"schema":{"const":"hottub-news/list/v1"},"item_schema":{"type":"string"},"count":{"type":"integer"},"cursor":{"type":"integer"},"next":{"type":"string"},"sponsored":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}}},"required":["schema","count","sponsored","items"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}},"responses":{"Error":{"description":"Error with a fix-it message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}