fulcrum: "1.0"
name: hackernews_top
description: |
  Get the IDs of the current top 500 stories on Hacker News (news.ycombinator.com).
  Returns a JSON array of integer item IDs ordered by current rank.

  Use `hackernews_get_item` to fetch the content (title, URL, score, author,
  comment count) of each ID. Lists update every few minutes.

  This is the official Hacker News Firebase API, no auth, no rate limit.

schema:
  input:
    type: object
    properties: {}
  output:
    type: array
    description: Up to 500 integer item IDs in rank order
    items:
      type: integer

providers:
  primary:
    service: rest
    cost_per_call: 0
    timeout: 10
    config:
      base_url: https://hacker-news.firebaseio.com
      path: /v0/topstories.json
      method: GET
      headers:
        Accept: "application/json"

cache:
  strategy: exact
  ttl: 300  # 5 min

auth:
  required: false
  type: none

metadata:
  category: knowledge
  tags: [hackernews, news, tech, ycombinator, free, real-time]
  cost_category: free
  execution_time: fast
  read_only: true
  produces: [hn_item_id]
  chains_with: [hackernews_get_item]
  docs: "https://github.com/HackerNews/API"
  license: "MIT (HN API)"
  rate_limit: "No documented limit"
