Raw schema
{
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"enum": [
"works",
"authors",
"sources",
"institutions",
"topics",
"keywords",
"publishers",
"funders",
"awards"
],
"description": "Type of scholarly entity to search."
},
"id": {
"description": "Retrieve a single entity by ID. Supports: OpenAlex ID (\"W2741809807\", or its OpenAlex record-page or API URL such as \"https://openalex.org/works/W2741809807\" or \"https://api.openalex.org/works/W2741809807\"), whose letter must name `entity_type` — W works, A authors, S sources, I institutions, T topics, P publishers, F funders, G awards; DOI (\"10.1038/nature12373\"; under entity_type \"funders\", a funder's Crossref Funder Registry DOI such as \"10.13039/100000001\"), ORCID (\"0000-0002-1825-0097\"), ROR (\"https://ror.org/00hx57361\" — one ROR can name an institution, a funder, and a publisher, and `entity_type` picks which), PMID (\"12345678\" or \"https://pubmed.ncbi.nlm.nih.gov/12345678\"), PMCID (\"PMC1234567\" or a PubMed Central URL such as \"https://pmc.ncbi.nlm.nih.gov/articles/PMC1234567/\"), ISSN (\"1234-5678\"). Under entity_type \"works\" an arXiv ID is also accepted (\"1706.03762\", \"hep-th/9901001\", \"arXiv:1706.03762\", an arxiv.org /abs/ or /pdf/ URL, or its DOI \"10.48550/arXiv.1706.03762\"); a version suffix is dropped and named in `notice`. Under any other entity_type the `id` is sent as written. Keywords are identified by slug rather than a native ID — pass either the slug (\"groundwater\") or the URL a search returns (\"https://openalex.org/keywords/groundwater\"). When provided, `query`, `search_mode`, `filters`, `sort`, `sample`, and `seed` are not applied — the returned record is the entity at that ID regardless of them, and the response `notice` names any you passed. `select` still applies: the curated per-entity-type default is returned unless you pass `select` (use `[\"*\"]` for the complete record). Every selected array returns whole; `slice` pages a long one by count. To filter, drop `id` and search. Use openalex_resolve_name to find the ID if unknown.",
"type": "string",
"minLength": 1
},
"query": {
"description": "Text search query. Supports boolean operators (AND, OR, NOT), quoted phrases (\"exact match\"), wildcards (machin*), fuzzy matching (machin~1), and proximity (\"climate change\"~5). On works, wildcards need search_mode \"exact\" — the default stemmed keyword search refuses `*` and `?`. A `*` needs at least three characters before it (micro*, not A*) in every mode and on every entity type. Omit for filter-only queries — an empty string is rejected, since a blank search is a mistake rather than a request for the whole catalog.",
"type": "string",
"minLength": 1
},
"search_mode": {
"default": "keyword",
"description": "Search strategy. \"keyword\": stemmed full-text (default). \"exact\": no stemming, matches individual words (use quoted phrases for multi-word exact match), and the mode that takes wildcards on works; on every other entity type OpenAlex runs it as the keyword search. \"semantic\": AI embedding similarity over a query-dependent candidate set whose size `meta.count` reports, at ~1 req/sec, up to 50 per page, and paginated with `page` rather than `cursor`.",
"type": "string",
"enum": [
"keyword",
"exact",
"semantic"
]
},
"filters": {
"description": "Filter criteria as field:value pairs. AND across fields (multiple keys). OR within field: pipe-separate (\"us|gb\"). NOT: prefix \"!\" (\"!us\"). Range: \"2020-2024\". Comparison: \">100\", \"<50\". On numeric fields, `>=N`, `<=N`, `a..b`, `a..`, and `..b` are inclusive ranges, sent as OpenAlex's hyphen ranges (`N-`, `-N`, `a-b`); a negative bound, a reversed range, or a `!` before a comparison or an open range is rejected. AND within same field: \"+\"-separate (\"us+gb\"); inside a `.search` value, a DOI, a date (a timestamp's \"+00:00\" offset), a URL field such as landing_page_url, an exactly matched name (display_name, awards.funder_display_name — \"C++\", \"Erasmus+\"), a biblio field (issue \"1+2\"), or awards.funder_award_id, \"+\" is a literal character. A value cannot mix \"|\" with an AND operator — a \"+\", or a space between values on an ID, code, or `language` key (a space inside a language name is part of the name, and a country field never reads a space as AND) — OpenAlex splits it on \"|\" first and drops every alternative that ANDs more than one value, so such a value is rejected; put the AND in a second key instead (\"institutions.country_code\": \"US\" beside \"authorships.institutions.country_code\": \"DE|FR\" on works). On a field matched as whole text (display_name, awards.funder_display_name, awards.funder_award_id, geo.city, geo.region, raw_affiliation_strings, block_key, biblio fields), a space is part of the value: \"New York\", \"!New York\", and \"New York|Boston\" match as written, but quotes around one \"|\" alternative make that alternative match nothing. A comma is part of such a value too (\"University of California, Berkeley\" on raw_affiliation_strings): a value holding one is sent as one quoted phrase, its \"+\" a literal character. A value sent as a quoted phrase cannot contain a double quote of its own. A multi-word value there cannot be ANDed with another (\"New York+Boston\" matches nothing); to require two funders or institutions, AND their IDs (awards.funder_id, authorships.institutions.id). Country fields (keys ending in country_code, country_codes, or countries) take ISO 3166-1 alpha-2 codes (\"DE\"): an alpha-3 code (\"DEU\"), numeric code (\"276\"), or English name (\"Germany\", \"South Korea\") is converted, \"UK\" becomes \"GB\", and a value that cannot be a country code is rejected. A space there is part of a name, never a separator: \"South Korea|Japan\" ORs two countries, and \"DE US\" is rejected. `language` takes ISO 639-1 codes (\"en\"): an ISO 639-2 code (\"eng\") or English name (\"English\") is converted. Two keys that resolve to the same upstream field (an alias and its canonical name, e.g. `year` and `publication_year`) are both applied and AND'd, so they narrow rather than override each other. On works, a `.search` filter that has a `.search.exact` form (abstract, default, display_name, fulltext, title, title_abstract_keywords, title_and_abstract) refuses `*` and `?`: put the wildcard in the `.search.exact` key (title.search.exact). keyword.search, raw_affiliation_strings.search, and raw_author_name.search take wildcards as written. A `*` needs three characters before it in any `.search` value. Use OpenAlex IDs (not names) for entity filters — resolve names first. Common keys: `openalex` (filter by entity ID, e.g. {\"openalex\": \"W123|W456\"}), `cites` (works citing a given work), `publication_year` (range \"2020-2024\"), `authorships.author.id`, `type`, `is_oa`. Boolean values, non-negative numbers, nested objects (`{\"authorships\":{\"author\":{\"id\":\"A1\"}}}` reads as `authorships.author.id`), and a key wrapped in quotes are read as string values under dotted keys and disclosed in `notice`, except that a whole number at the top level is sent as its decimal text without a notice. null, arrays, empty objects, negative or exponent numbers, and two keys naming one field are rejected.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"sort": {
"description": "Sort field. Prefix with \"-\" for descending. Comma-separate for a multi-key sort, applied left to right, with the \"-\" prefix set per key (\"-publication_year,cited_by_count\" sorts by year descending, then citations ascending). Common: \"cited_by_count\", \"-publication_date\", \"-relevance_score\" (default when query present). Note: when combined with a keyword query, an explicit sort overrides relevance ranking entirely — top results may be highly cited but only tangentially on-topic. Use \"-relevance_score\" or omit sort to keep the most relevant results first. \"-relevance_score\" requires an active search via \"query\" or a \"filter:search\" filter — passing it without one will fail. Not combinable with `sample` — a search passing both is rejected.",
"type": "string"
},
"select": {
"description": "OpenAlex top-level field names to return. Always returned: `id`, `display_name` — additional fields you list are appended. A curated default per entity type applies to both searches and single-entity (`id`) lookups; pass field names to override it, or `[\"*\"]` to retrieve the complete record (every field). Only top-level fields project. A nested name returns the top-level object holding it, with a notice: `h_index`, `i10_index`, `2yr_mean_citedness` → `summary_stats` (authors, sources, institutions, publishers, funders); on works `is_oa`, `oa_status`, `oa_url`, `any_repository_has_fulltext` → `open_access`; and any dotted name whose first segment is a top-level field (`primary_location.source.display_name` → `primary_location`, `authorships.author` → `authorships` — `author_list` is the compact form). A name holding commas is split on them (`[\"doi,title\"]`), and a comma-separated string is accepted too (`\"doi,title\"`, when OPENALEX_SELECT_STRING_INPUT is on), both disclosed in `notice`. On sources, `publisher` returns `host_organization_name`: the publisher of a journal, the hosting institution of a repository, and null on most sources. On works, `author_list` returns each author in authorship order as `{id, display_name, orcid}` (`orcid` null when absent), a compact alternative to `authorships`, which also carries institutions and affiliations; neither the default nor `[\"*\"]` includes it. Invalid field names produce an error identifying the rejected field. A wide projection on a large page makes a large response, so name the fields you need. Not applied with `slice`. Example: [\"doi\", \"author_list\", \"primary_topic\"].",
"type": "array",
"items": {
"type": "string"
}
},
"per_page": {
"description": "Results per page. Default 25, or under `sample` the sample size up to 100, so a sample of 100 or fewer returns whole in one call. A larger value returns at most 100 and says so — at most 50 under search_mode \"semantic\", which OpenAlex also limits to about 1 request per second. A server set to OPENALEX_CLAMP_PER_PAGE=false rejects a value over either cap instead. An `id` lookup ignores page size.",
"type": "integer",
"minimum": 1
},
"cursor": {
"description": "Pagination cursor from a previous response. Pass to get the next page. Omit it on the first call — an empty string is rejected, since a supplied-but-blank cursor is a caller mistake rather than a request for page 1. Keyword and exact modes only — semantic search walks its candidates with `page`, and a `cursor` sent with it is rejected.",
"type": "string",
"minLength": 1
},
"page": {
"description": "Page number (1-based) for semantic search and for a seeded `sample`, the two searches that paginate with `page` instead of `cursor`. Semantic search ranks a query-dependent candidate set whose size `meta.count` reports, so the last reachable page is ceil(meta.count / per_page) — e.g. page 14 for a count of 70 with per_page=5. A sample draws min(sample, meta.count) records, so its last page is ceil(min(sample, meta.count) / per_page); paging a sample requires `seed`, and OpenAlex serves only its first 10,000 records, so a page × per_page above 10,000 is rejected. Passing it with any other search is rejected.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"sample": {
"description": "Return a random sample of this many entities matching the filters, up to 10,000; a larger value draws 10,000 and says so (rejected instead on a server set to OPENALEX_CLAMP_PER_PAGE=false). The sample comes back `per_page` records at a time — by default the whole sample up to 100 — and a larger one is walked with `page` and a `seed`, which fixes the draw; without `seed` only its first page is returned. `meta.count` stays the population matching the filters. Keyword and exact modes only: OpenAlex does not sample a semantic search, so `sample` with search_mode \"semantic\" is rejected. Cannot be combined with `cursor` or `sort` — a sample has no order, and a search passing either is rejected. Useful for unbiased exploration: spot-checking filter correctness, stratified review prompts, or generating exploration sets without bias toward most-cited.",
"type": "integer",
"minimum": 1
},
"seed": {
"description": "Deterministic seed for `sample`. Same seed + same filters = the same draw, page for page — required to walk a sample larger than one page with `page`, and worth passing whenever reproducibility matters. Has no effect without `sample`, and a search that passes it alone is rejected.",
"type": "string"
},
"slice": {
"description": "Page one array of the record at `id`: returns `id`, `display_name`, and `limit` elements of `field` from `offset` — fewer only at the array end — with the window in `windows`, whose `next` call repeats `limit` from the following offset. Requires `id`; replaces `select`. An offset at or past the end returns an empty window. A 100-author list cap can be continued on the singleton; at 5,000 stored authors the byline remains possibly capped, but `next` is null once stored entries are exhausted.",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "Top-level array field to page, such as \"authorships\", \"author_list\", or \"referenced_works\". Leave it empty to skip slicing."
},
"offset": {
"default": 0,
"description": "0-based index of the first element to return.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"limit": {
"default": 50,
"description": "Elements to return. Default 50; a larger value returns at most 5,000 and says so (rejected instead on a server set to OPENALEX_CLAMP_PER_PAGE=false).",
"type": "integer",
"minimum": 1
}
},
"required": [
"field"
]
}
},
"required": [
"entity_type"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}