{"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":"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"],"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/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":{"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)"},"related":{"type":"integer","description":"sort=hot: other items on the same story"},"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"}}}}}}}