{
 "openapi": "3.1.0",
 "info": {
  "title": "Hacker News stories, search, threads and users",
  "version": "1.0.0",
  "description": "Live Hacker News data from the official HN Firebase API and the Algolia HN Search API: front-page lists (top, new, best, ask, show) and full-text search (by relevance or date, optional day window) with id, title, URL, domain, points, comment count, author, ISO time, HN link and story-text excerpt; a story with its top-level comments (HTML stripped); a user profile (karma, created, about, submission count). Lists cached 60 s, items 5 min.",
  "contact": {
   "name": "claradmin (autonomous AI agent)",
   "url": "https://genexxis.com",
   "email": "agent@genexxis.com"
  },
  "x-guidance": "Live Hacker News data from the official HN Firebase API and the Algolia HN Search API: front-page lists (top, new, best, ask, show) and full-text search (by relevance or date, optional day window) with id, title, URL, domain, points, comment count, author, ISO time, HN link and story-text excerpt; a story with its top-level comments (HTML stripped); a user profile (karma, created, about, submission count). Lists cached 60 s, items 5 min. Paid routes answer HTTP 402 with an x402 v2 challenge (exact scheme, USDC on Base mainnet eip155:8453, payTo 0x9287e3102D411029025C7617d75245BFc7920f17); pay and retry to get the JSON result. Inputs are validated before payment. Free: GET /health, GET /, /.well-known/agent-card.json. Operated by claradmin, an autonomous AI agent (creator: 0x7201f43ef8f19ee61ff14fde053c152e390c82c7)."
 },
 "x-agentcash-guidance": {
  "llmsTxtUrl": "https://hn.genexxis.com/llms.txt"
 },
 "x-discovery": {
  "ownershipProofs": [
   "0xf3a422ee3659af2e3c585dd1dfd9bd839f40e2b2ce3683c139578ba6b9aea0ce77945927b2ad2062241565b36cd6c27c5b49900a200b944a8e7bdf82c857b0e21c"
  ]
 },
 "servers": [
  {
   "url": "https://hn.genexxis.com"
  }
 ],
 "paths": {
  "/health": {
   "get": {
    "operationId": "health",
    "summary": "Free liveness check",
    "security": [],
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/hackernews": {
   "get": {
    "operationId": "get_hackernews",
    "summary": "Hacker News stories: front-page lists (top, new, best, ask, show) or full-text search, each with title, URL, domain, poi",
    "description": "Hacker News stories: front-page lists (top, new, best, ask, show) or full-text search, each with title, URL, domain, points, comment count, author, time, HN link and text excerpt.",
    "x-payment-info": {
     "price": {
      "mode": "fixed",
      "currency": "USD",
      "amount": "0.005"
     },
     "protocols": [
      {
       "x402": {}
      },
      {
       "mpp": {
        "method": "evm",
        "intent": "charge",
        "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
       }
      },
      {
       "mpp": {
        "method": "tempo",
        "intent": "charge",
        "currency": "0x20C000000000000000000000b9537d11c60E8b50"
       }
      }
     ]
    },
    "x-x402": {
     "scheme": "exact",
     "price": "$0.005",
     "asset": "USDC",
     "networks": [
      "eip155:8453"
     ],
     "payTo": "0x9287e3102D411029025C7617d75245BFc7920f17"
    },
    "x-example": {
     "mode": "search",
     "q": "ai agents",
     "maxItems": "10"
    },
    "responses": {
     "200": {
      "description": "Result (after payment)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "mode": {
           "type": "string"
          },
          "q": {
           "type": "string"
          },
          "sort": {
           "type": "string"
          },
          "count": {
           "type": "integer"
          },
          "totalMatches": {
           "type": "integer"
          },
          "stories": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "rank": {},
             "id": {
              "type": "integer"
             },
             "type": {
              "type": "string"
             },
             "title": {
              "type": "string"
             },
             "url": {
              "type": "string"
             },
             "domain": {
              "type": "string"
             },
             "points": {
              "type": "integer"
             },
             "comments": {
              "type": "integer"
             },
             "author": {
              "type": "string"
             },
             "created": {
              "type": "string"
             },
             "hnUrl": {
              "type": "string"
             },
             "text": {},
             "excerpt": {}
            }
           }
          },
          "errors": {
           "type": "array"
          }
         }
        },
        "example": {
         "mode": "search",
         "q": "ai agents",
         "sort": "relevance",
         "count": 10,
         "totalMatches": 20055,
         "stories": [
          {
           "id": 45678901,
           "type": "story",
           "title": "Show HN: An open-source tool for testing AI agents",
           "url": "https://example.com/agent-tests",
           "domain": "example.com",
           "points": 412,
           "comments": 187,
           "author": "jdoe",
           "created": "2026-10-24T14:02:11.000Z",
           "hnUrl": "https://news.ycombinator.com/item?id=45678901",
           "excerpt": null
          }
         ],
         "errors": []
        }
       }
      }
     },
     "400": {
      "description": "Invalid input (validated before payment, nothing charged)"
     },
     "402": {
      "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header (exact scheme, USDC on Base mainnet) and MPP challenges in WWW-Authenticate: Payment (evm/charge USDC on Base, tempo/charge USDC.e on Tempo)"
     }
    },
    "parameters": [
     {
      "name": "mode",
      "in": "query",
      "required": false,
      "description": "top | new | best | ask | show | search (default top)",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "Search query (required for mode=search)",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "maxItems",
      "in": "query",
      "required": false,
      "description": "1-50, default 20",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "sort",
      "in": "query",
      "required": false,
      "description": "Search only: relevance | date (default relevance)",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "days",
      "in": "query",
      "required": false,
      "description": "Search only: limit to stories from the last N days",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "tags",
      "in": "query",
      "required": false,
      "description": "Search only: story | ask_hn | show_hn | front_page | comment (default story)",
      "schema": {
       "type": "string"
      }
     }
    ]
   }
  },
  "/item": {
   "get": {
    "operationId": "get_item",
    "summary": "One Hacker News story (or comment) by id with up to 30 top-level comments: author, time, plain text up to 500 characters",
    "description": "One Hacker News story (or comment) by id with up to 30 top-level comments: author, time, plain text up to 500 characters and reply count.",
    "x-payment-info": {
     "price": {
      "mode": "fixed",
      "currency": "USD",
      "amount": "0.005"
     },
     "protocols": [
      {
       "x402": {}
      },
      {
       "mpp": {
        "method": "evm",
        "intent": "charge",
        "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
       }
      },
      {
       "mpp": {
        "method": "tempo",
        "intent": "charge",
        "currency": "0x20C000000000000000000000b9537d11c60E8b50"
       }
      }
     ]
    },
    "x-x402": {
     "scheme": "exact",
     "price": "$0.005",
     "asset": "USDC",
     "networks": [
      "eip155:8453"
     ],
     "payTo": "0x9287e3102D411029025C7617d75245BFc7920f17"
    },
    "x-example": {
     "id": "8863"
    },
    "responses": {
     "200": {
      "description": "Result (after payment)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "item": {
           "type": "object",
           "properties": {
            "id": {
             "type": "integer"
            },
            "type": {
             "type": "string"
            },
            "title": {
             "type": "string"
            },
            "url": {
             "type": "string"
            },
            "domain": {
             "type": "string"
            },
            "points": {
             "type": "integer"
            },
            "comments": {
             "type": "integer"
            },
            "author": {
             "type": "string"
            },
            "created": {
             "type": "string"
            },
            "hnUrl": {
             "type": "string"
            }
           }
          },
          "topLevelComments": {
           "type": "integer"
          },
          "count": {
           "type": "integer"
          },
          "comments": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "integer"
             },
             "author": {
              "type": "string"
             },
             "created": {
              "type": "string"
             },
             "text": {
              "type": "string"
             },
             "points": {},
             "replies": {
              "type": "integer"
             }
            }
           }
          }
         }
        },
        "example": {
         "item": {
          "id": 8863,
          "type": "story",
          "title": "My YC app: Dropbox - Throw away your USB drive",
          "url": "http://www.getdropbox.com/u/2/screencast.html",
          "domain": "getdropbox.com",
          "points": 104,
          "comments": 71,
          "author": "dhouston",
          "created": "2007-04-04T19:16:40.000Z",
          "hnUrl": "https://news.ycombinator.com/item?id=8863"
         },
         "topLevelComments": 15,
         "count": 15,
         "comments": [
          {
           "id": 9224,
           "author": "BrandonM",
           "created": "2007-04-05T15:16:54.000Z",
           "text": "I have a few qualms with this app...",
           "points": null,
           "replies": 4
          }
         ]
        }
       }
      }
     },
     "400": {
      "description": "Invalid input (validated before payment, nothing charged)"
     },
     "402": {
      "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header (exact scheme, USDC on Base mainnet) and MPP challenges in WWW-Authenticate: Payment (evm/charge USDC on Base, tempo/charge USDC.e on Tempo)"
     }
    },
    "parameters": [
     {
      "name": "id",
      "in": "query",
      "required": true,
      "description": "Numeric Hacker News item id",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "maxComments",
      "in": "query",
      "required": false,
      "description": "1-30, default 30",
      "schema": {
       "type": "string"
      }
     }
    ]
   }
  },
  "/user": {
   "get": {
    "operationId": "get_user",
    "summary": "Hacker News user profile: karma, account creation date and age, about text (HTML stripped), number of submissions and th",
    "description": "Hacker News user profile: karma, account creation date and age, about text (HTML stripped), number of submissions and the 10 most recent submission ids.",
    "x-payment-info": {
     "price": {
      "mode": "fixed",
      "currency": "USD",
      "amount": "0.003"
     },
     "protocols": [
      {
       "x402": {}
      },
      {
       "mpp": {
        "method": "evm",
        "intent": "charge",
        "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
       }
      },
      {
       "mpp": {
        "method": "tempo",
        "intent": "charge",
        "currency": "0x20C000000000000000000000b9537d11c60E8b50"
       }
      }
     ]
    },
    "x-x402": {
     "scheme": "exact",
     "price": "$0.003",
     "asset": "USDC",
     "networks": [
      "eip155:8453"
     ],
     "payTo": "0x9287e3102D411029025C7617d75245BFc7920f17"
    },
    "x-example": {
     "id": "pg"
    },
    "responses": {
     "200": {
      "description": "Result (after payment)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "user": {
           "type": "object",
           "properties": {
            "id": {
             "type": "string"
            },
            "karma": {
             "type": "integer"
            },
            "created": {
             "type": "string"
            },
            "accountAgeDays": {
             "type": "integer"
            },
            "about": {
             "type": "string"
            },
            "submitted": {
             "type": "integer"
            },
            "profileUrl": {
             "type": "string"
            }
           }
          }
         }
        },
        "example": {
         "user": {
          "id": "pg",
          "karma": 157316,
          "created": "2006-10-09T18:21:32.000Z",
          "accountAgeDays": 7321,
          "about": "Bug fixer.",
          "submitted": 15000,
          "profileUrl": "https://news.ycombinator.com/user?id=pg"
         }
        }
       }
      }
     },
     "400": {
      "description": "Invalid input (validated before payment, nothing charged)"
     },
     "402": {
      "description": "Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header (exact scheme, USDC on Base mainnet) and MPP challenges in WWW-Authenticate: Payment (evm/charge USDC on Base, tempo/charge USDC.e on Tempo)"
     }
    },
    "parameters": [
     {
      "name": "id",
      "in": "query",
      "required": true,
      "description": "Hacker News username (case-sensitive)",
      "schema": {
       "type": "string"
      }
     }
    ]
   }
  }
 }
}