hacker-news

name	Hacker News
slug	hacker-news
version	1.0.0
description	Search and browse Hacker News with API access to stories, comments, users, and hiring threads.
metadata	{"clawdbot":{"emoji":"🟠","requires":{"bins":[]},"os":["linux","darwin","win32"]}}

Quick Reference

Topic	File
API endpoints	api.md
Search patterns	search.md

Core Rules

1. Two APIs Available

API	Use Case	Base URL
Official HN API	Single items, real-time	https://hacker-news.firebaseio.com/v0
Algolia Search	Full-text search, filters	https://hn.algolia.com/api/v1

2. Official API Endpoints

• /topstories.json — top 500 story IDs
• /newstories.json — newest 500 story IDs
• /beststories.json — best stories
• /askstories.json — Ask HN
• /showstories.json — Show HN
• /jobstories.json — job postings
• /item/{id}.json — story/comment details
• /user/{username}.json — user profile

3. Algolia Search Syntax

/search?query=TERM&tags=TAG&numericFilters=FILTER

Tags (combinable with AND):

• story, comment, poll, job, ask_hn, show_hn
• author_USERNAME — posts by user
• story_ID — comments on story

Numeric filters:

• created_at_i>TIMESTAMP — after date
• points>N — minimum points
• num_comments>N — minimum comments

4. Common Patterns

Request	Endpoint
Frontpage	Official /topstories.json → fetch first 30 items
Search posts	Algolia /search?query=X&tags=story
User's posts	Algolia /search?tags=author_USERNAME
Who is hiring?	Algolia /search?query=who is hiring&tags=story,author_whoishiring
Comments on story	Algolia /search?tags=comment,story_ID
This week's top	Algolia /search?tags=story&numericFilters=created_at_i>WEEK_TS

5. Response Handling

• Official API returns IDs → batch fetch items (parallelize)
• Algolia returns full objects with hits[] array
• Story object: id, title, url, score, by, time, descendants (comment count)
• Comment object: id, text, by, parent, time

6. Rate Limits

• Official API: No auth required, generous limits
• Algolia: 10,000 requests/hour (no key needed)
• Always paginate large results (page=N, hitsPerPage=N)

7. Gotchas

• url is null for Ask HN/Show HN text posts — use text field instead
• deleted and dead items exist — check before displaying
• Timestamps are Unix seconds, not milliseconds
• Algolia objectID = HN item id (as string)