Search and Filter Scholarly Outputs via the REST API

Query Hexagraph’s outputs endpoint to search scholarly works by keyword, filter by attributes like DOI presence, and paginate through large result sets.

The /outputs endpoint is the primary entry point for searching and retrieving scholarly works indexed by Hexagraph. It surfaces journal articles, preprints, books, and other academic outputs drawn from OpenAlex’s enriched metadata corpus. Whether you need a broad keyword search, a narrowly filtered dataset, or a precise single-record lookup, this endpoint covers all three patterns.

Basic Search

Append a search query parameter to run a full-text search across titles, abstracts, and other indexed fields.

curl "https://hexagraph-core.onrender.com/outputs?search=artificial+intelligence"

Example response

{
  "results": [
    {
      "id": "OA:W2107277218",
      "doi": "https://doi.org/10.1016/j.artint.2022.103751",
      "title": "Artificial Intelligence in Clinical Decision Support",
      "year": 2022,
      "citations": 148
    },
    {
      "id": "OA:W3149812045",
      "doi": "https://doi.org/10.1038/s41586-022-04386-4",
      "title": "Ethical Frameworks for Artificial Intelligence Systems",
      "year": 2022,
      "citations": 94
    },
    {
      "id": "OA:W2983671120",
      "doi": null,
      "title": "Survey of Artificial Intelligence Applications in Healthcare",
      "year": 2021,
      "citations": 310
    }
  ],
  "meta": {
    "total": 18743,
    "page": 1,
    "per_page": 25
  }
}

Each result in the results array includes the work’s id (using the OA:W prefix), doi, title, publication year, and citations count. The meta object reports the total number of matching records and the current pagination position.

Filtering Results

The filter parameter accepts colon-separated key-value pairs to narrow results by specific attributes. Multiple filters can be combined in a comma-separated list.

Filter	Description
has_doi:true	Only return works that have an assigned DOI
is_oa:true	Only return open access works
year:2023	Restrict results to a specific publication year

curl "https://hexagraph-core.onrender.com/outputs?search=machine+learning&filter=has_doi:true"

This returns only machine learning works that carry a DOI — useful when you need stable identifiers for every record in your dataset.

To stack filters, separate them with commas:

curl "https://hexagraph-core.onrender.com/outputs?search=machine+learning&filter=has_doi:true,is_oa:true"

Pagination

For large result sets, use page and per_page to step through records in manageable chunks. The default per_page value is 25; you can set it up to 200.

curl "https://hexagraph-core.onrender.com/outputs?search=climate&page=2&per_page=10"

Use the meta.total field in each response to calculate the total number of pages:

total_pages = ceil(meta.total / per_page)

Fetch a Specific Output

When you already know an output’s OA:ID, retrieve its full record directly with GET /outputs/{id}.

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

Example response

{
  "id": "OA:W2107277218",
  "doi": "https://doi.org/10.1016/j.artint.2022.103751",
  "title": "Artificial Intelligence in Clinical Decision Support",
  "year": 2022,
  "date": "2022-04-15",
  "citations": 148,
  "source": {
    "id": "OA:S1983651",
    "name": "Artificial Intelligence"
  },
  "authors": [
    { "id": "OA:A5086208034", "name": "Jordan Rivera" },
    { "id": "OA:A2048391207", "name": "Priya Nambiar" }
  ]
}

The single-record response includes the full source object (the journal or venue), an authors array with each contributor’s ID and name, and the precise publication date in addition to the year.

Combining Parameters

You can freely combine search, filter, page, and per_page in a single request. The example below retrieves the second page of open-access climate papers from 2023, ten records at a time:

curl "https://hexagraph-core.onrender.com/outputs?search=climate+change&filter=is_oa:true,year:2023&page=2&per_page=10"

Example response

{
  "results": [
    {
      "id": "OA:W3301847562",
      "doi": "https://doi.org/10.1038/s41558-023-01701-x",
      "title": "Accelerating Climate Adaptation Through Open Science",
      "year": 2023,
      "citations": 27
    }
  ],
  "meta": {
    "total": 4821,
    "page": 2,
    "per_page": 10
  }
}

For complex filtered queries that span multiple entity types — for example, fetching an output alongside its authors’ full profiles in one round trip — consider using the GraphQL endpoint. GraphQL lets you request exactly the fields you need and combine multiple entity lookups into a single request, which is especially useful for staying within rate limits.