# Social Fetch API - Hacker News endpoints
# Base URL: https://api.socialfetch.dev
# Auth: x-api-key header (sfk_...)
# Full catalog: https://www.socialfetch.dev/llms-endpoints.txt | JSON: https://www.socialfetch.dev/llms.json
# Docs hub: https://www.socialfetch.dev/docs/api | OpenAPI: https://www.socialfetch.dev/openapi.json

13 documented Hacker News operations. Do not invent paths - only the routes below (and their linked markdown pages) are supported.

## GET /v1/hackernews/search
Search Hacker News
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/hackernews/search/get.mdx
SDK: client.hackernews.search({ query: "Dropbox" })
Parameters:
- query (optional, string) - Full-text search query. Required unless `frontPageOnly`, `author`, `domain`, or `url` is set.
- type (optional, string, enum: all | story | comment | ask_hn | show_hn | launch_hn | job | poll) - Content type filter. Default: `all`.
- sort (optional, string, enum: popularity | date) - Ranking mode. Default: `popularity`.
- dateRange (optional, string, enum: 24h | week | month | year | all) - Creation-time window. Default: `all`.
- page (optional, integer) - Zero-based page index (maximum 50 pages, up to 1,000 hits).
- pageSize (optional, integer) - Hits per page. Default: 20.
- frontPageOnly (optional, boolean) - When true, restrict results to current front-page items. Allows omitting `query`.
- searchStoryText (optional, boolean) - Include story/comment text in searchable fields. Default: true. Set false to search title/URL only.
- searchAuthor (optional, boolean) - When true, include author username in the searchable fields.
- prefix (optional, boolean) - When true, enable prefix matching for query tokens.
- typoTolerance (optional, boolean) - Enable typo tolerance. Default: true.
- author (optional, string) - Restrict results to items by this Hacker News username.
- domain (optional, string) - Restrict search to story URLs matching this domain (e.g. example.com). Can omit `query`.
- url (optional, string) - Restrict search to story URLs matching this URL substring. Can omit `query`.
- minPoints (optional, integer) - Minimum points/score filter.
Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/hackernews/search?query=Dropbox" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/hackernews/feeds/{feed}
List a Hacker News feed
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/hackernews/feeds/feed/get.mdx
SDK: client.hackernews.listFeed({ feed: "top" })
Parameters:
- feed (required, string, enum: top | new | best | ask | show | jobs) - Hacker News feed: top, new, best, ask, show, or jobs.
- limit (optional, integer) - Maximum items to hydrate (1–50). Default: 30.
- offset (optional, integer) - Zero-based offset into the official feed id list.
Pagination: advance query `offset` (with `limit`); stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/hackernews/feeds/top" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/hackernews/stories/{id}
Get Hacker News story
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/hackernews/stories/id/get.mdx
SDK: client.hackernews.getStory({ id: 8863 })
Parameters:
- id (required, integer) - Hacker News story id.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `not_story`
curl "https://api.socialfetch.dev/v1/hackernews/stories/8863" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/hackernews/stories/{id}/comments
Get Hacker News story comments
Credit cost: 3 credits per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/hackernews/stories/id/comments/get.mdx
SDK: client.hackernews.getStoryComments({ id: 8863 })
Parameters:
- id (required, integer) - Hacker News story id whose comment tree should be returned.
- limit (optional, integer) - Maximum comment nodes to return in this page (1–100). Default: 50.
- cursor (optional, string) - Opaque continuation cursor from a previous response. Omit for the first page.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `not_story`
curl "https://api.socialfetch.dev/v1/hackernews/stories/8863/comments" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/hackernews/items/{id}
Get Hacker News item
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/hackernews/items/id/get.mdx
SDK: client.hackernews.getItem({ id: 8863 })
Parameters:
- id (required, integer) - Hacker News item id.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/hackernews/items/8863" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/hackernews/comments/{id}/context
Get Hacker News comment context
Credit cost: 2 credits per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/hackernews/comments/id/context/get.mdx
SDK: client.hackernews.getCommentContext({ id: 9224 })
Parameters:
- id (required, integer) - Hacker News comment id.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `not_comment`
curl "https://api.socialfetch.dev/v1/hackernews/comments/2921983/context" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/hackernews/users/{username}
Get Hacker News user profile
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/hackernews/users/username/get.mdx
SDK: client.hackernews.getUserProfile({ username: "jl" })
Parameters:
- username (required, string) - Hacker News username (case-sensitive).
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/hackernews/users/tptacek" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/hackernews/users/{username}/submissions
List Hacker News user submissions
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/hackernews/users/username/submissions/get.mdx
SDK: client.hackernews.getUserSubmissions({ username: "jl" })
Parameters:
- username (required, string) - Hacker News username (case-sensitive).
- page (optional, integer) - Zero-based page index (maximum 50 pages, up to 1,000 hits).
- pageSize (optional, integer) - Hits per page (1–50). Default: 20.
Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/hackernews/users/tptacek/submissions" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/hackernews/users/{username}/comments
List Hacker News user comments
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/hackernews/users/username/comments/get.mdx
SDK: client.hackernews.getUserComments({ username: "jl" })
Parameters:
- username (required, string) - Hacker News username (case-sensitive).
- page (optional, integer) - Zero-based page index (maximum 50 pages, up to 1,000 hits).
- pageSize (optional, integer) - Hits per page (1–50). Default: 20.
Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/hackernews/users/tptacek/comments" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/hackernews/users/{username}/favorites
List Hacker News user favorites
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/hackernews/users/username/favorites/get.mdx
SDK: client.hackernews.getUserFavorites({ username: "tptacek" })
Parameters:
- username (required, string) - Hacker News username (case-sensitive).
- page (optional, integer) - One-based HTML favorites page number. Default: 1. Each page bills 1 credit.
Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `private_or_unavailable`
curl "https://api.socialfetch.dev/v1/hackernews/users/tptacek/favorites" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/hackernews/jobs/who-is-hiring
List Who is Hiring jobs
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/hackernews/jobs/who-is-hiring/get.mdx
SDK: client.hackernews.listWhoIsHiring()
Parameters:
- month (optional, string) - Calendar month (YYYY-MM) to pin a Who is Hiring thread. Default: latest thread.
- page (optional, integer) - Zero-based page index of top-level hiring comments.
- pageSize (optional, integer) - Job rows per page (1–50). Default: 20.
Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/hackernews/jobs/who-is-hiring" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/hackernews/updates
Get Hacker News updates
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/hackernews/updates/get.mdx
SDK: client.hackernews.getUpdates()
curl "https://api.socialfetch.dev/v1/hackernews/updates" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/hackernews/maxitem
Get Hacker News max item id
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/hackernews/maxitem/get.mdx
SDK: client.hackernews.getMaxItem()
curl "https://api.socialfetch.dev/v1/hackernews/maxitem" \
  -H "x-api-key: YOUR_API_KEY"