> ## 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 Nephia Watch on Hacker News captures, 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 Watch on Hacker News requires a **search term**. There is no channel, subreddit or author to scope to, so a Watch 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`   |
| `min_points` | integer                   | —       |

`min_points` filters on the score at the moment we read it, so it only narrows stories — comments carry no points.

Interval: **120–86400** seconds. Cap: **20** active Watches 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. `webhook_url` is optional — without it the Watch still records every match, readable through `GET /v1/hackernews/watches/{id}/events`. See [Webhooks](/webhooks).

```bash theme={null}
curl -X POST https://api.nephia.cc/v1/hackernews/watches \
  -H "x-api-key: $NEPHIA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "query": "duckdb",
    "types": "all",
    "min_points": 50,
    "refresh_interval_seconds": 300,
    "webhook_url": "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 Watch reports it in its activity, readable through `GET /v1/hackernews/watches/{id}/activity`.