HnSearch

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/fiatdock-com/json-schema/fiatdock-com-hn-search-schema.json",
  "title": "HnSearch",
  "description": "Paid. Hacker News search and front page.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/fiatdock-com-news-api-openapi.yml#/components/schemas/HnSearch",
  "type": "object",
  "properties": {
    "query": {
      "type": [
        "string",
        "null"
      ],
      "description": "The search words, or null for the front page / a type listing"
    },
    "sort": {
      "type": "string",
      "description": "relevance or date"
    },
    "type": {
      "type": "string",
      "description": "Which items were searched: story, comment, ask_hn, show_hn or front_page"
    },
    "sinceHours": {
      "type": [
        "number",
        "null"
      ],
      "description": "The time window in hours, or null for none"
    },
    "count": {
      "type": "number",
      "description": "Items returned"
    },
    "totalHits": {
      "type": [
        "number",
        "null"
      ],
      "description": "How many items match in total, by the search service's (approximate) count"
    },
    "hits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The Hacker News item id"
          },
          "kind": {
            "type": [
              "string",
              "null"
            ],
            "description": "story, comment, ask_hn, show_hn, poll or job — from the item's tags"
          },
          "title": {
            "type": [
              "string",
              "null"
            ],
            "description": "The story title; null for a comment"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "The story's link (http/https only); null for a comment, an Ask HN or a text post"
          },
          "hnUrl": {
            "type": "string",
            "description": "The discussion page on news.ycombinator.com"
          },
          "author": {
            "type": [
              "string",
              "null"
            ],
            "description": "The HN username"
          },
          "points": {
            "type": [
              "number",
              "null"
            ],
            "description": "Points (upvotes) as of asOf; null for a comment"
          },
          "comments": {
            "type": [
              "number",
              "null"
            ],
            "description": "Number of comments as of asOf; null for a comment"
          },
          "createdAt": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO time the item was posted"
          },
          "text": {
            "type": [
              "string",
              "null"
            ],
            "description": "The comment or post text as plain text (HTML removed), at most 2,000 characters; null for a link-only story"
          },
          "textTruncated": {
            "type": "boolean",
            "description": "True when text was cut at 2,000 characters"
          },
          "storyTitle": {
            "type": [
              "string",
              "null"
            ],
            "description": "For a comment: the title of the story it belongs to"
          },
          "storyUrl": {
            "type": [
              "string",
              "null"
            ],
            "description": "For a comment: the link of the story it belongs to"
          }
        },
        "required": [
          "id",
          "kind",
          "title",
          "url",
          "hnUrl",
          "author",
          "points",
          "comments",
          "createdAt",
          "text",
          "textTruncated",
          "storyTitle",
          "storyUrl"
        ]
      },
      "description": "The items, in the requested order"
    },
    "source": {
      "type": "string",
      "description": "Where the data came from"
    },
    "asOf": {
      "type": "string",
      "description": "ISO time the search service was read (answers are cached for up to 60 s)"
    },
    "note": {
      "type": "string",
      "description": "How to read the order and the numbers, and their limits"
    }
  },
  "required": [
    "query",
    "sort",
    "type",
    "sinceHours",
    "count",
    "totalHits",
    "hits",
    "source",
    "asOf",
    "note"
  ]
}