# Hacker News — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Browse Hacker News top/new/best/ask/show stories and job posts, search stories by keyword and timeframe, fetch user profiles, retrieve comment threads for a post, and compute basic engagement stats and trending stories.

**Category:** News & Media | **Website:** [news.ycombinator.com/](https://news.ycombinator.com/) | **Docs:** [parse.bot/marketplace/972a15f7-7702-44f9-8190-1dacc2e28620/news-ycombinator-com-api](https://parse.bot/marketplace/972a15f7-7702-44f9-8190-1dacc2e28620/news-ycombinator-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-news-ycombinator-com-api-972a15f7/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_comment_details

Get comments for a post as a flat, paginated list with filtering and sorting. Filter by specific author to see all their comments on a post. Supports sorting by newest, oldest, or relevance. Uses Algolia search API for paginated flat comment listing.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `author` | string | No | Filter comments by specific author username |
| `limit` | integer | No | Max comments per page (max 50) |
| `page` | integer | No | Page number (0-based) for pagination |
| `post_id` | string | Yes | Hacker News post ID |
| `sort_by` | string | No | Sort order |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-news-ycombinator-com-api-972a15f7/get_comment_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"author":"<string>","limit":"<integer>","page":"<integer>","post_id":"<string>","sort_by":"<string>"}'
```

### get_job_posts

Get current job postings from Hacker News. Returns jobs in reverse chronological order.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of jobs to return (max 200) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-news-ycombinator-com-api-972a15f7/get_job_posts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>"}'
```

### get_post_commenters

Get a breakdown of all commenters on a post: who commented, how many times each person commented, total replies they received, and the full text of each of their comments. Commenters are sorted by comment count (most active first). Uses Algolia items API for full nested comment tree.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Max number of commenters to return (max 100) |
| `post_id` | string | Yes | Hacker News post ID |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-news-ycombinator-com-api-972a15f7/get_post_commenters \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","post_id":"<string>"}'
```

### get_post_comments

Get nested comment threads for a specific Hacker News post. Returns recursively nested comments with author, text, and depth. Uses Algolia items API.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of top-level comments (max 50) |
| `post_id` | integer | Yes | HN post ID to fetch comments for |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-news-ycombinator-com-api-972a15f7/get_post_comments \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","post_id":"<integer>"}'
```

### get_post_stats

Compute engagement statistics (points and comments) for a set of stories. Returns max, min, median, mean, stdev, and top stories by points and comments. Uses Algolia search sorted by relevance.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of posts to analyze (max 500) |
| `story_type` | string | No | Story category |
| `timeframe` | string | No | Time filter. When specified, story_type in response becomes 'search'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-news-ycombinator-com-api-972a15f7/get_post_stats \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","story_type":"<string>","timeframe":"<string>"}'
```

### get_top_posts

Get stories from Hacker News by category. Returns formatted story data including title, URL, author, points, and comment count. Stories are returned in the same order as the HN front page for the given category.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of stories to return (max 500) |
| `story_type` | string | No | Story category to fetch |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-news-ycombinator-com-api-972a15f7/get_top_posts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","story_type":"<string>"}'
```

### get_trending

Get trending/popular stories within a timeframe, optionally filtered by domain or topic keyword. Returns stories sorted by points with domain distribution. Narrow timeframes with specific domains may return empty results when no matching stories exist in that window.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `domain` | string | No | Filter by domain or topic keyword (searches in story content and URL) |
| `limit` | integer | No | Maximum results to return (max 50) |
| `timeframe` | string | No | Time window |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-news-ycombinator-com-api-972a15f7/get_trending \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"<string>","limit":"<integer>","timeframe":"<string>"}'
```

### get_user_info

Get a Hacker News user's profile including karma, about text, account creation date, and total submissions count.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `username` | string | Yes | HN username to look up |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-news-ycombinator-com-api-972a15f7/get_user_info \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"<string>"}'
```

### search_posts

Search Hacker News stories by keyword with optional timeframe filtering. Supports relevance and date sorting, with pagination. Uses Algolia search API.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Results per page (max 50) |
| `page` | integer | No | Page number (0-indexed) |
| `query` | string | Yes | Search keyword or phrase |
| `sort_by` | string | No | Sort order |
| `timeframe` | string | No | Time filter |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-news-ycombinator-com-api-972a15f7/search_posts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>","query":"<string>","sort_by":"<string>","timeframe":"<string>"}'
```