Getting started overview

Integrating with Product Hunt typically involves creating an account, registering an application to obtain API credentials, and then using these credentials to make authenticated requests to the GraphQL API. The process enables developers to programmatically access data related to products, posts, and user activity on the platform. This guide outlines the steps required to get an application connected and make an initial API call.

The Product Hunt API utilizes GraphQL, which allows clients to request specific data structures, minimizing over-fetching or under-fetching of data compared to traditional REST APIs GraphQL queries overview. Authentication is managed through OAuth2, a standard for delegated authorization OAuth 2.0 specification. Product Hunt provides official SDKs for Ruby, Node.js, and Python to streamline development.

Here's a quick reference for the initial setup:

Step What to do Where
1. Create Account Register a user account on Product Hunt. Product Hunt homepage
2. Register Application Create a new application to obtain client ID and client secret. Product Hunt API help
3. Obtain Access Token Exchange client credentials for an OAuth2 access token. Product Hunt API documentation
4. Make First Request Execute a GraphQL query using the access token. Product Hunt API documentation

Create an account and get keys

To begin interacting with the Product Hunt API, you must first establish a user account. This account will be associated with any applications you register and will provide access to the developer dashboard.

1. Create a Product Hunt Account

Navigate to the Product Hunt website and sign up. You can typically use an existing social media account (e.g., Google, Twitter) or an email address to register. Complete any required profile information.

2. Register Your Application

After creating an account, you need to register a new application to obtain the necessary OAuth2 credentials. Follow these steps:

  1. Log in to your Product Hunt account.
  2. Access the Product Hunt API help page or navigate directly to the application registration section (often found under developer settings or API access).
  3. Click on 'Register a new application' or similar.
  4. Provide the required information for your application, which typically includes:
    • Application Name: A descriptive name for your project.
    • Description: A brief overview of what your application does.
    • Homepage URL: The public URL of your application (if applicable).
    • Callback URL(s): The URL(s) to which Product Hunt will redirect users after they authorize your application. For development and testing, you might use http://localhost:3000/callback or a similar local address.
  5. Submit the application registration form.

Upon successful registration, Product Hunt will provide you with a Client ID and a Client Secret. These are your application's credentials. The Client Secret should be treated as sensitive information and stored securely, never exposed in client-side code.

3. Obtain an OAuth2 Access Token

The Product Hunt API uses OAuth2 for authentication. To make requests, your application needs an access token. For server-side applications or testing, you can typically use the Client Credentials flow to obtain an access token. This involves making a POST request to the token endpoint.

Consult the Product Hunt API documentation for authentication for the precise token endpoint URL and required parameters. Generally, a request will look like this:

POST https://api.producthunt.com/v2/oauth/token
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "grant_type": "client_credentials"
}

The response will contain an access_token. This token should be included in the Authorization header of subsequent API requests as a Bearer token.

Your first request

With an access token in hand, you can now make your first authenticated request to the Product Hunt GraphQL API. The API endpoint is https://api.producthunt.com/v2/api/graphql.

Example GraphQL Query

Let's retrieve a list of recent posts. This is a common starting point to verify your API access.

Query:

query {
  posts(first: 5) {
    edges {
      node {
        id
        name
        tagline
        url
        votesCount
      }
    }
  }
}

Making the Request (using cURL)

Replace YOUR_ACCESS_TOKEN with the token you obtained in the previous step.

curl -X POST \
  https://api.producthunt.com/v2/api/graphql \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data-binary '{"query":"query { posts(first: 5) { edges { node { id name tagline url votesCount } } } }"}'

Interpreting the Response

A successful response will return a JSON object containing a data field, which holds the results of your query. If there are errors, an errors field will be present, detailing the issues.

{
  "data": {
    "posts": {
      "edges": [
        {
          "node": {
            "id": "123456",
            "name": "Example Product 1",
            "tagline": "A new way to do things.",
            "url": "https://www.producthunt.com/posts/example-product-1",
            "votesCount": 150
          }
        },
        // ... more posts
      ]
    }
  }
}

Common next steps

After successfully making your first API call, consider these next steps to further your integration:

  • Explore More Queries: Consult the Product Hunt GraphQL API documentation to discover other available queries and mutations. You can fetch user data, comments, topics, and more.
  • Implement Authentication Flow: If your application requires users to log in with their Product Hunt accounts, implement the full OAuth2 authorization code flow. This involves redirecting users to Product Hunt for authorization and exchanging the authorization code for an access token.
  • Utilize SDKs: For Ruby, Node.js, or Python projects, consider using the official Product Hunt SDKs. These libraries abstract away the HTTP request details and provide language-specific interfaces for interacting with the API, simplifying development.
  • Handle Pagination: GraphQL APIs often use cursor-based pagination. Learn how to use first, after, last, and before arguments in your queries to fetch large datasets efficiently GraphQL pagination concepts.
  • Error Handling: Implement robust error handling in your application to gracefully manage API errors, rate limits, and network issues.
  • Webhooks: Investigate Product Hunt's webhook capabilities if you need real-time notifications for events like new posts or comments.

Troubleshooting the first call

Encountering issues during the initial API call is common. Here are some troubleshooting tips:

  • Check Access Token: Ensure your Authorization: Bearer YOUR_ACCESS_TOKEN header is correctly formatted and that the token has not expired. OAuth2 tokens have a limited lifespan.
  • Verify Client ID and Secret: Double-check that the Client ID and Client Secret used to obtain your access token are accurate and match the credentials provided during application registration.
  • Correct Endpoint: Confirm you are sending requests to the correct GraphQL endpoint: https://api.producthunt.com/v2/api/graphql.
  • Content-Type Header: The Content-Type: application/json header is crucial for GraphQL POST requests. Ensure it is set correctly.
  • GraphQL Query Syntax: Verify the syntax of your GraphQL query. Even minor typos can lead to parsing errors. Tools like GraphQL Playground or GraphiQL can help validate queries against the schema.
  • Rate Limits: If you receive 429 Too Many Requests errors, you may have hit a rate limit. Product Hunt's API has rate limits to prevent abuse. Refer to the Product Hunt API documentation on rate limits for details.
  • Scope Issues: If you're using an OAuth2 flow that involves user authorization, ensure your application requested the necessary scopes during the authorization step. Insufficient scopes can lead to permission errors.
  • Network Issues: Check your network connectivity and any firewalls or proxies that might be blocking your requests.
  • Product Hunt Status Page: In rare cases, the Product Hunt API itself might be experiencing issues. Check their official status page for any outages.