> ## 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.

# Implement Type-Ahead Autocomplete Search with Hexagraph

> Power type-ahead search in your app using Hexagraph's autocomplete endpoint, which surfaces works, authors, sources, institutions, publishers, and funders.

The `/autocomplete` endpoint provides fast, type-ahead search suggestions across all Hexagraph entity types, making it ideal for building search interfaces in your application. As the user types, you can feed each keystroke to this endpoint and render a live dropdown of matching scholarly entities — works, researchers, journals, institutions, publishers, and funders — without running a full paginated search.

## General Autocomplete

`GET /autocomplete?q=<query>` returns suggestions across every entity type in a single call. Use this when you want a unified search box that surfaces any kind of scholarly entity.

```bash theme={null}
curl "https://api.hexagraph.in/autocomplete?q=machine+learning"
```

**Example response**

```json theme={null}
[
  {
    "id": "HX_W2107277218",
    "display_name": "Machine Learning for Natural Language Processing",
    "entity_type": "output",
    "hint": "2022 · Journal of Artificial Intelligence Research"
  },
  {
    "id": "HX_A3109847201",
    "display_name": "Yann LeCun",
    "entity_type": "author",
    "hint": "New York University · 142,893 citations"
  },
  {
    "id": "HX_S2041851",
    "display_name": "Machine Learning",
    "entity_type": "source",
    "hint": "Springer · ISSN 0885-6125"
  },
  {
    "id": "HX_I136199984",
    "display_name": "MIT Computer Science and Artificial Intelligence Laboratory",
    "entity_type": "institution",
    "hint": "Massachusetts Institute of Technology"
  }
]
```

Results are sorted by relevance across all entity types. The `entity_type` field tells your UI which icon or label to render alongside each suggestion.

## Entity-Specific Autocomplete

`GET /autocomplete/{entity}?q=<query>` restricts suggestions to a single entity type. Use this when your search context is already known — for example, an "Add Author" field in a paper submission form should only surface author suggestions.

**Supported entity values**

| Entity         | Description                                          |
| -------------- | ---------------------------------------------------- |
| `outputs`      | Scholarly works (journal articles, preprints, books) |
| `authors`      | Researcher profiles                                  |
| `sources`      | Journals, repositories, and other publication venues |
| `institutions` | Universities, research labs, and other organisations |
| `publishers`   | Publishing companies and organisations               |
| `funders`      | Grant-making bodies and funding agencies             |

```bash theme={null}
curl "https://api.hexagraph.in/autocomplete/authors?q=einstein"
```

**Example response**

```json theme={null}
[
  {
    "id": "HX_A2048391207",
    "display_name": "Albert Einstein",
    "entity_type": "author",
    "hint": "Institute for Advanced Study · 89,402 citations"
  },
  {
    "id": "HX_A3301847501",
    "display_name": "Albert Einstein College of Medicine Faculty",
    "entity_type": "author",
    "hint": "Albert Einstein College of Medicine · 1,204 citations"
  }
]
```

By scoping the request to `/autocomplete/authors`, only author records are returned — no outputs, sources, or institutions will appear in the list, keeping dropdown results clean and contextually appropriate.

## Integration Example

Below is a minimal JavaScript implementation of a debounced type-ahead search using the general autocomplete endpoint. The 300 ms debounce prevents excessive requests while the user is still typing.

```javascript theme={null}
let debounceTimer;

async function searchEntities(query) {
  const res = await fetch(
    `https://api.hexagraph.in/autocomplete?q=${encodeURIComponent(query)}`
  );
  return res.json();
}

function onSearchInput(event) {
  const query = event.target.value.trim();

  // Don't fire for very short inputs
  if (query.length < 2) return;

  // Debounce: wait 300ms after the user stops typing
  clearTimeout(debounceTimer);
  debounceTimer = setTimeout(async () => {
    const suggestions = await searchEntities(query);
    renderSuggestions(suggestions);
  }, 300);
}

function renderSuggestions(suggestions) {
  const list = document.getElementById("suggestions");
  list.innerHTML = suggestions
    .map(
      (s) => `<li data-id="${s.id}" data-type="${s.entity_type}">
                <strong>${s.display_name}</strong>
                <span class="hint">${s.hint}</span>
              </li>`
    )
    .join("");
}

document.getElementById("search-input").addEventListener("input", onSearchInput);
```

To scope the search to a specific entity type, replace the `autocomplete` path segment:

```javascript theme={null}
`https://api.hexagraph.in/autocomplete/authors?q=${encodeURIComponent(query)}`
```

## Response Fields

Each object in the suggestions array contains the following fields:

| Field          | Type   | Description                                                                                                                               |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | string | The entity's Hexagraph HX\_ID (e.g. `HX_W…`, `HX_A…`, `HX_S…`)                                                                            |
| `display_name` | string | Human-readable name suitable for rendering in a dropdown                                                                                  |
| `entity_type`  | string | One of `output`, `author`, `source`, `institution`, `publisher`, `funder`                                                                 |
| `hint`         | string | A short contextual string (e.g. year and venue for outputs, citation count for authors) to help users distinguish between similar results |

Use `id` to make a follow-up lookup to the appropriate detail endpoint (`/outputs/{id}`, `/authors/{id}`, etc.) once the user selects a suggestion.

<Note>
  Autocomplete queries count against your rate limit just like any other request (30 requests/min, 1,000/day). For type-ahead interfaces, debounce requests so you send at most one query per 300 ms — this keeps a fast typist from consuming dozens of quota slots per second and ensures a smoother user experience overall.
</Note>