Hacker News

Search and browse Hacker News with API access to stories, comments, users, and hiring threads.

SKILL.md

Quality

Evals

Security

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)

Repository: wanikua/danghuangshang
Path: skills/hacker-news/SKILL.md
Commit: acea185

Last updated: about 12 hours ago
First committed: 5 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.