This document describes the Hashnode Public API. The Hashnode Public API is a GraphQL API that allows you to interact with Hashnode.

Make sure to join our Discord server to be in the loop about any updates.

If you're seeing Errors with a 502 status code, it's highly likely that you are using api.hashnode.com. This was our legacy API and is now officially discontinued. Please use these docs and the migration guide to transition to our new GQL API.

All Hashnode Public API queries are made through a single GraphQL endpoint, which only accepts POST requests.

https://gql.hashnode.com

You can visit the same URL to check out Hashnode API Playground.

You can query user details, publication information, posts within publications, drafts, and more. Please explore the playground to view all available fields.

Additionally, mutations are at your disposal for actions such as publishing posts, subscribing to newsletters, and following users. The complete list of these available mutations can be found within the playground.

If you're not familiar with GraphQL, be sure to check out this beginner-friendly guide on freeCodeCamp

Almost all responses of queries are cached on the Edge. Cached data will automatically be purged if you mutate the data. For example, if you request a post of your blog:

The playground shows you if a response is cached or not. You can see it in the bottom right corner (MISS or HIT).

🚧 Important: You need to request the field id of each field. It is best practice to always request the id. If you don't do that it is possible that you get stale data.

We have a very generous rate limit in place which are as follows:

• Query users are allowed to send up to 20k requests per minute.
• Mutations users can send up to 500 requests per per minute.

Almost all queries can be accessed without any authentication mechanism. Some sensitive fields need authentication. All mutations need an authentication header.

You can include an Authorization header in your request to access restricted fields. The value of the Authorization header needs to be your Personal Access Token (PAT).

You can test it in the GQL playground and click on the Headers tab to add the header.

To generate the token, go to https://hashnode.com/settings/developer and click on "Generate New Token".

Once the token is generated, simply pass it as Authorization header.

An example of a restricted query could be getting drafts inside any blog, it can only be queried by their respective owners.

query Publication($first: Int!, $host: String) { publication(host: $host) { drafts(first: $first) { edges { node { title } } } } } 

Similarly, anyone can request user details but certain fields like unsubscribeCode and email require an authorization header to be present.

Please ensure that you pass the token when requesting restricted fields; otherwise, the API will throw an error.

GraphQL APIs use HTTP status codes to indicate the success or failure of a request. A 200 OK status code means the request was successful. In addition to HTTP status codes, GraphQL APIs also return error objects in response to specific errors.

These error objects have a code and message property. The code is a string that identifies the type of error. For example, you'll receive something like this if you try to request restricted fields without passing the authorization header.

{ "errors": [ { "message": "You must be authenticated.", "locations": [ { "line": 2, "column": 3 } ], "path": ["me"], "extensions": { "code": "UNAUTHENTICATED" } } ], "data": null } 

Some of the error codes are:

1. GRAPHQL_VALIDATION_FAILED
2. UNAUTHENTICATED
3. FORBIDDEN
4. BAD_USER_INPUT
5. NOT_FOUND

You can check out this article to understand error codes in detail.

You must check for the presence of error objects along with error codes and messages to handle GraphQL errors in a structured way.

When handling extensive lists of items in an API, such as many blog posts, it's practical to fetch them in smaller sets rather than all at once. This process is known as pagination. For instance, if your blog has 500 posts, retrieving them all simultaneously can be inefficient. A better approach is to initially fetch a subset, like 10 posts, and then continue loading more in small groups.

Hashnode offers two distinct pagination methods, each suited for different scenarios:

1. Cursor-Based Pagination
2. Offset-Based Pagination

Only one type of pagination is available for a query. You can distinguish the types of the type of response connection that is available. For cursor-based pagination the type PageInfo is available. For offset-based pagination the type OffsetPageInfo is available.

1. Cursor-Based Pagination

Cursor-based pagination is ideal for an infinite scrolling mechanism, where there is no fixed concept of pages. It uses a field named endCursor to keep track of the last item fetched. This cursor is then used to request subsequent items.

In this approach, the first API request does not include a cursor, and the API responds with the first set of results along with a new cursor. This new cursor is then utilized to fetch the next set of results.

Example Query in GraphQL

query Publication { publication(host: "blog.developerdao.com") { isTeam title posts( first: 10 after: "NjQxZTc4NGY0M2NiMzc2YjAyNzNkMzU4XzIwMjMtMDMtMjVUMDQ6Mjc6NTkuNjQxWg==" ) { edges { node { title brief url } } pageInfo { endCursor hasNextPage } } } } 

In this example, edges contains a list of nodes (the data), and the pageInfo object provides pagination details. Use pageInfo.hasNextPage to check for more data and pageInfo.endCursor for subsequent requests.

For more information, visit Relay Pagination Specification.

2. Offset-Based Pagination

Offset-based pagination is more traditional, involving distinct pages. It is suitable when you want to display data on specific pages or embed page information in URLs.

Example Query in GraphQL

query Followers { user(username: "SandroVolpicella") { id followers(pageSize: 10, page: 1) { pageInfo { hasNextPage hasPreviousPage previousPage nextPage } } } } 

In this method, pageInfo includes information about the availability of next and previous pages, allowing for easy navigation between different sets of data.

Breaking changes, while rare, can occur. Our aim is to minimize them. Stay updated by joining our Discord server.

When a breaking change is imminent, rest assured, we'll notify you beforehand. Affected fields, queries, or mutations will be deprecated in advance, ensuring you're well-prepared for the upcoming change.

Thank you for your understanding and collaboration.

Overview

After the deprecation phase, our old legacy GraphQL API is now shutdown. To ensure that your apps are still working, follow this migration guide from the old API to the new API (gql.hashnode.com).

Migration Steps

Update API Endpoint

Replace the old API endpoint https://api.hashnode.com with the new GraphQL endpoint https://gql.hashnode.com.

Authentication Changes

If you were using authentication for the old API, ensure that your authentication mechanism remains valid for the new API. Check the documentation for how Authentication works in our GraphQL API.

Adjust Queries

Review your existing GraphQL queries and mutations. Some types and fields may have changed. Refer to the documentation for Examples and below to review the latest schema, query and mutation definitions.

Check Pagination

If your application relies on pagination, ensure that you are using the updated pagination methods provided by the new API. We offer two kinds of pagination: Cursor-Based Pagination and Offset-Based Pagination. Review the pagination guide in the docs on how these two are working.

Update Error Handling

The new API might have different error responses or codes. Update your error handling mechanisms to accommodate any changes in error formats. You can check out this article to understand error codes in detail.

If you want to access a count of some entity we provide them via the field totalDocuments on the connection of the attribute.

Let's see an example:

query SeriesCount { publication(host: "engineering.hashnode.com") { seriesList(first: 0) { totalDocuments } } } 

The result looks like that:

{ "data": { "publication": { "seriesList": { "totalDocuments": 3 } } } } 

The field totalDocuments shows you how many series are in the publication with the host engineering.hashnode.com. The totalDocuments field doesn't refer to how many items you request with first. This is independent of each other.

We don't expose this field for all connections, but for most of them.

Let’s look at some examples which might help you get started:

Fetch details about your publication

query Publication { publication(host: "blog.developerdao.com") { isTeam title about { markdown } } } 

Fetch posts from your blog

query Publication { publication(host: "blog.developerdao.com") { isTeam title posts(first: 10) { edges { node { title brief url } } } } } 

The queries support pagination, and let you fetch a full list of the posts to recreate your blog home page.

Fetch a single article (blog post)

query Publication { publication(host: "blog.developerdao.com") { isTeam title post(slug: "the-developers-guide-to-chainlink-vrf-foundry-edition") { title content { markdown html } } } } 

As long as you have your publication hostname and article slug, you can fetch it like the above.

Fetch posts from a series

query Publication { publication(host: "lo-victoria.com") { isTeam title series(slug: "graphql") { posts(first: 10) { edges { node { title } } } } } } 

Fetch static pages

query Publication { publication(host: "lo-victoria.com") { isTeam title staticPages(first: 10) { edges { node { title slug } } } } } 

Fetch a single page

query Publication { publication(host: "lo-victoria.com") { isTeam title staticPage(slug: "about") { title content { markdown } } } }