Raw schema
{
"type": "object",
"properties": {
"query": {
"description": "Search terms. Supports simple keywords โ Algolia handles stemming and relevance, and a hit must contain every term. Matching is typo-tolerant and the last term also matches as a prefix (zig matches Zigbee); wrap a term in double quotes to match it exactly (\"zig\"), or put - before one to exclude it (\"zig\" -devlog). Trimmed before searching; blank or whitespace-only input is rejected. To find discussions of a page, pass its URL alone: a query with no spaces that starts with http://, https://, or www. is searched without that prefix, so submissions under either scheme, with or without www., all match. Omit for a filter-only search, which needs at least one of tags, author, storyId, minPoints, minComments, 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\". \"front_page\" is the HN front page right now (about 30 stories); no filter selects stories from past front pages. The nearest proxy is \"story\" with dateRange and minPoints โ without a query, the default relevance sort ranks by points. Omit to search all types, which also returns poll options (type \"pollopt\"): records with only an id, author, vote count, and date โ hn_get_thread reads an option's text and poll.",
"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. Matches the HN username exactly and is case-sensitive, so a re-cased name finds nothing. Trimmed, and one leading @ is dropped, so \"@pg\" searches pg; a name that still holds whitespace is rejected as a display name. 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, from a poll hit's own id (poll hits carry no storyId), or from hn_get_thread โ the root item's id, or its item.storyId when the root is a comment. 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
},
"minComments": {
"description": "Minimum comment count. Applies to stories and polls, including the ask_hn, show_hn, and front_page subsets. Any minComments, 0 included, excludes comments, jobs, and poll options, which carry no comment count in the search index, so an untagged search returns only stories and polls โ combining it with tags \"comment\" or \"job\" is rejected.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"count": {
"default": 10,
"description": "Number of results to return, at most 50 per call. A larger value is served at 50: the search runs at count 50 from the hit where the requested page starts, and the notice names the count and page to pass next. With page above 0, that hit (page ร count) must begin a page of 50 hits.",
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"page": {
"default": 0,
"description": "Page number for pagination (0-indexed), counted in pages of count results.",
"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, parentId, storyUrl, 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
}