Hacker Noroshi API

Read-only JSON API. No authentication required. Modeled after the official Hacker News API, with minor differences noted below.

Base URL: https://hn.llll-ll.com/api/v0

Endpoints

Path	Returns
GET /api/v0/topstories.json	Front page (HN-style ranking) story IDs
GET /api/v0/newstories.json	Newest story IDs (descending by created time)
GET /api/v0/beststories.json	Story IDs ordered by points (descending)
GET /api/v0/askstories.json	"Ask HN"-style story IDs (type=ask)
GET /api/v0/showstories.json	"Show HN"-style story IDs (type=show)
GET /api/v0/activestories.json	Stories with the most recent comments (Hacker Noroshi extension)
GET /api/v0/item/<id>.json	Story or comment by ID
GET /api/v0/user/<username>.json	User profile (lightweight)

Listings currently return up to 60 IDs (HN returns 500 — we may raise this later).

Listing example

$ curl https://hn.llll-ll.com/api/v0/topstories.json
[42, 17, 8, 3, ...]

Story item example

$ curl https://hn.llll-ll.com/api/v0/item/42.json

{
  "id": 42,
  "type": "story",
  "by": "noroshi",
  "time": 1700000000,
  "title": "Show HN: Hacker Noroshi",
  "url": "https://hn.llll-ll.com/",
  "text": null,
  "score": 45,
  "descendants": 3,
  "kids": [44, 47, 51],
  "dead": false,
  "deleted": false
}

Comment item example

{
  "id": 47,
  "type": "comment",
  "by": "tanaka",
  "time": 1700000100,
  "text": "Nice work.",
  "parent": 42,
  "score": 1,
  "kids": [],
  "dead": false,
  "deleted": false
}

User example

{
  "id": "noroshi",
  "created": 1700000000,
  "karma": 100,
  "about": ""
}

Field reference

id	Item or user identifier (number for items, string for users).
type	One of story, comment, ask, show, poll. (HN's job type is not used here.)
by	Author username. "[deleted]" if the author deleted their account.
time	Creation time as Unix seconds.
title	Story title (stories only).
url	Story URL or null for self-posts (stories only).
text	Body text (HTML allowed). May be null for URL stories.
score	Points (upvotes minus downvotes).
descendants	Total comment count (stories only).
kids	IDs of immediate child comments in chronological order (oldest first). One level only — recurse via /item/<id>.json per kid. Note: HN sorts kids by best-comment score; we sort chronologically.
parent	Parent item ID (comments only). Top-level comments point at the story; replies point at the parent comment.
dead	true if the item was killed by moderation.
deleted	true if the author deleted their account. Note: this differs from HN's deleted, which means the post itself was deleted (and content fields are dropped). On Hacker Noroshi the post content (title/text/url) is preserved when an author deletes; only by becomes "[deleted]".
created	Account creation time as Unix seconds (users only).
karma	Total karma (users only).
about	About text (users only). Empty string for deleted accounts.

Caching

Listings	Cache-Control: public, max-age=10, s-maxage=60
Items	Cache-Control: public, max-age=30, s-maxage=300
Users	Cache-Control: public, max-age=60, s-maxage=300
Errors (4xx/5xx)	Cache-Control: no-store

CORS

All endpoints respond with Access-Control-Allow-Origin: * and accept GET / OPTIONS. Calls from browser-side JS are fine.

Errors

Unknown items / users return 404 with body {"error": "not found"}. Malformed input (non-numeric ID, invalid username format) is also 404 by design, matching HN's behaviour. Internal failures return 500 with body {"error": "internal"}.

Rate limits

There is currently no per-IP rate limit on the public API. Edge caching (s-maxage) absorbs most of the load, but please be polite — keep concurrent requests low and prefer caching responses on your side.

Item ID space

Stories and comments are stored in separate tables on Hacker Noroshi, so their IDs come from different sequences and can collide. /item/<id>.json resolves a collision by checking the stories table first, then comments. This differs from HN, where every item shares a single sequence. If you need to distinguish, look at the type field in the response.

Differences from the official HN API

• Listings cap at 60 IDs (HN: 500).
• No maxitem endpoint.
• No /v0/updates stream.
• User submitted array is not included (use /user/<username> on the site instead, for now).
• Realtime / Firebase subscription is not provided. Use polling.
• activestories.json is a Hacker Noroshi extension and has no HN counterpart.
• deleted means "the author deleted their account" rather than HN's "the post was deleted". See the field reference for details.
• kids is sorted chronologically (oldest first), not by HN's best-comment ranking.
• Item IDs are not globally unique across stories and comments (see "Item ID space").

Source code: github.com/kako-jun/hacker-noroshi