1---2name: hacker-news3description: Search and browse Hacker News with API access to stories, comments, users, and hiring threads.4---5
6## Quick Reference
7
8| Topic | File |
9|-------|------|
10| API endpoints | `api.md` |
11| Search patterns | `search.md` |
12
13## Core Rules
14
15### 1. Two APIs Available
16| API | Use Case | Base URL |
17|-----|----------|----------|
18| Official HN API | Single items, real-time | `https://hacker-news.firebaseio.com/v0` |
19| Algolia Search | Full-text search, filters | `https://hn.algolia.com/api/v1` |
20
21### 2. Official API Endpoints
22- `/topstories.json` — top 500 story IDs
23- `/newstories.json` — newest 500 story IDs
24- `/beststories.json` — best stories
25- `/askstories.json` — Ask HN
26- `/showstories.json` — Show HN
27- `/jobstories.json` — job postings
28- `/item/{id}.json` — story/comment details
29- `/user/{username}.json` — user profile
30
31### 3. Algolia Search Syntax
32```
33/search?query=TERM&tags=TAG&numericFilters=FILTER
34```
35
36**Tags (combinable with AND):**
37- `story`, `comment`, `poll`, `job`, `ask_hn`, `show_hn`
38- `author_USERNAME` — posts by user
39- `story_ID` — comments on story
40
41**Numeric filters:**
42- `created_at_i>TIMESTAMP` — after date
43- `points>N` — minimum points
44- `num_comments>N` — minimum comments
45
46### 4. Common Patterns
47| Request | Endpoint |
48|---------|----------|
49| Frontpage | Official `/topstories.json` → fetch first 30 items |
50| Search posts | Algolia `/search?query=X&tags=story` |
51| User's posts | Algolia `/search?tags=author_USERNAME` |
52| Who is hiring? | Algolia `/search?query=who is hiring&tags=story,author_whoishiring` |
53| Comments on story | Algolia `/search?tags=comment,story_ID` |
54| This week's top | Algolia `/search?tags=story&numericFilters=created_at_i>WEEK_TS` |
55
56### 5. Response Handling
57- Official API returns IDs → batch fetch items (parallelize)
58- Algolia returns full objects with `hits[]` array
59- Story object: `id`, `title`, `url`, `score`, `by`, `time`, `descendants` (comment count)
60- Comment object: `id`, `text`, `by`, `parent`, `time`
61
62### 6. Rate Limits
63- Official API: No auth required, generous limits
64- Algolia: 10,000 requests/hour (no key needed)
65- Always paginate large results (`page=N`, `hitsPerPage=N`)
66
67### 7. Gotchas
68- `url` is null for Ask HN/Show HN text posts — use `text` field instead
69- `deleted` and `dead` items exist — check before displaying
70- Timestamps are Unix seconds, not milliseconds
71- Algolia `objectID` = HN item `id` (as string)