Hygraph Getting Started: Quickstart Guide & First API Call (2026)

Getting started overview

Hygraph, previously known as GraphCMS, offers a GraphQL-native headless content management system designed for delivering content across various digital platforms. This guide focuses on the initial steps required to begin development: setting up an account, configuring a project, and executing the first API request to retrieve content. Hygraph's architecture prioritizes GraphQL, which influences how content models are defined and queried. The platform supports a range of client-side technologies through its GraphQL API, enabling developers to integrate content into web, mobile, and other applications.

To follow this guide, you will need a web browser and a tool for making HTTP requests, such as curl or a GraphQL client like Insomnia or Postman. Understanding basic GraphQL syntax is beneficial but not strictly required for the initial steps, as examples will be provided. The process outlined here covers the fundamental actions necessary to retrieve data from a Hygraph project and serves as a foundation for further development, such as content creation, mutation, and advanced queries.

The following table provides a quick reference for the steps involved in getting started with Hygraph:

Create an account and get keys

To begin using Hygraph, you must first create an account and then set up a project. Hygraph offers a Developer Plan that includes a free tier, suitable for getting started and small projects. After signing up, you will be directed to your Hygraph dashboard.

1. Sign Up or Log In: Visit the Hygraph website and either sign up for a new account or log in if you already have one.
2. Create a New Project: Once logged in, you will be prompted to create a new project. Give your project a name and choose a region for content hosting. This action initializes a dedicated environment for your content models and data.
3. Schema Definition: Before retrieving content, you need to define a content schema. Navigate to the 'Schema' section in your project dashboard. Here, you can create content models (e.g., 'Page', 'Article', 'Product') and add fields to them (e.g., 'title' as a Single Line Text, 'content' as a Rich Text). For instance, create a simple model named Post with a title (String) and a slug (String) field. Make sure to mark the slug as unique.
4. Add Content: After defining your schema, go to the 'Content' section. Here, you can create new entries based on your defined models. For the Post model, create a new entry with a sample title like "My First Hygraph Post" and a slug like "my-first-hygraph-post". Publish this content to make it available via the API.
5. Retrieve API Endpoint and Permissions:
   • Navigate to 'Project Settings' in your dashboard.
   • Select 'API Access'.
   • Locate the 'Content API' section. You will see a 'Public Content API' endpoint URL. This is the GraphQL endpoint you will use to query your content. Copy this URL.
   • Under 'Permanent Auth Tokens', you'll find settings for API permissions. For your first public request, ensure that the 'Public API' is enabled and has read access to the content models you wish to query. By default, the Public Content API often has read access to published content, but it's good practice to verify this in the Hygraph API Access documentation.

Your first request

With your project set up, a content model defined, content added, and API endpoint identified, you can now make your first GraphQL request. This example uses curl for simplicity, but any GraphQL client or programming language SDK can be used. Hygraph's API is GraphQL-native, meaning all interactions are done through GraphQL queries and mutations.

First, identify your GraphQL API endpoint. It will look similar to https://api-us-west-2.hygraph.com/v2/YOUR_PROJECT_ID/master. Replace YOUR_PROJECT_ID with your actual project ID from the Hygraph dashboard's API Access section.

Let's assume you created a Post model with title and slug fields, and you've added at least one post. The following GraphQL query fetches all posts and their titles and slugs:

query MyPosts {
  posts {
    title
    slug
  }
}

To execute this query using curl, open your terminal and run the following command. Remember to replace YOUR_HYGRAPH_API_ENDPOINT with your actual endpoint URL:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "query": "query MyPosts { posts { title slug } }" }' \
  YOUR_HYGRAPH_API_ENDPOINT

A successful response will return a JSON object containing your published posts. For example:

{
  "data": {
    "posts": [
      {
        "title": "My First Hygraph Post",
        "slug": "my-first-hygraph-post"
      }
    ]
  }
}

If you prefer using an HTTP client like Postman's GraphQL client, set the request type to POST, enter your API endpoint URL, and paste the GraphQL query into the body of the request, typically under a "GraphQL" or "Body" tab. Ensure the Content-Type header is set to application/json.

Common next steps

After successfully retrieving content with your first API call, you can explore several common next steps to further develop with Hygraph:

• Add More Content Models and Fields: Expand your content schema by creating more complex models, adding different field types (e.g., Rich Text, Assets, References), and establishing relationships between models. This allows for structuring diverse content types within your project.
• Mutate Content: Learn how to create, update, and delete content using GraphQL mutations. This involves sending POST requests with GraphQL mutation syntax to your API endpoint. Hygraph provides detailed documentation on how to perform these operations securely.
• Integrate with a Frontend Framework: Connect your Hygraph project to a frontend framework like React, Vue, or Next.js. You can use GraphQL client libraries (e.g., Apollo Client, Relay) to simplify data fetching and state management in your application.
• Manage Assets: Upload and manage digital assets (images, videos, documents) directly within Hygraph. You can then reference these assets in your content models and retrieve their URLs via the API.
• Webhooks: Configure webhooks to trigger external processes whenever content is created, updated, or deleted. This is useful for cache invalidation, sending notifications, or integrating with other services.
• Localization: If your project requires multiple languages, explore Hygraph's localization features to manage content variants for different locales.
• Content Federation: Utilize Hygraph's content federation capabilities to pull content from external APIs or other Hygraph projects into a single unified GraphQL API. This can simplify data aggregation from disparate sources. The Hygraph documentation on content federation provides guides for setup.
• Explore SDKs: While this guide used curl, Hygraph supports various SDKs in languages like JavaScript, Python, and Ruby. Using an SDK can streamline API interactions within your chosen programming environment.

Troubleshooting the first call

If your first API call to Hygraph does not return the expected data, consider the following troubleshooting steps:

• Check API Endpoint URL: Ensure the GraphQL API endpoint URL is correct and includes your specific project ID. A common error is using a generic placeholder URL.
• Verify Content-Type Header: For POST requests, the Content-Type header must be set to application/json. Incorrect headers can lead to parsing errors on the server side.
• GraphQL Query Syntax: Double-check your GraphQL query for any syntax errors (e.g., misspelled field names, missing braces). Even small typos can cause the query to fail or return no data.
• Project Permissions: Go to 'Project Settings' > 'API Access' in your Hygraph dashboard. Verify that the 'Public API' has sufficient read permissions for the content models you are trying to query. If you're using a Permanent Auth Token, ensure its permissions are correctly configured.
• Content Status: Make sure the content you are trying to retrieve is actually published. Only published content is accessible via the Public Content API by default. Draft content will not appear in API responses unless specific preview API configurations are used.
• Network Issues: Check your internet connection. A stable connection is necessary for making successful API requests.
• Rate Limits: While unlikely for a first call, be aware that Hygraph, like many API providers, implements rate limits. If you are making numerous requests in quick succession, you might temporarily hit a limit, resulting in a 429 Too Many Requests error.
• Hygraph Status Page: In case of widespread issues, check the Hygraph status page (if available) for any reported service outages or degradation.
• Consult Documentation: Refer to the official Hygraph documentation for specific error codes or detailed explanations of API behavior.