Raw schema
{
"type": "object",
"properties": {
"query": {
"description": "Search terms. Supports simple keywords — Algolia handles stemming and relevance. Trimmed before searching; blank or whitespace-only input is rejected. Omit for a filter-only search, which needs at least one of tags, author, storyId, minPoints, or a dateRange bound.",
"type": "string",
"minLength": 1
},
"tags": {
"description": "Filter results by content type: \"story\", \"comment\", \"poll\", or \"job\", or the story subsets \"ask_hn\", \"show_hn\", and \"front_page\". Omit to search all types.",
"type": "string",
"enum": [
"story",
"comment",
"poll",
"job",
"ask_hn",
"show_hn",
"front_page"
]
},
"author": {
"description": "Filter results to a specific author. Useful for finding a user's posts on a topic (hn_get_user only shows recent submissions). Trimmed before filtering; omit the field to search all authors rather than passing a blank string.",
"type": "string",
"minLength": 1
},
"storyId": {
"description": "Restrict results to one discussion: the id of a story or poll root, combined with the other filters. Pair with tags \"comment\" to search within a thread. Take it from hits[].storyId or the root item of hn_get_thread — a comment id matches nothing.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"sort": {
"default": "relevance",
"description": "Sort order. \"relevance\" for best match, \"date\" for most recent first.",
"type": "string",
"enum": [
"relevance",
"date"
]
},
"dateRange": {
"description": "Filter to a creation-time window with a start, an end, or both. An empty object is rejected — omit dateRange instead.",
"type": "object",
"properties": {
"start": {
"description": "Exclusive lower bound — only items created strictly after this instant match. ISO 8601: YYYY, YYYY-MM, YYYY-MM-DD, or YYYY-MM-DDThh:mm[:ss[.sss]] with an optional Z or ±hh:mm offset. Reduced and date-only forms mean UTC midnight at the start of that period; a date-time without an offset is read as UTC.",
"type": "string",
"pattern": "^(\\d{4})(?:-(\\d{2})(?:-(\\d{2})(?:T(\\d{2}):(\\d{2})(?::(\\d{2})(?:\\.\\d{1,3})?)?(?:Z|[+-](\\d{2}):(\\d{2}))?)?)?)?$"
},
"end": {
"description": "Exclusive upper bound — only items created strictly before this instant match. Same formats and UTC reading as start, and must be later than start. A date-only end excludes that whole UTC day: to include it, pass the next day or a full timestamp.",
"type": "string",
"pattern": "^(\\d{4})(?:-(\\d{2})(?:-(\\d{2})(?:T(\\d{2}):(\\d{2})(?::(\\d{2})(?:\\.\\d{1,3})?)?(?:Z|[+-](\\d{2}):(\\d{2}))?)?)?)?$"
}
}
},
"minPoints": {
"description": "Minimum score. Applies to stories and polls, including the ask_hn, show_hn, and front_page subsets. Comments and jobs carry no points in the search index, so any minPoints excludes them — combining it with tags \"comment\" or \"job\" is rejected.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"count": {
"default": 30,
"description": "Number of results to return.",
"type": "integer",
"minimum": 1,
"maximum": 50
},
"page": {
"default": 0,
"description": "Page number for pagination (0-indexed).",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"view": {
"default": "full",
"description": "How much of each hit to return. \"full\" includes every field. \"compact\" omits the two body-text fields — `text` and `highlights.text` — which together can repeat a long comment twice per hit; everything else (id, title, url, domain, author, points, comment count, timestamp, parent story, title highlight, matchedWords) is unchanged. Use \"compact\" to scan many results, then pass a hit id to hn_get_thread to read the body you skipped.",
"type": "string",
"enum": [
"full",
"compact"
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
