# Hacker News API
> Search Hacker News stories and comments by relevance or date, read the live front page, and fetch full item threads with their comment trees. Filter by story, Ask HN, Show HN, poll or comment. Great for tech-trend monitoring, brand and topic tracking, content aggregation and developer tools.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/hackernews-api/..."
```

## Pricing
- **Free** (Free) — 2,000 calls/Mo, 2 req/s
- **Basic** ($7/Mo) — 60,000 calls/Mo, 8 req/s
- **Pro** ($19/Mo) — 350,000 calls/Mo, 25 req/s
- **Mega** ($49/Mo) — 1,500,000 calls/Mo, 75 req/s

## Endpoints

### Hacker News

#### `GET /v1/frontpage` — Current front page

**Parameters:**
- `limit` (query, optional, string) — Max 1-50 Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hackernews-api/v1/frontpage?limit=30"
```

**Response:**
```json
{
    "data": {
        "count": 30,
        "results": [
            {
                "id": "48324712",
                "url": "https://www.owenmcgrann.com/p/the-dead-economy-theory",
                "tags": [
                    "story",
                    "author_WillDaSilva",
                    "story_48324712",
                    "front_page"
                ],
                "text": null,
                "title": "The dead economy theory",
                "author": "WillDaSilva",
                "hn_url": "https://news.ycombinator.com/item?id=48324712",
                "points": 809,
                "created_at": "2026-05-29T15:46:24Z",
                "num_comments": 986
            },
            {
                "id": "48324499",
                "url": "https://rockstarintel.com/gta-6-developers-announce-rockstar-games-union/",
                "tags": [
                    "story",
                    "author_AndrewKemendo",
                    "story_48324499",
                    "front_page"
                ],
                "text": null,
                "title": "GTA 6 Developers Unionize",
                "author": "AndrewKemendo",
                "hn_url": "https://news.ycombinator.com/item?id=48324499",
                "points": 605,
                "created_at": "2026-05-29T15:32:55Z",
                "num_comments": 417
            },
            {
                "id": "48309233",
                "url": "https://www.latimes.com/california/story/2026-
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/item` — Item + comment tree

**Parameters:**
- `id` (query, required, string) — Numeric HN item id Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hackernews-api/v1/item?id=1"
```

**Response:**
```json
{
    "data": {
        "id": "1",
        "url": "http://ycombinator.com",
        "text": null,
        "type": "story",
        "title": "Y Combinator",
        "author": "pg",
        "hn_url": "https://news.ycombinator.com/item?id=1",
        "points": 57,
        "children": [
            {
                "id": "15",
                "url": null,
                "text": ""the rising star of venture capital" -unknown VC eating lunch on SHR",
                "type": "comment",
                "title": null,
                "author": "sama",
                "hn_url": "https://news.ycombinator.com/item?id=15",
                "points": null,
                "children": [
                    {
                        "id": "17",
                        "url": null,
                        "text": "Is there anywhere to eat on Sandhill Road?",
                        "type": "comment",
                        "title": null,
                        "author": "pg",
                        "hn_url": "https://news.ycombinator.com/item?id=17",
                        "points": null,
                        "children": [
                            {
                                "id": "1079",
                                "url": null,
                                "text": "sure",
                                "type": "comment",
                                "title": null,
                                "author": "dmon",
                                "hn_url": "
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search stories/comments

**Parameters:**
- `q` (query, required, string) — Search term Example: `openai`
- `limit` (query, optional, string) — Max 1-50 Example: `10`
- `sort` (query, optional, string) — relevance or date Example: `relevance`
- `type` (query, optional, string) — story ask_hn show_hn poll comment Example: `story`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hackernews-api/v1/search?q=openai&limit=10&sort=relevance&type=story"
```

**Response:**
```json
{
    "data": {
        "sort": "relevance",
        "type": "story",
        "count": 10,
        "query": "openai",
        "total": 25362,
        "results": [
            {
                "id": "38309611",
                "url": "https://openai.com/blog/openai-announces-leadership-transition",
                "tags": [
                    "story",
                    "author_davidbarker",
                    "story_38309611"
                ],
                "text": null,
                "title": "OpenAI's board has fired Sam Altman",
                "author": "davidbarker",
                "hn_url": "https://news.ycombinator.com/item?id=38309611",
                "points": 5710,
                "created_at": "2023-11-17T20:28:50Z",
                "num_comments": 2530
            },
            {
                "id": "35813322",
                "url": "https://www.semianalysis.com/p/google-we-have-no-moat-and-neither",
                "tags": [
                    "story",
                    "author_klelatti",
                    "story_35813322"
                ],
                "text": null,
                "title": "Google “We have no moat, and neither does OpenAI”",
                "author": "klelatti",
                "hn_url": "https://news.ycombinator.com/item?id=35813322",
                "points": 2455,
                "created_at": "2023-05-04T10:19:13Z",
                "num_comments": 1039
            },
            {
                "id": "44800746"
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/hackernews-api
OpenAPI spec: https://www.oanor.com/api/hackernews-api/openapi.json