{
  "openapi": "3.0.1",
  "info": {
    "title": "Hacker News Search — Stories, Comments & Developer Sentiment",
    "description": "Search and extract stories, comments, polls, Show HN, and Ask HN posts from Hacker News. This actor uses the Algolia HN Search API to find content by keyword, filter by author, date range, minimum points, and comment count -- then returns clean, structured JSON ready for analysis, monitoring, or ...",
    "version": "1.0",
    "x-build-id": "xaCxw5saOZuFccPnQ"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/ryanclinton~hackernews-search/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-ryanclinton-hackernews-search",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/ryanclinton~hackernews-search/runs": {
      "post": {
        "operationId": "runs-sync-ryanclinton-hackernews-search",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/ryanclinton~hackernews-search/run-sync": {
      "post": {
        "operationId": "run-sync-ryanclinton-hackernews-search",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "title": "Search Query",
            "type": "string",
            "description": "Search query to find on Hacker News",
            "default": "artificial intelligence"
          },
          "mode": {
            "title": "Mode",
            "enum": [
              "search",
              "discover",
              "brand_monitor",
              "competitor_tracking",
              "hiring_intelligence",
              "show_hn_analysis"
            ],
            "type": "string",
            "description": "Pre-configured workflow. `search` is the default flexible mode. The other modes set sensible defaults so common jobs are one-click — your explicit input fields always win over the preset.",
            "default": "search"
          },
          "outputLevel": {
            "title": "Output Level",
            "enum": [
              "basic",
              "enriched",
              "intelligence"
            ],
            "type": "string",
            "description": "Shorthand for enabling enrichment toggles. `basic` = raw search results. `enriched` = author profile + GitHub enrichment auto-on. `intelligence` = same as enriched (intelligence scoring runs on every result regardless).",
            "default": "basic"
          },
          "searchType": {
            "title": "Search Type",
            "enum": [
              "relevance",
              "date"
            ],
            "type": "string",
            "description": "Sort results by relevance or date",
            "default": "relevance"
          },
          "tags": {
            "title": "Content Type",
            "enum": [
              "",
              "story",
              "comment",
              "poll",
              "show_hn",
              "ask_hn",
              "front_page"
            ],
            "type": "string",
            "description": "Filter by content type (leave empty for all types)"
          },
          "author": {
            "title": "Author",
            "type": "string",
            "description": "Filter by author username (case-sensitive)"
          },
          "minPoints": {
            "title": "Minimum Points",
            "minimum": 0,
            "type": "integer",
            "description": "Minimum number of upvotes/points"
          },
          "minComments": {
            "title": "Minimum Comments",
            "minimum": 0,
            "type": "integer",
            "description": "Minimum number of comments"
          },
          "dateFrom": {
            "title": "Date From",
            "type": "string",
            "description": "Start date in YYYY-MM-DD format"
          },
          "dateTo": {
            "title": "Date To",
            "type": "string",
            "description": "End date in YYYY-MM-DD format"
          },
          "maxResults": {
            "title": "Maximum Results",
            "minimum": 1,
            "maximum": 10000,
            "type": "integer",
            "description": "Maximum number of deduplicated results to return. Default 100. Algolia HN caps at 1,000 hits per single query; values up to 10,000 are accepted but only useful when `autoSplitLargeQueries` is enabled (the actor warns if exceeded without it).",
            "default": 100
          },
          "expandQuery": {
            "title": "Expand short queries to synonyms",
            "type": "boolean",
            "description": "When the query matches a known short form (e.g. \"AI\", \"ML\", \"k8s\", \"agents\"), runs additional searches for the canonical synonyms and dedupes results by HN object ID. Triples the API calls when active — cap maxResults appropriately.",
            "default": false
          },
          "includeAuthorProfile": {
            "title": "Enrich author profiles",
            "type": "boolean",
            "description": "Adds karma, account age (days), submission count, AND a 0–100 author influence score for every author. Uses the official HN Firebase API.",
            "default": false
          },
          "enrichGithubLinks": {
            "title": "Enrich GitHub links",
            "type": "boolean",
            "description": "When a result links to a GitHub repository, adds star count, primary language, and last-push timestamp. Set the GITHUB_TOKEN environment variable to raise the unauthenticated rate limit (60/hr) to 5,000/hr.",
            "default": false
          },
          "correlateGithub": {
            "title": "GitHub correlation (freshness, maturity, signal)",
            "type": "boolean",
            "description": "Adds repository freshness (active / recent / stale / dormant), maturity (nascent / emerging / established / mature), and a composite signal tier (high / medium / low). Auto-enables `enrichGithubLinks`.",
            "default": false
          },
          "parseHiringComments": {
            "title": "Parse Who Is Hiring comments",
            "type": "boolean",
            "description": "When fetching comments (combine with Content Type = Comments and a query like 'who is hiring'), extracts company, location, remote/on-site mode, and apply URL from each listing.",
            "default": false
          },
          "expandThreads": {
            "title": "Expand comment threads",
            "type": "boolean",
            "description": "For each story, Show HN, Ask HN, or poll result, fetch the full reply tree from the HN Firebase API and emit each comment as a separate `recordType: 'thread_comment'` dataset record. Bundled in the existing per-result charge (no extra event).",
            "default": false
          },
          "threadMaxDepth": {
            "title": "Thread Max Depth",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "Maximum reply depth to walk (1 = direct replies only).",
            "default": 3
          },
          "threadMaxComments": {
            "title": "Thread Max Comments per Run",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Hard cap on total thread_comment records emitted across all parents in this run, to keep dataset size bounded.",
            "default": 100
          },
          "includeInsights": {
            "title": "Heuristic insights (sentiment, themes, risk)",
            "type": "boolean",
            "description": "Adds an `insightSummary` string, `sentiment` (bullish / bearish / mixed / neutral), `riskLevel` (high / medium / low), and `keyThemes` array per result. Pure regex + keyword matching — no LLM, no external API.",
            "default": false
          },
          "detectTrends": {
            "title": "Detect trending keywords",
            "type": "boolean",
            "description": "Run two date-bounded searches (current `trendWindowDays` window vs the previous equal-length window), extract 1/2/3-grams from titles + story bodies + comments, and compute growth rates. Writes a `TREND_SUMMARY` key-value record and pushes top trends as `recordType: 'trend'` dataset records.",
            "default": false
          },
          "trendWindowDays": {
            "title": "Trend Window (days)",
            "minimum": 1,
            "maximum": 90,
            "type": "integer",
            "description": "Length of the comparison window for trend detection. Each side uses this many days (current vs previous).",
            "default": 7
          },
          "trendMinMentions": {
            "title": "Trend Min Mentions",
            "minimum": 1,
            "type": "integer",
            "description": "Minimum mention count in the current window for a term to be considered a trend.",
            "default": 3
          },
          "trendMinGrowthPercent": {
            "title": "Trend Min Growth %",
            "minimum": 0,
            "type": "integer",
            "description": "Minimum growth percentage versus the baseline window (e.g. 100 = at least doubled).",
            "default": 100
          },
          "trendMaxTerms": {
            "title": "Trend Max Terms",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Maximum number of trending terms to surface.",
            "default": 50
          },
          "compareMode": {
            "title": "Compare Mode",
            "enum": [
              "none",
              "previous_period",
              "explicit"
            ],
            "type": "string",
            "description": "Run two searches and compute deltas. `none` (default) skips comparison. `previous_period` uses dateFrom/dateTo as period A and shifts back by the same length for period B. `explicit` uses the four `compareDateFromA/ToA/FromB/ToB` inputs.",
            "default": "none"
          },
          "compareDateFromA": {
            "title": "Period A: Date From",
            "type": "string",
            "description": "Start date for period A (YYYY-MM-DD). Used when compareMode = explicit."
          },
          "compareDateToA": {
            "title": "Period A: Date To",
            "type": "string",
            "description": "End date for period A (YYYY-MM-DD)."
          },
          "compareDateFromB": {
            "title": "Period B: Date From",
            "type": "string",
            "description": "Start date for period B (YYYY-MM-DD)."
          },
          "compareDateToB": {
            "title": "Period B: Date To",
            "type": "string",
            "description": "End date for period B (YYYY-MM-DD)."
          },
          "autoSplitLargeQueries": {
            "title": "Auto-split queries beyond 1,000 hits",
            "type": "boolean",
            "description": "Adaptively halve the date range when an Algolia query would exceed 900 hits, fetching each bucket separately and deduping by HN object ID. Requires both dateFrom and dateTo. Capped by `maxSplitRuns` to prevent runaway pagination.",
            "default": false
          },
          "maxSplitRuns": {
            "title": "Max Split Runs",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Maximum number of date-range buckets to fetch when auto-split is active.",
            "default": 20
          },
          "alertOnNewOnly": {
            "title": "Alert on new results only (for scheduled runs)",
            "type": "boolean",
            "description": "Tracks the IDs seen on previous runs of this query and only outputs items that are new since the last run. Use this with an Apify schedule to build a daily brand-mention or competitor monitor.",
            "default": false
          },
          "alertWebhookUrl": {
            "title": "Slack / webhook URL for alerts",
            "type": "string",
            "description": "When set together with 'Alert on new results only', POSTs a Slack-compatible JSON payload to this URL after each run. Works with Slack incoming webhooks, Discord, or any HTTP endpoint. Treat as a secret — Slack/Discord webhook URLs grant posting access to a channel."
          },
          "alertMode": {
            "title": "Alert Mode",
            "enum": [
              "all",
              "smart"
            ],
            "type": "string",
            "description": "`all` posts every new mention to the webhook. `smart` filters the webhook to mentions with signal score ≥ 50.",
            "default": "all"
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}