> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nephia.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Hacker News

> What a keyword captures on Hacker News, and what arrives in each event.

## The item

Hacker News has one content unit, an **HnItem**, and `type` says which kind it is: `story` or `comment`. Both carry an author, a timestamp and a link back to the discussion; a story additionally carries a score, a comment count and the URL it submitted.

`title` is the story's own title on a story, and the **parent story's** title on a comment. That is what lets a comment tell you what it is a comment on without a second request.

`url` is what the item submitted: the linked article on a story, and `null` on a comment and on an Ask HN post. `hnUrl` is always the discussion on `news.ycombinator.com`.

## Coverage

A search on Hacker News requires a **search term**. There is no channel, subreddit or author to scope to, so a search without one would mean "everything on Hacker News". The match runs over titles, submitted URLs and comment bodies.

| Criterion | Values | Default |
| - | - | - |
| `types` | `story`, `comment`, `all` | `all` |
| `minPoints` | integer | none |

`minPoints` filters on the score at the moment we read it, so it only narrows stories: comments carry no points. These are this Source's own criteria: on the keyword they go in the search's `overrides.filters` (see [Keywords](/keywords#create)).

Interval: **120 to 86400** seconds. At most **20** active Hacker News searches per Account. Each tick costs **1 credit**.

## What an event carries

The first tick establishes a silent baseline and emits nothing. Later ticks emit `hn_item.created` with the full item. `webhookUrl` is optional: without it the keyword still records every match, readable through `GET /v1/keywords/{id}/events` in the same shape. See [Webhooks](/webhooks#replay).

```bash theme={null}
curl -X POST https://api.nephia.cc/v1/keywords \
  -H "x-api-key: $NEPHIA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "duckdb on Hacker News",
    "refreshIntervalSeconds": 300,
    "globalCriteria": { "market": "global", "query": "duckdb" },
    "sources": [
      {
        "source": "hackernews",
        "enabled": true,
        "searches": [
          {
            "overridesEnabled": true,
            "overrides": {
              "filters": {
                "types": "all",
                "minPoints": 50
              }
            }
          }
        ]
      }
    ],
    "webhookUrl": "https://example.com/hooks/nephia"
  }'
```

A tick reads the newest matches and dedupes by id as well as by time, so an item that surfaces late still arrives exactly once.

## Errors

A temporary Source failure is **503** and is not charged; the keyword reports it in its activity, readable through `GET /v1/keywords/{id}/activity`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.