Hexagraph REST API Reference: Endpoints and Params

Complete reference for the Hexagraph REST API. Base URL, request format, response structure, pagination, filtering, and query parameters for all endpoints.

The Hexagraph API provides RESTful endpoints for querying enriched scholarly metadata. All endpoints are available at the base URL https://hexagraph-core.onrender.com and return JSON. The API follows OAS 3.0 conventions and is designed for high-performance, unified access to academic data across works, authors, institutions, publishers, funders, and more.

Base URL

https://hexagraph-core.onrender.com

All requests should be made over HTTPS. The API is versioned at 1.0 and the base URL already reflects the current stable version.

Authentication

Open access — no API key required. You can start making requests immediately without any credentials or registration. Requests are rate limited per IP address to ensure fair usage across all clients. See the rate limits section for details.

Limit	Value
Per minute	30 requests
Per day	1,000 requests

Content Type

All responses are returned as application/json. You do not need to set a request Content-Type for standard REST GET requests.

For GraphQL queries, send a POST request with the following header and body format:

Content-Type: application/json

{
  "query": "{ outputs(search: \"transformer\") { id title year } }"
}

Available Endpoints

Endpoint	Description
GET /outputs	List/search scholarly works
GET /outputs/{id}	Fetch a specific work by OA:ID
GET /authors	List/search authors
GET /authors/{id}	Fetch a specific author
GET /sources	List/search sources (journals, repositories)
GET /sources/{id}	Fetch a specific source
GET /institutions	List/search institutions
GET /institutions/{id}	Fetch a specific institution
GET /publishers	List/search publishers
GET /publishers/{id}	Fetch a specific publisher
GET /funders	List/search funders
GET /funders/{id}	Fetch a specific funder
GET /autocomplete	Cross-entity autocomplete search
GET /autocomplete/{entity}	Entity-specific autocomplete
GET /{id}	Resolve any entity by OA:ID
GET /rate-limit	View current rate limit usage
GET /health	Service health check
POST /graphql	Execute a GraphQL query (output(id), outputs(query), author(id))

Common Query Parameters

The following parameters are available across all list endpoints (e.g. /outputs, /authors, /institutions).

search · string

Full-text search query string. Searches across relevant text fields for the entity type (e.g. title and abstract for outputs, display name for authors).

filter · string

Filter expression to narrow results. Accepts key-value pairs such as has_doi:true, is_oa:true, or year:2023. Multiple filters can be combined with commas.

page · integer

Page number for pagination. Defaults to 1. Use in combination with per_page to walk through result sets.

per_page · integer

Number of results to return per page. Defaults to 25. Maximum allowed value is 200.

Response Format

List Endpoints

List endpoints (e.g. GET /outputs, GET /authors) return a paginated response envelope containing metadata about the result set alongside an array of entity objects:

{
  "meta": {
    "count": 1523,
    "page": 1,
    "per_page": 25
  },
  "results": [
    {
      "id": "OA:W2741809807",
      "title": "Attention Is All You Need",
      "year": 2017,
      ...
    },
    ...
  ]
}

Field	Type	Description
meta.count	integer	Total number of matching records
meta.page	integer	Current page number
meta.per_page	integer	Number of results on this page
results	array	Array of entity objects matching the query

Single-Entity Endpoints

Endpoints that fetch a specific entity by ID (e.g. GET /outputs/{id}, GET /authors/{id}) return the entity object directly — no envelope wrapper:

{
  "id": "OA:W2741809807",
  "title": "Attention Is All You Need",
  "year": 2017,
  "doi": "https://doi.org/10.48550/arxiv.1706.03762",
  "is_oa": true,
  ...
}

ID Handling

All entity identifiers in Hexagraph use the OA:ID format — a namespaced string prefixed with OA: followed by a letter and numeric identifier. Examples:

Entity Type	Example ID
Output (Work)	OA:W2741809807
Author	OA:A5023888391
Institution	OA:I136199984
Source	OA:S1983995261
Publisher	OA:P4310319965
Funder	OA:F4320332161

When passing an OA:ID as a path parameter, URL-encode the colon character (:). For example:

GET /outputs/OA%3AW2741809807

The GET /{id} endpoint resolves any OA:ID to its entity type and data automatically — useful when you have an ID but don’t know the entity type in advance.