Hashnode API Skill

Comprehensive assistance with the Hashnode GraphQL API for blog management, content creation, and user interaction on the Hashnode platform.

When to Use This Skill

This skill should be triggered when:

• Building integrations with Hashnode blogs or publications
• Querying Hashnode posts, users, or publication data
• Creating, publishing, or managing blog posts via API
• Implementing authentication with Hashnode Personal Access Tokens
• Working with GraphQL queries or mutations for Hashnode
• Debugging Hashnode API responses or error codes
• Setting up pagination (cursor-based or offset-based) for Hashnode data
• Implementing newsletter subscriptions, comments, or user interactions
• Migrating from the legacy Hashnode API to the new GQL endpoint

Key Concepts

API Endpoint

All Hashnode API requests go through a single GraphQL endpoint:

• Endpoint: https://gql.hashnode.com (POST only)
• Playground: Visit the same URL in a browser to explore the API
• Legacy API: https://api.hashnode.com is discontinued - migrate to new endpoint

Authentication

• Most queries work without authentication
• Sensitive fields (drafts, email, etc.) require authentication
• All mutations require authentication
• Authentication method: Add Authorization header with your Personal Access Token (PAT)
• Get your PAT: https://hashnode.com/settings/developer → "Generate New Token"

Rate Limits

• Queries: 20,000 requests per minute
• Mutations: 500 requests per minute

Caching

• Almost all query responses are cached on the Edge
• Cache is automatically purged when you mutate data
• Check cache status in playground (bottom right: HIT/MISS)
• Important: Always request the id field to avoid stale data

Error Codes

Common GraphQL error codes:

• GRAPHQL_VALIDATION_FAILED - Invalid query structure
• UNAUTHENTICATED - Missing or invalid auth token
• FORBIDDEN - Insufficient permissions
• BAD_USER_INPUT - Invalid input data
• NOT_FOUND - Resource doesn't exist

Quick Reference

1. Fetch Publication Details

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

Get basic information about a publication by its hostname.

2. Fetch Recent Blog Posts

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

Retrieve the latest 10 posts from a publication with cursor-based pagination support.

3. Fetch a Single Article by Slug

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

Get full content of a specific article using its slug and publication hostname.

4. Cursor-Based Pagination (Infinite Scroll)

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

Use endCursor from previous response as after parameter to fetch next page.

5. Offset-Based Pagination (Traditional Pages)

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

Navigate between pages using explicit page numbers.

6. Get Entity Count (Series Count Example)

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

Result:

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

Use totalDocuments field to get counts without fetching all data.

7. Fetch Posts from a Series

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

Get all posts belonging to a specific series.

8. Fetch Static Pages

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

Retrieve custom static pages like "About", "Contact", etc.

9. Fetch Single Static Page

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

Get content of a specific static page by slug.

10. Authentication Example - Get Drafts (Requires Auth)

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

Headers:

{
  "Authorization": "your-personal-access-token-here"
}

Variables:

{
  "first": 10,
  "host": "your-blog-host.hashnode.dev"
}

Drafts can only be queried by the publication owner with valid authentication.

Reference Files

This skill includes comprehensive documentation in references/:

• api.md - Complete Hashnode GraphQL API documentation including:
  • GQL Playground overview
  • Caching behavior and best practices
  • Rate limits and authentication
  • Status codes and error handling
  • Pagination methods (cursor-based and offset-based)
  • Migration guide from legacy API
  • Query and mutation examples
  • Full list of available queries and mutations

Use the reference files for detailed information about specific API features, error handling patterns, and advanced query techniques.

Working with This Skill

For Beginners

Start by understanding the core concepts above, then explore:

1. API Endpoint: Test queries in the playground at https://gql.hashnode.com
2. Authentication: Generate your PAT at https://hashnode.com/settings/developer
3. Basic Queries: Try fetching publication details and blog posts first
4. Pagination: Start with cursor-based pagination for simple infinite scroll

For Intermediate Users

Focus on:

1. Authentication flows: Implement PAT-based auth in your application
2. Error handling: Handle GraphQL error codes properly
3. Pagination strategies: Choose between cursor-based and offset-based based on your UI needs
4. Caching considerations: Always request id fields to avoid stale data
5. Content extraction: Work with both markdown and HTML content formats

For Advanced Users

Explore:

1. Mutations: Publishing posts, managing drafts, updating content
2. Complex queries: Nested queries with multiple levels (publication → series → posts)
3. Batch operations: Optimize API calls with GraphQL field selection
4. Webhook integration: Handle Hashnode webhook events
5. Rate limit optimization: Implement efficient request batching

Navigation Tips

• Start broad → go deep: Begin with publication queries, then drill into specific posts/series
• Check authentication: If you get UNAUTHENTICATED errors, verify your PAT is in the Authorization header
• Test in playground: Use https://gql.hashnode.com to test queries before implementing
• Monitor cache: Watch cache HIT/MISS status to optimize your queries
• Read error messages: GraphQL errors include helpful details in the extensions.code field

Common Use Cases

Building a Blog Frontend

1. Fetch publication metadata
2. Get post list with pagination
3. Display individual posts by slug
4. Implement series/category navigation
5. Show static pages (about, contact)

Content Management Dashboard

1. Authenticate with PAT
2. List and manage drafts
3. Publish/update posts
4. Schedule content
5. Monitor analytics

Newsletter Integration

1. Subscribe/unsubscribe users
2. Fetch subscriber counts
3. Manage email preferences
4. Track engagement metrics

Migration from Legacy API

1. Update endpoint from api.hashnode.com to gql.hashnode.com
2. Convert REST calls to GraphQL queries
3. Update authentication mechanism (check docs)
4. Adjust pagination from old format to cursor/offset-based
5. Update error handling for new error codes

Resources

Official Documentation

• API Docs: https://apidocs.hashnode.com
• Playground: https://gql.hashnode.com
• Discord: Join for updates and community support
• GraphQL Guide: freeCodeCamp's beginner-friendly GraphQL guide

references/

The api.md reference file contains:

• Complete API specification
• All available queries and mutations
• Detailed parameter descriptions
• Authentication requirements
• Code examples with proper syntax
• Links to original documentation
• Comprehensive error code reference

Important Notes

• Always request the id field on objects to avoid stale cached data
• Rate limits are generous but respect them for production apps
• Cache behavior: Most responses are cached; mutations automatically purge related cache
• Breaking changes are rare and announced well in advance on Discord
• Legacy API is shut down - use gql.hashnode.com only

Troubleshooting

Getting UNAUTHENTICATED errors?

• Verify your Personal Access Token is valid
• Check the Authorization header is set correctly
• Ensure you're requesting fields that require auth (drafts, email, etc.)

Not seeing latest data?

• Always request the id field to avoid stale cached data
• Check if response is HIT/MISS in playground

Query validation failed?

• Verify your GraphQL syntax in the playground first
• Check required parameters are provided
• Ensure field names match the schema

Rate limit reached?

• Queries: 20k/min is very generous - optimize your queries
• Mutations: 500/min limit - batch operations where possible
• Use caching on your end to reduce API calls

Updating

This skill was automatically generated from official Hashnode documentation. To refresh with updated documentation, regenerate the skill using the latest docs from https://apidocs.hashnode.com.