Hexagraph Quickstart: First REST and GraphQL Request

Learn how to make your first Hexagraph API call and run a GraphQL query to retrieve enriched scholarly metadata in under 5 minutes.

This guide walks you through your first REST and GraphQL requests against the Hexagraph API. No authentication is required — you can start querying live scholarly metadata immediately. By the end of this guide you’ll have fetched a scholarly output by ID, run a filtered search, and executed a GraphQL query from the playground.

1. Check the API

   Before making data requests, confirm the Hexagraph service is up and reachable by calling the health endpoint.

   curl https://hexagraph-core.onrender.com/health
   

   A healthy service returns:

   {
     "status": "ok"
   }
   

   If you receive a non-200 response or a network error, the service may be temporarily unavailable. Try again after a few moments.

2. Fetch a scholarly output

   Retrieve a single scholarly work by its OA:ID. Hexagraph uses the OA: prefix for all entity identifiers, derived from the underlying OpenAlex identifier.

   curl https://hexagraph-core.onrender.com/outputs/OA:W2107277218
   

   Example response (trimmed):

   {
     "id": "OA:W2107277218",
     "doi": "https://doi.org/10.1038/nature12373",
     "title": "Human-level control through deep reinforcement learning",
     "year": 2015,
     "citations": 18423,
     "authors": [
       { "id": "OA:A5086208034", "name": "Volodymyr Mnih" },
       { "id": "OA:A5010412141", "name": "Koray Kavukcuoglu" },
       { "id": "OA:A5025753558", "name": "David Silver" }
     ]
   }
   

   Use the id values returned in the authors array to resolve individual author records via the /authors/{id} endpoint.

3. Search publications

   Use the /outputs endpoint with query parameters to search across millions of scholarly works. Combine search with filter to narrow results, and use page and per_page for pagination.

   curl "https://hexagraph-core.onrender.com/outputs?search=artificial+intelligence&filter=has_doi:true&page=1&per_page=3"
   

   Key query parameters:

   Parameter	Type	Description
   search	string	Full-text search term across titles and abstracts
   filter	string	Comma-separated filter expressions (e.g. has_doi:true)
   page	integer	Page number for paginated results (default: 1)
   per_page	integer	Number of results per page (default: 10, max: 50)

   The response includes a meta object with total result counts and pagination details alongside the results array.

4. Try GraphQL

   Hexagraph exposes a full GraphQL API for flexible, nested queries. The interactive playground is available at:

   https://hexagraph-core.onrender.com/graphql

   Paste the following query into the playground to retrieve the same scholarly output you fetched in Step 2:

   query GetScholarlyOutput {
     output(id: "OA:W2107277218") {
       id
       doi
       title
       year
       date
       citations
       authors {
         name
       }
     }
   }
   

   GraphQL lets you request exactly the fields you need — no more, no less — and compose nested queries across related entities (e.g. fetching an author’s affiliated institutions in the same request). See the GraphQL Overview for the full schema reference.

Hexagraph enforces rate limits of 30 requests per minute and 1,000 requests per day per IP address. If you exceed these limits, you’ll receive an HTTP 429 Too Many Requests response. See Rate Limits & Authentication for guidance on handling limit errors gracefully.

API Reference

Explore the full REST endpoint catalog, parameters, and response schemas.

Rate Limits

Understand how rate limiting works and how to avoid hitting your quota.