{"uid":"cap_zyGtM71MNIbITRnQ0Trme","slug":"hacker-news-stories-search-api-970b8320","name":"Hacker News Stories & Search API","description":"Hacker News stories: front-page lists (top, new, best, ask, show) or full-text search, each with title, URL, domain, points, comment count, author, time, HN link and text excerpt.","url":"https://hn.genexxis.com/hackernews?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET"],"type":"string"},"queryParams":{"type":"object","properties":{"q":{"type":"string","description":"Search query (required for mode=search)"},"days":{"type":"string","description":"Search only: limit to stories from the last N days"},"mode":{"type":"string","description":"top | new | best | ask | show | search (default top)"},"sort":{"type":"string","description":"Search only: relevance | date (default relevance)"},"tags":{"type":"string","description":"Search only: story | ask_hn | show_hn | front_page | comment (default story)"},"maxItems":{"type":"string","description":"1-50, default 20"}}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object"}}}}},"responseSchema":{"type":"json","example":{"q":"ai agents","mode":"search","sort":"relevance","count":10,"errors":[],"stories":[{"id":45678901,"url":"https://example.com/agent-tests","type":"story","hnUrl":"https://news.ycombinator.com/item?id=45678901","title":"Show HN: An open-source tool for testing AI agents","author":"jdoe","domain":"example.com","points":412,"created":"2026-10-24T14:02:11.000Z","excerpt":null,"comments":187}],"totalMatches":20055}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.005","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.002/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.002","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.002","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_vEOw1p6iaI1e6_I00hf6d","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.002","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Fetches Hacker News front-page story lists (top, new, best, ask, show) or performs full-text search across HN stories, returning titles, URLs, points, comments, authors, and excerpts.","exampleAgentPrompt":"Can you search Hacker News for the top 10 most relevant stories about AI agents from the last 7 days, sorted by relevance?","exampleUseCases":[{"title":"Tech news briefing for daily standup","prompt":"Pull the top 15 front-page Hacker News stories right now and summarize them for me so I can share highlights with my team."},{"title":"Research topic on HN","prompt":"Search Hacker News for the 20 most relevant posts about WebAssembly from the last 30 days, sorted by relevance — I want to see what the community has been discussing."},{"title":"Monitor Show HN launches","prompt":"Get me the latest 25 Show HN submissions from Hacker News so I can see what indie developers have been shipping recently."}],"resultDescription":"Returns a JSON object containing the mode/query used, a count of returned stories, and an array of story objects each with: numeric ID, title, URL, domain, author, creation timestamp, points, comment count, HN permalink, story type, and optional text excerpt. Also includes a totalMatches field for search mode.","failureModes":["Missing required 'q' parameter when mode=search returns an error","Invalid mode value returns an error or defaults to 'top'","maxItems outside 1-50 range may be clamped or rejected","days parameter with non-numeric value may cause a query error","HN API downtime causes upstream fetch failures","Payment not provided or insufficient USDC returns 402"],"whenToPreferThis":"Use this endpoint when you need structured, machine-readable Hacker News data including front-page rankings or full-text search with filtering by recency, tags (ask_hn, show_hn, front_page), and sort order. Prefer this over scraping HN directly or using the raw Algolia HN Search API when you want a clean, unified interface that handles both list modes and search in one call at low cost per request.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-30T12:31:07.153Z","isFirstParty":false,"canonicalSlug":"hacker-news-stories-search-api-970b8320"}