{"openapi":"3.1.0","info":{"title":"Hacker News Data","description":"This tool reads live information from Hacker News, a popular website where people share and discuss technology news. You can either ask for a current list of stories (like the Top, New, Best, Ask, Show, or Job lists) or ask for every story, job posting, and poll that was posted on one specific calendar day in the past. You can also choose to pull in the discussion comments underneath each story, including nested replies several levels deep.","version":"1.0.0","contact":{"name":"_done","url":"https://forms.gle/5KzuSFH7p8hHtDmz7","email":"info@underscoredone.com"},"x-openapi-url":"https://hackernews-data.underscoredone.com/openapi.json","x-logo":{"url":"https://underscoredone.com/logo.png","altText":"_done"},"x-guidance":"Call this when you need Hacker News content: either a current ranked list (top, new, best, ask, show, job) or every story/job/poll posted on a given UTC date. Set 'date' to switch to date mode; leave it empty to use category mode. Use 'reply_depth' and 'comment_limit' sparingly since higher values take longer. For date mode, if 'range_complete' is false in the response, call again passing the returned 'next_page_token' as 'page_token' to continue scanning the same day.","x-ai-instructions":"Call this when you need Hacker News content: either a current ranked list (top, new, best, ask, show, job) or every story/job/poll posted on a given UTC date. Set 'date' to switch to date mode; leave it empty to use category mode. Use 'reply_depth' and 'comment_limit' sparingly since higher values take longer. For date mode, if 'range_complete' is false in the response, call again passing the returned 'next_page_token' as 'page_token' to continue scanning the same day.","x-provider":"_done — single-purpose utility APIs for developers and AI agents. Pay per call with USDC on Base.","x-pricing":{"model":"pay-per-call","currency":"USDC","network":"Base Mainnet","price":"$0.01"},"x-keywords":["network","hackernews","hacker news","hn api","stories","comments","jobs","polls","date scan","developer news","utility","api","ai-agent","pay-per-call","usdc","x402"],"x-category":"network","x-provider-url":"https://underscoredone.com","x-402":{"price":"$0.01","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","pay_to":"0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08","facilitator":"https://api.cdp.coinbase.com/platform/v2/x402","scheme":"exact","description":"This tool reads live information from Hacker News, a popular website where people share and discuss technology news. You can either ask for a current list of stories (like the Top, New, Best, Ask, Show, or Job lists) or ask for every story, job posting, and poll that was posted on one specific calendar day in the past. You can also choose to pull in the discussion comments underneath each story, including nested replies several levels deep.","mime_type":"application/json"}},"paths":{"/fetch":{"post":{"tags":["Network"],"summary":"Get current Hacker News lists or scan a past date for stories, jobs, and polls, with optional comment threads.","description":"Get a current Hacker News list (top, new, best, ask, show, or job), or scan everything posted on one specific calendar day, optionally pulling in discussion comments and their nested replies.","operationId":"handler_fetch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"},"examples":{"typical":{"summary":"Typical input","value":{"category":"top","limit":5,"comment_limit":3,"reply_depth":1}},"zero_or_empty":{"summary":"Zero or empty input","value":{"category":"top","limit":0,"comment_limit":0,"reply_depth":0}},"negative_or_invalid":{"summary":"Invalid input (400 error)","value":{"category":"banana","date":"2026-13-40","limit":-5}},"large":{"summary":"Large input","value":{"date":"2026-06-29","limit":200,"reply_depth":5,"replies_per_comment":20}}}}},"required":true},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"},"examples":{"success":{"summary":"Successful response","value":{"api_version":"1.0.0","mode":"get_stories","category":"top","date":null,"count":5,"scanned":null,"range_complete":null,"next_page_token":null,"results":[{"id":48753715,"item_type":"story","category":"top","title":"ZCode – Harness for GLM-5.2","author":"chvid","url":"https://zcode.z.ai/en","points":234,"posted_at":1782943416,"comment_count":223,"comments":[{"id":48752128,"author":"seizethecheese","posted_at":1782935074,"body":"I'm somewhat surprised that this is not open source...","reply_count":9,"replies":[]}]}]}}}}}},"422":{"description":"Unprocessable — a required field is missing or the wrong type. Check the detail field for specifics.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"array"}}}}}},"402":{"description":"Payment required. Send a signed USDC payment on Base Mainnet using the x402 protocol.","headers":{"X-Payment-Response":{"description":"x402 payment challenge — base64-encoded JSON with payment details.","schema":{"type":"string"}}}},"400":{"description":"Bad request — your input failed validation or could not be processed. Check the detail field for specifics.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}},"x-ai-instructions":"Call this when you need Hacker News content: either a current ranked list (top, new, best, ask, show, job) or every story/job/poll posted on a given UTC date. Set 'date' to switch to date mode; leave it empty to use category mode. Use 'reply_depth' and 'comment_limit' sparingly since higher values take longer. For date mode, if 'range_complete' is false in the response, call again passing the returned 'next_page_token' as 'page_token' to continue scanning the same day.","x-guidance":"Call this when you need Hacker News content: either a current ranked list (top, new, best, ask, show, job) or every story/job/poll posted on a given UTC date. Set 'date' to switch to date mode; leave it empty to use category mode. Use 'reply_depth' and 'comment_limit' sparingly since higher values take longer. For date mode, if 'range_complete' is false in the response, call again passing the returned 'next_page_token' as 'page_token' to continue scanning the same day.","x-payment-info":{"price":{"fixed":{"mode":"fixed","currency":"USD","amount":"0.01"}},"protocols":[{"x402":{}}]}}}},"components":{"schemas":{"CommentModel":{"properties":{"id":{"type":"integer","title":"Id","description":"The unique number identifying this comment."},"author":{"type":"string","title":"Author","description":"The username of the person who wrote the comment."},"posted_at":{"type":"integer","title":"Posted At","description":"The moment the comment was posted, shown as a plain number of seconds since 1970."},"body":{"type":"string","title":"Body","description":"The text of the comment."},"reply_count":{"type":"integer","title":"Reply Count","description":"How many direct replies this comment has."},"replies":{"items":{"$ref":"#/components/schemas/CommentModel"},"type":"array","title":"Replies","description":"Nested replies underneath this comment, if any were requested."}},"type":"object","required":["id","author","posted_at","body","reply_count"],"title":"CommentModel","example":{"author":"seizethecheese","body":"I'm somewhat surprised that this is not open source...","id":48752128,"posted_at":1782935074,"replies":[],"reply_count":9}},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ItemModel":{"properties":{"id":{"type":"integer","title":"Id","description":"The unique number identifying this story, job, or poll."},"item_type":{"type":"string","title":"Item Type","description":"Whether this item is a story, a job posting, or a poll."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"The list this item came from, when using list mode. Empty when scanning by date."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"The headline of the post."},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"The username of the person who posted it."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The web address the post links to, if it has one."},"points":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Points","description":"The number of upvotes the post has."},"posted_at":{"type":"integer","title":"Posted At","description":"The moment the post was made, shown as a plain number of seconds since 1970."},"comment_count":{"type":"integer","title":"Comment Count","description":"The total number of comments and replies on the post."},"comments":{"items":{"$ref":"#/components/schemas/CommentModel"},"type":"array","title":"Comments","description":"Discussion comments under the post, if they were requested."}},"type":"object","required":["id","item_type","posted_at","comment_count"],"title":"ItemModel","example":{"author":"chvid","category":"top","comment_count":223,"comments":[],"id":48753715,"item_type":"story","points":234,"posted_at":1782943416,"title":"ZCode – Harness for GLM-5.2","url":"https://zcode.z.ai/en"}},"Request":{"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Which current list to pull from: top, new, best, ask, show, or job. Ignored if a date is given."},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date","description":"A calendar day in YYYY-MM-DD format (UTC). If given, the tool switches to scanning that whole day instead of using a category."},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"The largest number of results to return. Default is 30, maximum is 200.","default":30},"comment_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Comment Limit","description":"How many top-level comments to fetch per story. Default 10, maximum 100, 0 means none.","default":10},"reply_depth":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reply Depth","description":"How many levels of nested replies to fetch below each comment. Default 0, maximum 5.","default":0},"replies_per_comment":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Replies Per Comment","description":"The largest number of replies fetched per comment at each level. Default 5, maximum 20.","default":5},"page_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Token","description":"A resume point from a previous date-scan response, used to continue scanning the same day where it left off."}},"type":"object","title":"Request","example":{"category":"top","comment_limit":3,"limit":5,"reply_depth":1}},"Response":{"properties":{"api_version":{"type":"string","title":"Api Version","description":"The version of this tool that produced the response.","default":"1.0.0"},"mode":{"type":"string","title":"Mode","description":"Whether the response came from a current list (get_stories) or a scan of one calendar day (find_by_date)."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"The list that was read from, when using list mode."},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date","description":"The calendar day that was scanned, when using date mode."},"count":{"type":"integer","title":"Count","description":"How many items are included in this response."},"scanned":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Scanned","description":"How many Hacker News items were examined while scanning a date. Empty in list mode."},"next_page_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Page Token","description":"A resume point to continue a date scan on a later call, or empty if the day is fully covered."},"range_complete":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Range Complete","description":"Whether the entire requested day has now been fully scanned. Empty in list mode."},"results":{"items":{"$ref":"#/components/schemas/ItemModel"},"type":"array","title":"Results","description":"The stories, jobs, or polls that were found."}},"type":"object","required":["mode","count","results"],"title":"Response","example":{"api_version":"1.0.0","category":"top","count":5,"mode":"get_stories","results":[{"author":"chvid","category":"top","comment_count":223,"comments":[{"author":"seizethecheese","body":"I'm somewhat surprised that this is not open source...","id":48752128,"posted_at":1782935074,"replies":[],"reply_count":9}],"id":48753715,"item_type":"story","points":234,"posted_at":1782943416,"title":"ZCode – Harness for GLM-5.2","url":"https://zcode.z.ai/en"}]}},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"siwx":{"type":"apiKey","in":"header","name":"SIGN-IN-WITH-X","description":"CAIP-122 wallet signature for repeat access after payment"}}},"servers":[{"url":"https://hackernews-data.underscoredone.com","description":"Production"}]}