# Hacker News Stories API

> Hacker News top, new and best stories, Ask/Show HN, and any item or user by id

- Vendor: `hackernewsstoriesapi` · version 1.0 · category News & Media · tags hacker news api, hn api, tech news api, y combinator news api, startup news api, top stories api
- Datasource: custom HTTP routes
- Marketplace page: https://apiclay.com/api/hackernewsstoriesapi
- This document: https://apiclay.com/docs/hackernewsstoriesapi.md
- OpenAPI 3.1: https://apiclay.com/api/hackernewsstoriesapi/openapi.json
- MCP: connect https://api.apiclay.com/v1/mcp (see https://apiclay.com/llms.txt), then `apiclay_describe_api` with vendor `hackernewsstoriesapi`
- Updated: 2026-11-18

## About

## Hacker News Stories API

Read Hacker News (Y Combinator's tech news site): the ids of the current top, new, best, Ask HN, Show HN and job stories, any item (story, comment, poll, job) with title, URL, score, author, time and child comment ids, and a user's karma and profile.

Data comes from **news.ycombinator.com** (https://news.ycombinator.com). Every route calls the source's own public API and returns it unchanged.

Typical flow: `/stories?list=topstories`, then `/item?id=8863`.

### Routes

#### GET `/stories` - Story ids
| Param | In | Type | Required | Description |
|---|---|---|---|---|
| list | path | string | yes | `topstories`, `newstories`, `beststories`, `askstories`, `showstories` or `jobstories`. |

Returns: array of item ids (up to 500).

#### GET `/item` - Item
| Param | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | number | yes | Item id. |

Returns: `id`, `type`, `by`, `time`, `title`, `url`, `score`, `descendants`, `kids`, `text`.

#### GET `/user` - User
| Param | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | yes | Username, e.g. `pg`. |

Returns: `id`, `karma`, `created`, `about`, `submitted`.

### Caveats

- Story lists return ids only; read each with `/item`.
- Upstream responses can change over time. Verify fields before relying on them.
- Not affiliated with or endorsed by news.ycombinator.com.

## Pricing

- Pay as you go: 0.0012 credits/request
- Trial: 1 free requests per buyer
- Billing order: trial requests -> subscribed plan requests -> pay as you go. 1 credit's USD value is shown on the marketplace page.

## HTTP routes

Only the public, buyer-facing parts of each route are listed; vendor-side credentials stay on the gateway.

### GET /stories — Story ids
- Gateway: `GET https://api.apiclay.com/v1/api/hackernewsstoriesapi/stories`
- Public query params: `list` (string, required)
- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

### GET /item — Item
- Gateway: `GET https://api.apiclay.com/v1/api/hackernewsstoriesapi/item`
- Public query params: `id` (string, required)
- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

### GET /user — User
- Gateway: `GET https://api.apiclay.com/v1/api/hackernewsstoriesapi/user`
- Public query params: `id` (string, required)
- Upstream proxy: ApiClay proxy paid by the vendor (data cap 2 MB per call). Fetched through an ApiClay proxy paid by the vendor; a response larger than the route's data cap fails with 502 and is refunded in full.

## Call example

```bash
curl -X GET "https://api.apiclay.com/v1/api/hackernewsstoriesapi/stories?list=<list>" \
  -H "token: <YOUR_APICLAY_TOKEN>"
```

Index of every published API: https://apiclay.com/llms.txt
