API Docs · Hacker News CN

API Docs

Hacker News Chinese Edition API · v1.0.0

A read-only REST API served by a single Cloudflare Worker. It proxies the official Hacker News (Firebase) API and the Algolia HN Search API, and optionally translates story titles and comments into Simplified Chinese with Cloudflare Workers AI (@cf/meta/m2m100-1.2b).

Base URL

https://ycnews.331319.xyz

Auth: none · CORS: * · Format: JSON · Edge-cached 30–120s

Endpoints

GET/api/v1/stories

List stories — Returns a paginated list of stories for the requested feed. Titles are translated to Simplified Chinese when translate=1.

Name	In	Type	Default	Description
`type`	query	top \| new \| best \| ask \| show \| job	top	Feed id: top, new, best, ask, show, job
`page`	query	integer	1	Page number (1-based)
`limit`	query	integer	20	Items per page
`q`	query	string	-	Optional keyword filter (Algolia feeds only)
`translate`	query	0 \| 1	1	1 = Chinese titles, 0 = original English
`pretty`	query	0 \| 1	1	Pretty-printed JSON envelope

GET/api/v1/story/{id}

Get one story — Story detail from the official HN API. Add comments=1 to embed the comment tree.

Name	In	Type	Default	Description
`id` required	path	integer	-	Hacker News item id, e.g. 8863
`comments`	query	0 \| 1	-	1 = include comment tree
`depth`	query	integer	2	Comment tree depth
`max_comments`	query	integer	60	Max comments to fetch per request
`translate`	query	0 \| 1	1	Translate title/text

GET/api/v1/comments/{id}

Comment tree — Returns the nested comment tree of a story, translated when translate=1.

Name	In	Type	Default
`id` required	path	integer	-
`depth`	query	integer	2
`max`	query	integer	60
`translate`	query	0 \| 1	1

GET/api/v1/search

Search stories — Full-text search over HN stories via the Algolia HN Search API.

Name	In	Type	Default	Description
`q` required	query	string	-	Keyword, e.g. cloudflare
`page`	query	integer	1
`limit`	query	integer	20
`translate`	query	0 \| 1	1

GET/api/v1/translate

Translate a string — Translate arbitrary English text to Simplified Chinese (or any m2m100 target code such as fr, de, ja).

Name	In	Type	Default	Description
`text` required	query	string	-	Text to translate (max 900 chars)
`to`	query	string	zh	Target language code

GET/api/v1/feeds

Available feeds

No parameters.

GET/api/v1/health

Health check

No parameters.

Story object

{
  "id": 8863,
  "rank": 1,
  "title": "我的 YC 应用：Dropbox —— 把同步功能完全抛掉",
  "title_original": "My YC app: Dropbox - Throw away your USB drive",
  "url": "http://www.getdropbox.com/u/2/screencast.html",
  "domain": "getdropbox.com",
  "author": "dhouston",
  "points": 111,
  "comments": 71,
  "created_at": "2006-10-09T18:21:51.000Z",
  "created_ago": "19 年前",
  "hn_url": "https://news.ycombinator.com/item?id=8863",
  "text": null
}

Errors

Errors use the same envelope: {"ok":false,"error":{"code":"...","message":"..."}} with HTTP 400 / 404 / 405 / 500.

Quick start

curl 'https://ycnews.331319.xyz/api/v1/stories?type=top&limit=5'
curl 'https://ycnews.331319.xyz/api/v1/story/8863?comments=1&depth=2'
curl 'https://ycnews.331319.xyz/api/v1/search?q=cloudflare&limit=3'
curl 'https://ycnews.331319.xyz/api/v1/translate?text=Hello%20world&to=zh'