HackerNews Getting Started: API Access & First Request (2026)

Getting started overview

The HackerNews API offers a public, read-only interface to access data from news.ycombinator.com, including stories, comments, and user profiles. Unlike many commercial APIs, it does not require an API key or explicit authentication for read operations, simplifying the initial setup process. The API is built on Google's Firebase Realtime Database, providing real-time updates for data. This guide focuses on quickly setting up your environment and making your first data retrieval.

To begin, you will primarily interact with specific Firebase endpoints that represent different data types within HackerNews. Understanding the structure of these endpoints is key to retrieving the data you need. The API provides access to the topstories, newstories, beststories, askstories, showstories, and jobstories lists, each returning an array of item IDs. Once you have these IDs, you can fetch the details for each item individually.

The HackerNews API is maintained by the community and hosted on GitHub, which serves as its primary documentation source. This resource details the available endpoints and the structure of the JSON responses. Familiarizing yourself with the HackerNews API README on GitHub is crucial for effective use.

Here's a quick reference table outlining the essential steps to get started:

Create an account and get keys

A significant advantage of the HackerNews API for read-only access is that it does not require an account, API keys, or any form of authentication. This simplifies the onboarding process considerably, allowing developers to start making requests immediately without prior registration or credential management. The API is designed for public consumption of HackerNews data, making it accessible to anyone with an internet connection.

Because there are no keys, there's no need to handle environment variables for API keys, secure storage, or rotation policies. This reduces the complexity often associated with integrating third-party APIs. Developers can directly construct their API calls using the base URL for the Firebase Realtime Database.

While authentication is not required for reading data, it's important to be aware that the underlying Firebase Realtime Database has its own usage policies and potential rate limits, which are generally generous for public read access. However, extremely high volumes of requests could potentially be throttled by Google's Firebase infrastructure. For most use cases, this should not be an immediate concern during initial development and testing.

For operations that would typically require user authentication (e.g., submitting stories or comments), the HackerNews API does not provide direct programmatic access. These actions are handled through the news.ycombinator.com website directly, requiring a user to log in via the web interface. The API's scope is strictly confined to data retrieval.

Therefore, the process of "getting keys" is entirely bypassed when working with the HackerNews API for data retrieval. You can proceed directly to making API calls once you understand the endpoint structure.

Your first request

Making your first request to the HackerNews API involves two primary steps: first, retrieving a list of item IDs (e.g., top stories), and then using those IDs to fetch the detailed information for individual items. All responses are in JSON format.

1. Retrieve a list of item IDs

The HackerNews API exposes various lists of story IDs. Let's start by fetching the IDs of the current top stories. You can do this using a simple HTTP GET request to the topstories.json endpoint.

Endpoint: https://hacker-news.firebaseio.com/v0/topstories.json

Example using curl:

curl "https://hacker-news.firebaseio.com/v0/topstories.json"

Example using JavaScript (Node.js with fetch):

async function getTopStoryIds() {
  try {
    const response = await fetch('https://hacker-news.firebaseio.com/v0/topstories.json');
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const storyIds = await response.json();
    console.log('Top Story IDs:', storyIds.slice(0, 5)); // Log first 5 IDs
    return storyIds;
  } catch (error) {
    console.error('Error fetching top story IDs:', error);
  }
}

getTopStoryIds();

The response will be a JSON array containing numerical IDs, like [38676231, 38677610, 38675765, ...].

2. Fetch details for an individual item

Once you have an item ID, you can retrieve its full details (title, URL, author, score, etc.) using the item/{id}.json endpoint. Replace {id} with an actual story ID obtained from the previous step.

Endpoint: https://hacker-news.firebaseio.com/v0/item/{id}.json

Let's assume you got the ID 38676231 from the topstories list.

Example using curl:

curl "https://hacker-news.firebaseio.com/v0/item/38676231.json"

Example using JavaScript (Node.js with fetch):

async function getItemDetails(itemId) {
  try {
    const response = await fetch(`https://hacker-news.firebaseio.com/v0/item/${itemId}.json`);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const itemDetails = await response.json();
    console.log('Item Details:', itemDetails);
    return itemDetails;
  } catch (error) {
    console.error(`Error fetching details for item ${itemId}:`, error);
  }
}

// Assuming you have an ID from the top stories list
getItemDetails(38676231);

The response will be a JSON object containing the item's properties, such as:

{
  "by": "user_name",
  "descendants": 123,
  "id": 38676231,
  "kids": [38677610, ...],
  "score": 456,
  "time": 1678886400,
  "title": "Example HackerNews Story Title",
  "type": "story",
  "url": "https://example.com/story"
}

This two-step process forms the foundation for interacting with the HackerNews API to retrieve various types of content.

Common next steps

After successfully making your first requests, you might consider these common next steps to further integrate with the HackerNews API:

1. Explore other list endpoints: Beyond topstories, the API offers newstories, beststories, askstories, showstories, and jobstories. Each provides a different filtered view of HackerNews content. You can find the full list of endpoints in the HackerNews API documentation.
2. Retrieve comments and user data: Item objects often include a kids array, which contains the IDs of direct comments. You can fetch these comment items in the same way you fetch story items. User profiles can also be accessed via user/{username}.json, providing details like karma and submission history.
3. Implement real-time updates: Since the API is built on Firebase, you can leverage Firebase's streaming capabilities for real-time updates. By appending .json?print=pretty&callback= to your URL, you can get a stream of updates. For more robust real-time integration, consider using a Firebase client library, which handles connection management and event listening.
4. Pagination and rate limiting: While the API doesn't have explicit rate limit headers for individual requests, Firebase imposes general usage limits. For lists, you'll typically retrieve a large array of IDs and then fetch individual items. To manage load, consider fetching item details in batches or implementing a delay between requests.
5. Error handling: Implement robust error handling in your application. Check HTTP response statuses and parse error messages if they occur. Although the API is public, network issues or temporary service interruptions can happen.
6. Build a client library or wrapper: For more complex applications, consider building a simple wrapper around the API calls to abstract away the direct HTTP requests and provide a more idiomatic interface for your chosen programming language.

Troubleshooting the first call

When encountering issues with your initial HackerNews API calls, consider the following common troubleshooting steps:

1. Check the URL: Ensure the endpoint URL is precisely correct, including the v0 and .json extensions. A common mistake is omitting .json at the end of the endpoint. For instance, https://hacker-news.firebaseio.com/v0/topstories will not return JSON; it needs to be https://hacker-news.firebaseio.com/v0/topstories.json.
2. Verify network connectivity: Confirm that your machine or environment has active internet access and can reach hacker-news.firebaseio.com. Firewalls or proxy settings might interfere with outbound requests.
3. Inspect HTTP status codes: Most HTTP client libraries provide access to the response status code. A 200 OK indicates success. Other codes, such as 404 Not Found (incorrect URL or item ID) or 500 Internal Server Error (server-side issue), can pinpoint the problem.
4. Examine the response body: Even if the status code is 200, the response might not be what you expect. Parse the JSON response and log it to ensure it contains valid data. Sometimes, an empty array or an unexpected structure can indicate an issue with how the request was formed or data availability.
5. Test with curl or browser: If your programmatic requests are failing, try making the same request directly in your web browser or using the curl command-line tool. This helps isolate whether the issue is with your code or with the API endpoint itself. If curl works, the problem is likely in your application's code.
6. Review Firebase Console status: The HackerNews API relies on Firebase. While less common for read-only access, if there are widespread issues, checking the Firebase Status Dashboard could provide insights into potential service disruptions.
7. Consult the API documentation: The HackerNews API README on GitHub is the authoritative source for endpoint definitions and expected data structures. Double-check that your interpretation of the API is consistent with the documentation.
8. Handle rate limits: Although not explicitly documented with headers for this API, rapid-fire requests might occasionally be throttled by Firebase. If you're making many sequential requests, try adding small delays between them to see if the issue resolves.