openapi: 3.1.0
info:
title: Hacker News Data
description: This tool reads live information from Hacker News, a popular website where people share and discuss technology
news. You can either ask for a current list of stories (like the Top, New, Best, Ask, Show, or Job lists) or ask for every
story, job posting, and poll that was posted on one specific calendar day in the past. You can also choose to pull in
the discussion comments underneath each story, including nested replies several levels deep.
version: 1.0.0
contact:
name: _done
url: https://forms.gle/5KzuSFH7p8hHtDmz7
email: info@underscoredone.com
x-openapi-url: https://hackernews-data.underscoredone.com/openapi.json
x-logo:
url: https://underscoredone.com/logo.png
altText: _done
x-guidance: 'Call this when you need Hacker News content: either a current ranked list (top, new, best, ask, show, job)
or every story/job/poll posted on a given UTC date. Set ''date'' to switch to date mode; leave it empty to use category
mode. Use ''reply_depth'' and ''comment_limit'' sparingly since higher values take longer. For date mode, if ''range_complete''
is false in the response, call again passing the returned ''next_page_token'' as ''page_token'' to continue scanning the
same day.'
x-ai-instructions: 'Call this when you need Hacker News content: either a current ranked list (top, new, best, ask, show,
job) or every story/job/poll posted on a given UTC date. Set ''date'' to switch to date mode; leave it empty to use category
mode. Use ''reply_depth'' and ''comment_limit'' sparingly since higher values take longer. For date mode, if ''range_complete''
is false in the response, call again passing the returned ''next_page_token'' as ''page_token'' to continue scanning the
same day.'
x-provider: _done — single-purpose utility APIs for developers and AI agents. Pay per call with USDC on Base Mainnet or
Solana Mainnet.
x-pricing:
model: pay-per-call
currency: USDC
network: Base Mainnet or Solana Mainnet
price: $0.01
x-keywords:
- network
- hackernews
- hacker news
- hn api
- stories
- comments
- jobs
- polls
- date scan
- developer news
- utility
- api
- ai-agent
- pay-per-call
- usdc
- x402
x-category: hacker news
x-provider-url: https://underscoredone.com
x-agentcash-auth:
mode: paid
x-402:
price: $0.01
network: eip155:8453
asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
pay_to: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
facilitator: https://api.cdp.coinbase.com/platform/v2/x402
scheme: exact
description: This tool reads live information from Hacker News, a popular website where people share and discuss technology
news. You can either ask for a current list of stories (like the Top, New, Best, Ask, Show, or Job lists) or ask for
every story, job posting, and poll that was posted on one specific calendar day in the past. You can also choose to
pull in the discussion comments underneath each story, including nested replies several levels deep.
mime_type: application/json
networks:
- network: eip155:8453
asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
pay_to: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
- network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
pay_to: 8ugAWAXDB8V18kiUrGZTq1oMvU3C6Fxs8hfC6rvzQT3b
paths:
/fetch:
post:
tags:
- hacker news
- hackernews
- hacker news api
- news
- hn front page
- tech news
- hacker news stories
- top stories
- ask hn
- show hn
- hn comments
- trending tech news
- developer news
- tech sentiment
- hn jobs
summary: Get current Hacker News lists or scan a past date for stories, jobs, and polls, with optional comment threads.
description: Get a current Hacker News list (top, new, best, ask, show, or job), or scan everything posted on one specific
calendar day, optionally pulling in discussion comments and their nested replies.
operationId: handler_fetch_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Request'
required: true
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Response'
examples:
success:
summary: Successful response
value:
api_version: 1.0.0
mode: get_stories
category: top
date: null
count: 5
scanned: null
next_page_token: null
range_complete: null
results:
- id: 48753715
item_type: story
category: top
title: ZCode – Harness for GLM-5.2
author: chvid
url: https://zcode.z.ai/en
points: 234
posted_at: 1782943416
comment_count: 223
comments:
- id: 48752128
author: seizethecheese
posted_at: 1782935074
body: I'm somewhat surprised that this is not open source...
reply_count: 9
replies: []
'422':
description: Unprocessable — a required field is missing or the wrong type. Check the detail field for specifics.
content:
application/json:
schema:
type: object
properties:
detail:
type: array
'402':
description: Payment required. Send a signed USDC payment on Base Mainnet or Solana Mainnet using the x402 protocol.
headers:
X-Payment-Response:
description: x402 payment challenge — base64-encoded JSON with payment details.
schema:
type: string
'400':
description: Bad request — your input failed validation or could not be processed. Check the detail field for specifics.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
x-ai-instructions: 'Call this when you need Hacker News content: either a current ranked list (top, new, best, ask,
show, job) or every story/job/poll posted on a given UTC date. Set ''date'' to switch to date mode; leave it empty
to use category mode. Use ''reply_depth'' and ''comment_limit'' sparingly since higher values take longer. For date
mode, if ''range_complete'' is false in the response, call again passing the returned ''next_page_token'' as ''page_token''
to continue scanning the same day.'
x-guidance: 'Call this when you need Hacker News content: either a current ranked list (top, new, best, ask, show, job)
or every story/job/poll posted on a given UTC date. Set ''date'' to switch to date mode; leave it empty to use category
mode. Use ''reply_depth'' and ''comment_limit'' sparingly since higher values take longer. For date mode, if ''range_complete''
is false in the response, call again passing the returned ''next_page_token'' as ''page_token'' to continue scanning
the same day.'
x-payment-info:
price:
fixed:
mode: fixed
currency: USD
amount: '0.01'
protocols:
- x402: {}
components:
schemas:
CommentModel:
properties:
id:
type: integer
title: Id
description: The unique number identifying this comment.
author:
type: string
title: Author
description: The username of the person who wrote the comment.
posted_at:
type: integer
title: Posted At
description: The moment the comment was posted, shown as a plain number of seconds since 1970.
body:
type: string
title: Body
description: The text of the comment.
reply_count:
type: integer
title: Reply Count
description: How many direct replies this comment has.
replies:
items:
$ref: '#/components/schemas/CommentModel'
type: array
title: Replies
description: Nested replies underneath this comment, if any were requested.
type: object
required:
- id
- author
- posted_at
- body
- reply_count
title: CommentModel
example:
author: seizethecheese
body: I'm somewhat surprised that this is not open source...
id: 48752128
posted_at: 1782935074
replies: []
reply_count: 9
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ItemModel:
properties:
id:
type: integer
title: Id
description: The unique number identifying this story, job, or poll.
item_type:
type: string
title: Item Type
description: Whether this item is a story, a job posting, or a poll.
category:
anyOf:
- type: string
- type: 'null'
title: Category
description: The list this item came from, when using list mode. Empty when scanning by date.
title:
anyOf:
- type: string
- type: 'null'
title: Title
description: The headline of the post.
author:
anyOf:
- type: string
- type: 'null'
title: Author
description: The username of the person who posted it.
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: The web address the post links to, if it has one.
points:
anyOf:
- type: integer
- type: 'null'
title: Points
description: The number of upvotes the post has.
posted_at:
type: integer
title: Posted At
description: The moment the post was made, shown as a plain number of seconds since 1970.
comment_count:
type: integer
title: Comment Count
description: The total number of comments and replies on the post.
comments:
items:
$ref: '#/components/schemas/CommentModel'
type: array
title: Comments
description: Discussion comments under the post, if they were requested.
type: object
required:
- id
- item_type
- posted_at
- comment_count
title: ItemModel
example:
author: chvid
category: top
comment_count: 223
comments: []
id: 48753715
item_type: story
points: 234
posted_at: 1782943416
title: ZCode – Harness for GLM-5.2
url: https://zcode.z.ai/en
Request:
properties:
category:
anyOf:
- type: string
- type: 'null'
title: Category
description: 'Which current list to pull from: top, new, best, ask, show, or job. Ignored if a date is given.'
date:
anyOf:
- type: string
- type: 'null'
title: Date
description: A calendar day in YYYY-MM-DD format (UTC). If given, the tool switches to scanning that whole day instead
of using a category.
limit:
anyOf:
- type: integer
- type: 'null'
title: Limit
description: The largest number of results to return. Default is 30, maximum is 200.
default: 30
comment_limit:
anyOf:
- type: integer
- type: 'null'
title: Comment Limit
description: How many top-level comments to fetch per story. Default 10, maximum 100, 0 means none.
default: 10
reply_depth:
anyOf:
- type: integer
- type: 'null'
title: Reply Depth
description: How many levels of nested replies to fetch below each comment. Default 0, maximum 5.
default: 0
replies_per_comment:
anyOf:
- type: integer
- type: 'null'
title: Replies Per Comment
description: The largest number of replies fetched per comment at each level. Default 5, maximum 20.
default: 5
page_token:
anyOf:
- type: integer
- type: 'null'
title: Page Token
description: A resume point from a previous date-scan response, used to continue scanning the same day where it
left off.
type: object
title: Request
example:
category: top
comment_limit: 3
limit: 5
reply_depth: 1
Response:
properties:
api_version:
type: string
title: Api Version
description: The version of this tool that produced the response.
default: 1.0.0
mode:
type: string
title: Mode
description: Whether the response came from a current list (get_stories) or a scan of one calendar day (find_by_date).
category:
anyOf:
- type: string
- type: 'null'
title: Category
description: The list that was read from, when using list mode.
date:
anyOf:
- type: string
- type: 'null'
title: Date
description: The calendar day that was scanned, when using date mode.
count:
type: integer
title: Count
description: How many items are included in this response.
scanned:
anyOf:
- type: integer
- type: 'null'
title: Scanned
description: How many Hacker News items were examined while scanning a date. Empty in list mode.
next_page_token:
anyOf:
- type: integer
- type: 'null'
title: Next Page Token
description: A resume point to continue a date scan on a later call, or empty if the day is fully covered.
range_complete:
anyOf:
- type: boolean
- type: 'null'
title: Range Complete
description: Whether the entire requested day has now been fully scanned. Empty in list mode.
results:
items:
$ref: '#/components/schemas/ItemModel'
type: array
title: Results
description: The stories, jobs, or polls that were found.
type: object
required:
- mode
- count
- results
title: Response
example:
api_version: 1.0.0
category: top
count: 5
mode: get_stories
results:
- author: chvid
category: top
comment_count: 223
comments:
- author: seizethecheese
body: I'm somewhat surprised that this is not open source...
id: 48752128
posted_at: 1782935074
replies: []
reply_count: 9
id: 48753715
item_type: story
points: 234
posted_at: 1782943416
title: ZCode – Harness for GLM-5.2
url: https://zcode.z.ai/en
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
siwx:
type: apiKey
in: header
name: SIGN-IN-WITH-X
description: CAIP-122 wallet signature for repeat access after payment
servers:
- url: https://hackernews-data.underscoredone.com
description: Production
tags:
- name: hacker news
- name: hackernews
- name: hacker news api
- name: news
- name: hn front page
- name: tech news
- name: hacker news stories
- name: top stories
- name: ask hn
- name: show hn
- name: hn comments
- name: trending tech news
- name: developer news
- name: tech sentiment
- name: hn jobs
x402Version: 2
x-payment-accepts:
- scheme: exact
network: eip155:8453
payTo: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
- scheme: exact
network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
payTo: 8ugAWAXDB8V18kiUrGZTq1oMvU3C6Fxs8hfC6rvzQT3b
asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v