> ## Documentation Index
> Fetch the complete documentation index at: https://hexagraph-docs.voyla.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Hexagraph REST API Reference: Endpoints and Params

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

The Hexagraph API provides RESTful endpoints for querying enriched scholarly metadata across all 10 core entities. All endpoints are available at the base URL `https://api.hexagraph.in` and return JSON. The API is designed for high-performance, unified access to academic data across outputs, authors, institutions, sources, publishers, funders, topics, domains, fields, and subfields.

## Base URL

```text theme={null}
https://api.hexagraph.in
```

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 & Rate Limits

**Open access — no API key required.** You can start making requests immediately without credentials or registration. Requests are rate limited per IP address to ensure fair usage across all clients. See [Rate Limits](/concepts/rate-limits) and [GET /rate-limit](/api-reference/rate-limit) for real-time monitoring.

| Limit Category               | Limit              |
| ---------------------------- | ------------------ |
| Short-Burst IP Limit         | 30 requests / min  |
| IP Daily Quota - List/Filter | 500 requests / day |
| IP Daily Quota - Search      | 50 requests / day  |

Every API response includes rate limit status headers (`X-RateLimit-IP-Limit`, `X-RateLimit-IP-Remaining`, `X-RateLimit-Daily-Remaining`).

## Content Type

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

For **GraphQL** queries, send a `POST` request to `/graphql` with the header:

```http theme={null}
Content-Type: application/json
```

```json theme={null}
{
  "query": "{ output(id: \"HX_W3038568908\") { id name year cited_by_count } }"
}
```

## Available Endpoints

| Endpoint                     | Description                                                   |
| ---------------------------- | ------------------------------------------------------------- |
| `GET /outputs`               | List/search scholarly works                                   |
| `GET /outputs/{id}`          | Fetch a specific output by HX\_W ID                           |
| `GET /authors`               | List/search authors                                           |
| `GET /authors/{id}`          | Fetch a specific author by HX\_A ID                           |
| `GET /sources`               | List/search sources (journals, repositories)                  |
| `GET /sources/{id}`          | Fetch a specific source by HX\_S ID                           |
| `GET /institutions`          | List/search institutions                                      |
| `GET /institutions/{id}`     | Fetch a specific institution by HX\_I ID                      |
| `GET /publishers`            | List/search publishers                                        |
| `GET /publishers/{id}`       | Fetch a specific publisher by HX\_P ID                        |
| `GET /funders`               | List/search funders                                           |
| `GET /funders/{id}`          | Fetch a specific funder by HX\_F ID                           |
| `GET /domains`               | List research domains                                         |
| `GET /domains/{id}`          | Fetch a specific domain by numeric ID                         |
| `GET /fields`                | List research fields                                          |
| `GET /fields/{id}`           | Fetch a specific field by numeric ID                          |
| `GET /subfields`             | List research subfields                                       |
| `GET /subfields/{id}`        | Fetch a specific subfield by numeric ID                       |
| `GET /topics`                | List research topic clusters                                  |
| `GET /topics/{id}`           | Fetch a specific topic by HX\_T ID                            |
| `GET /autocomplete`          | Cross-entity autocomplete search                              |
| `GET /autocomplete/{entity}` | Entity-specific autocomplete                                  |
| `GET /rate-limit`            | View current client IP rate limit usage and daily quotas      |
| `POST /graphql`              | Execute a GraphQL query (`output`, `author`, `outputs`, etc.) |

## Common Query Parameters

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

<ParamField query="filter" type="string">
  Filter expression to narrow results. Accepts key-value pairs such as `is_oa:true` or `year:2024`. Multiple filters can be combined with commas.
</ParamField>

<ParamField query="sort" type="string">
  Sorting parameter to order results (e.g. `cited_by_count:desc`, `outputs_count:desc`, `year:asc`).
</ParamField>

<ParamField query="page" type="integer">
  Page number for pagination. Defaults to `1`.
</ParamField>

<ParamField query="per_page" type="integer">
  Number of results returned per page. Allowed values: `10`, `25`, `50`, `100`. Defaults to `25`.
</ParamField>

## Response Format

### List Endpoints

List endpoints (e.g. `GET /outputs`, `GET /authors`) return a paginated envelope containing metadata and a results array:

```json theme={null}
{
  "meta": {
    "count": 1523,
    "db_response_time_ms": 12.4,
    "page": 1,
    "per_page": 25
  },
  "results": [
    {
      "id": "HX_W3038568908",
      "name": "Machine learning for molecular design and synthesis",
      "year": 2020,
      "cited_by_count": 1420
    }
  ]
}
```

### Single-Entity Endpoints

Single entity lookups (e.g. `GET /outputs/{id}`, `GET /authors/{id}`) return the transformed entity object directly:

```json theme={null}
{
  "id": "HX_W3038568908",
  "doi": "https://doi.org/10.1038/s41586-020-2649-2",
  "name": "Machine learning for molecular design and synthesis",
  "year": 2020,
  "cited_by_count": 1420
}
```

## ID System (`HX_`)

All entity identifiers use the `HX_` prefix format:

| Entity Type | Prefix / Format | Example ID       |
| ----------- | --------------- | ---------------- |
| Output      | `HX_W`          | `HX_W3038568908` |
| Author      | `HX_A`          | `HX_A5028125522` |
| Source      | `HX_S`          | `HX_S140251998`  |
| Institution | `HX_I`          | `HX_I109009565`  |
| Publisher   | `HX_P`          | `HX_P4310319965` |
| Funder      | `HX_F`          | `HX_F4320321001` |
| Topic       | `HX_T`          | `HX_T10346`      |
| Domain      | Numeric string  | `3`              |
| Field       | Numeric string  | `17`             |
| Subfield    | Numeric string  | `1702`           |