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