Hacker News API

This API allows you to seamlessly retrieve the top 10 trending stories currently on the front page of Hacker News. Ideal for building news aggregators or daily developer briefings.

Endpoint

POST /api/v1/hacker-news

Request Parameters

This endpoint does not require any JSON body parameters.

Field	Type	Required	Description
(None)	-	-	Send an empty JSON object {}.

Request Examples

cURL

curl -X POST https://heavstal.com.ng/api/v1/hacker-news \
-H "Content-Type: application/json" \
-H "x-api-key: <YOUR_API_KEY>" \
-d '{}'

JavaScript (Fetch)

const response = await fetch('https://heavstal.com.ng/api/v1/hacker-news', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_API_KEY>'
  },
  body: JSON.stringify({})
});

const res = await response.json();
console.log(res.data);

Heavstal SDK

import { search } from '@heavstal/api';

const news = await search.hackerNews();
console.log(news.data[0].title);

Python

import requests

url = "https://heavstal.com.ng/api/v1/hacker-news"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR_API_KEY>"
}

response = requests.post(url, headers=headers, json={})
print(response.json()["data"])

Response Examples

Success Response

{
  "status": "success",
  "creator": "HEAVSTAL TECH",
  "cached": false,
  "data": [
    {
      "id": 48713832,
      "title": "HackerRank open sourced its ATS...",
      "url": "https://danunparsed.com/p/hackerrank-open-source-ats",
      "content": null,
      "author": "sambellll",
      "score": 299,
      "time": "2026-06-29T01:44:40.000Z",
      "comments_count": 92
    }
  ]
}

Error Response

{
  "status": "error",
  "error": "Failed to fetch stories from upstream provider."
}