Developer communities API

Hacker News

Live private service · production acceptance passed

Search Hacker News stories and comments, retrieve a story, read its full comment tree, and look up user profiles.

Four authenticated endpoints read Hacker News through its public Algolia search index and the official Firebase API. Responses preserve source field names and nulls, return whole comment trees within explicit bounds, and report coverage on every request.

Base URLhttp://localhost:3015

Local development example. Replace with your service origin.

Search Hacker News

GET/v1/hackernews/search

Search the public Hacker News index by relevance. Results default to stories; use tags to select comments, polls, Show HN, Ask HN, front-page items or one author, and numericFilters to bound created_at_i, points or num_comments. Each request returns one page of at most 100 hits with source paging metadata. The source exposes at most 1,000 hits per query.

Query parameters

Field	Type	Description
query	string	Required free-text search term, 1–500 characters.
tags	string	Comma-separated source tags: story, comment, poll, pollopt, job, show_hn, ask_hn, launch_hn, front_page, author_<username> or story_<id>. Top-level commas are AND; a parenthesised group such as (story,comment) is OR. Defaults to story. At most 10 tags.
numericFilters	string	Comma-separated conditions on created_at_i, points or num_comments using <, <=, =, >= or > with an integer, for example created_at_i>1700000000,points>=100. At most 10 conditions. No filter by default.
hitsPerPage	string	Hits per page, 1–100; defaults to 30. The response echoes the page size applied by the source.
page	string	Zero-based page number, 0–999; defaults to 0. The response echoes the page returned by the source.

Request cURL

export BASE_URL="http://localhost:3015"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/hackernews/search" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "query=claude code" \
  --data-urlencode "tags=story" \
  --data-urlencode "hitsPerPage=30" \
  --data-urlencode "page=0"

Response fields

Field	Type	Description
requestId	string	Request correlation identifier.
accounting	object	HTTP attempts, decoded bytes and duration for the operation, including the single shared retry.
success	boolean	True when usable data is returned; inspect status and coverage for omissions.
status	string	success, partial, failed, or challenged. HTTP 200 can be partial.
sourceUrl	string	Public Hacker News search, item or user URL for the request.
fetchedAt	string	UTC retrieval time.
coverage	object	Complete means this bounded page or tree was returned without known omissions. It does not imply all matching items were enumerated.
hits	array	Ordered source hits: objectID, title, url, author, points, num_comments, story_id, story_title, story_url, story_text, comment_text, parent_id, created_at, created_at_i, updated_at and _tags. Absent source fields stay absent; source nulls are preserved. Highlight markup and child ID lists are not returned.
nbHits	integer	Source total match count; approximate when exhaustiveNbHits is false.
page	integer	Zero-based page number, 0–999; defaults to 0. The response echoes the page returned by the source.
nbPages	integer	Source page count for the requested page size.
hitsPerPage	integer	Hits per page, 1–100; defaults to 30. The response echoes the page size applied by the source.
exhaustiveNbHits	boolean	Whether nbHits is exact.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "sourceUrl": "https://hn.algolia.com/?q=claude%20code",
  "fetchedAt": "2026-09-11T00:00:00.000Z",
  "coverage": {
    "source": "public_api",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 1,
    "responseBytes": 4200,
    "durationMs": 180
  },
  "hits": [
    {
      "objectID": "8863",
      "created_at": "2007-04-04T19:16:40Z",
      "created_at_i": 1175714200,
      "updated_at": "2026-09-09T15:14:22Z",
      "author": "example",
      "title": "Synthetic story about Claude Code",
      "url": "https://example.test/story",
      "points": 104,
      "num_comments": 71,
      "story_id": 8863,
      "_tags": [
        "story",
        "author_example",
        "story_8863"
      ]
    }
  ],
  "nbHits": 1,
  "page": 0,
  "nbPages": 1,
  "hitsPerPage": 30,
  "exhaustiveNbHits": true
}

Get a Hacker News story

GET/v1/hackernews/story

Retrieve one Hacker News item by numeric ID: title, submitted URL, author, points, self-post text, poll options and creation time, with the IDs of its direct child comments. The item type is returned; comment IDs are accepted and return that comment. Use the comments endpoint for the nested discussion.

Query parameters

Field	Type	Description
id	string	Required numeric Hacker News item ID, as shown after item?id= on news.ycombinator.com.

Request cURL

export BASE_URL="http://localhost:3015"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/hackernews/story" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "id=8863"

Response fields

Field	Type	Description
id	integer	Required numeric Hacker News item ID, as shown after item?id= on news.ycombinator.com.
created_at	string	Source creation timestamp.
created_at_i	integer	Source creation Unix time in seconds.
type	string	Source item type: story, comment, poll, pollopt or job.
author	string \| null	Submitting username, or null when the source withholds it.
title	string \| null	Story title; null for comments.
url	string \| null	Submitted external link; null for self posts and comments.
text	string \| null	Self-post or comment HTML text; null when absent.
points	integer \| null	Source score; null for comments.
parent_id	integer \| null	Parent item ID; null for top-level stories.
story_id	integer \| null	ID of the containing story.
options	array	Poll option items when the source provides them.
requestId	string	Request correlation identifier.
accounting	object	HTTP attempts, decoded bytes and duration for the operation, including the single shared retry.
success	boolean	True when usable data is returned; inspect status and coverage for omissions.
status	string	success, partial, failed, or challenged. HTTP 200 can be partial.
sourceUrl	string	Public Hacker News search, item or user URL for the request.
fetchedAt	string	UTC retrieval time.
coverage	object	Complete means this bounded page or tree was returned without known omissions. It does not imply all matching items were enumerated.
children	array	Direct child comment IDs in source order, at most 5,000.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "sourceUrl": "https://news.ycombinator.com/item?id=8863",
  "fetchedAt": "2026-09-11T00:00:00.000Z",
  "coverage": {
    "source": "public_api",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 1,
    "responseBytes": 41000,
    "durationMs": 220
  },
  "id": 8863,
  "created_at": "2007-04-04T19:16:40.000Z",
  "created_at_i": 1175714200,
  "type": "story",
  "author": "example",
  "title": "Synthetic story",
  "url": "https://example.test/story",
  "text": null,
  "points": 104,
  "parent_id": null,
  "story_id": 8863,
  "options": [],
  "children": [
    8865,
    8869
  ]
}

Get a Hacker News story’s comments

GET/v1/hackernews/story/comments

Retrieve the complete nested comment tree of a Hacker News item in one request. Each comment keeps its source fields and its own children. The source serves the whole thread at once, so there is no cursor; at most 5,000 comment nodes are returned, and larger threads are truncated with explicit partial coverage. Deleted comments appear with null author and text.

Query parameters

Field	Type	Description
id	string	Required numeric Hacker News item ID; a comment ID returns that comment’s subtree.

Request cURL

export BASE_URL="http://localhost:3015"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/hackernews/story/comments" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "id=8863"

Response fields

Field	Type	Description
requestId	string	Request correlation identifier.
accounting	object	HTTP attempts, decoded bytes and duration for the operation, including the single shared retry.
success	boolean	True when usable data is returned; inspect status and coverage for omissions.
status	string	success, partial, failed, or challenged. HTTP 200 can be partial.
sourceUrl	string	Public Hacker News search, item or user URL for the request.
fetchedAt	string	UTC retrieval time.
coverage	object	Complete means this bounded page or tree was returned without known omissions. It does not imply all matching items were enumerated.
id	integer	Required numeric Hacker News item ID; a comment ID returns that comment’s subtree.
type	string	Source type of the requested item.
commentCount	integer	Number of comment nodes returned across all levels.
comments	array	Nested source comment nodes: id, author, text, created_at, created_at_i, parent_id, story_id, points, type and children, recursively, in source order.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "sourceUrl": "https://news.ycombinator.com/item?id=8863",
  "fetchedAt": "2026-09-11T00:00:00.000Z",
  "coverage": {
    "source": "public_api",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 1,
    "responseBytes": 41000,
    "durationMs": 220
  },
  "id": 8863,
  "type": "story",
  "commentCount": 2,
  "comments": [
    {
      "id": 8865,
      "created_at": "2007-04-04T19:22:55.000Z",
      "created_at_i": 1175714575,
      "type": "comment",
      "author": "example",
      "title": null,
      "url": null,
      "text": "A synthetic top-level comment.",
      "points": null,
      "parent_id": 8863,
      "story_id": 8863,
      "options": [],
      "children": [
        {
          "id": 9007,
          "created_at": "2007-04-05T01:48:11.000Z",
          "created_at_i": 1175737691,
          "type": "comment",
          "author": "replier",
          "title": null,
          "url": null,
          "text": "A synthetic reply.",
          "points": null,
          "parent_id": 8865,
          "story_id": 8863,
          "options": [],
          "children": []
        }
      ]
    }
  ]
}

Get a Hacker News profile

GET/v1/hackernews/profile

Retrieve a public Hacker News user from the official API by case-sensitive username: karma, account creation time, the about text when present, and the count of submitted items. Hacker News has no follower, following or verification concepts, so none are invented.

Query parameters

Field	Type	Description
handle	string	Required case-sensitive Hacker News username: 2–15 letters, digits, underscores or hyphens, as shown after user?id= on news.ycombinator.com.

Request cURL

export BASE_URL="http://localhost:3015"
export API_KEY="your-service-key"

curl --get "$BASE_URL/v1/hackernews/profile" \
  -H "x-api-key: $API_KEY" \
  --data-urlencode "handle=pg"

Response fields

Field	Type	Description
requestId	string	Request correlation identifier.
accounting	object	HTTP attempts, decoded bytes and duration for the operation, including the single shared retry.
success	boolean	True when usable data is returned; inspect status and coverage for omissions.
status	string	success, partial, failed, or challenged. HTTP 200 can be partial.
sourceUrl	string	Public Hacker News search, item or user URL for the request.
fetchedAt	string	UTC retrieval time.
coverage	object	Complete means this bounded page or tree was returned without known omissions. It does not imply all matching items were enumerated.
id	string	Source username.
created	integer	Account creation Unix time in seconds.
karma	integer	Current source karma.
about	string	Profile about text in source HTML; omitted when the user has none.
submittedCount	integer	Number of item IDs in the source submitted list. The IDs themselves are not returned.

Nested fields and every response variant are in the OpenAPI specification.

Response 200 · synthetic example

{
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "sourceUrl": "https://news.ycombinator.com/user?id=pg",
  "fetchedAt": "2026-09-11T00:00:00.000Z",
  "coverage": {
    "source": "public_api",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 1,
    "responseBytes": 114000,
    "durationMs": 260
  },
  "id": "pg",
  "created": 1160418092,
  "karma": 157316,
  "about": "Bug fixer.",
  "submittedCount": 15565
}

Coverage & limits

Independent, stateless worker: four concurrent operations; 20-second total deadline; at most two upstream HTTP attempts per operation with one transient retry. No automatic retry for challenges or HTTP 429.
Fixed public HTTPS origins only: hn.algolia.com for search and items, hacker-news.firebaseio.com for users. No login, cookies, browser, proxy, outbound link visits, media downloads or result storage. The service API key is never forwarded.
At most 8 MiB decoded JSON, depth 128 and 400,000 nodes per source response. Oversize or malformed responses fail explicitly.
Search: one source page of 1–100 hits, default 30, pages 0–999; the source caps every query at 1,000 hits. Tags default to story. Relevance ordering is the source’s. Highlight markup and hit child ID lists are not returned.
Story and comments: one source thread read each. Comment trees return up to 5,000 nodes, then comment_limit partial coverage; story child ID lists truncate at 5,000 with children_limit. A story’s num_comments in search can exceed the returned tree because the source counts removed comments.
Profiles: the official API’s id, created, karma and about are preserved; the unbounded submitted list is replaced by submittedCount. Usernames are case-sensitive; a different case is a missing user.
Source caching and live counters can affect freshness. Sampled search, story, comment-tree and profile reads returned real data during local and production acceptance. No credit balances, billing or caching controls are provided.

Errors & partial results

HTTP	Code / status	Meaning
200	partial	Usable data with comment_limit or children_limit warnings.
400	invalid_request	Missing, duplicate, malformed or unsupported parameters.
401	unauthorized	Missing or invalid worker API key.
404	not_found	The source reports a missing item or user.
429	upstream_rate_limited	Source throttling; no automatic retry.
502	upstream_challenged	Source rejected the unauthenticated request.
502	unsupported_page	Malformed, mismatched or non-JSON source data.
502	response_too_large / payload_too_complex	Response exceeded byte or parsing limits.
502	unsafe_redirect / request_limit / upstream_error	Bounded source retrieval could not complete.
503	busy	All worker slots are occupied.
504	timeout	Total request deadline expired.