Searches the Crossref works index (~188M records) by free text and/or structured filters. The generic query matches loosely across all fields; scope precisely with the field-specific parameters queryTitle, queryAuthor, and queryContainerTitle, or resolve a known citation to its DOI with queryBibliographic — all combine with each other and with query. Use the filter parameter for structured filtering (object with hyphen-separated Crossref keys). Sort options: relevance, score, is-referenced-by-count, published, deposited, indexed, created. Each work returns at most authorLimit authors (25 by default) with authorCount reporting the full deposited total, since a single page of large-collaboration papers can carry tens of thousands of author entries; crossref_get_work pages the whole author list for any DOI whose list was cut. Funding acknowledgements with their award numbers, license terms, and registered full-text links come back only when fields names funder, license, or link, in the entry shapes crossref_get_work uses; each work then carries at most 25 funders, with funderCount the full deposited total. Post-publication updates ride each work as Crossref records them: updatedBy names each correction, retraction, expression of concern, or new version issued against it, and updateTo the works it is itself a notice for — an absent updatedBy does not mean the work was never updated. Set facets to count the matching works per value of a field — per publication year, publisher, type, funder, affiliation, ORCID, and more — over the whole match set in the same call; rows: 0 returns the counts alone. Offset-based paging is capped at ~10K results; use cursor="*" to start cursor-based deep paging, then pass the nextCursor value from each response to continue. A walk with a query term and no sort runs by relevance, one with filters only in Crossref registration order. The walk ends on the page where nextCursor is absent — that page also carries a notice saying the list is exhausted. Cursor and offset cannot be combined.
View input schema
{
"type": "object",
"properties": {
"query": {
"description": "Free-text search query, e.g. \"CRISPR gene editing\" or \"climate change adaptation\"",
"type": "string"
},
"queryBibliographic": {
"description": "Whole-citation match to resolve a known reference to its DOI. Combine title, author, year, and container into one string, e.g. \"Watson Crick molecular structure of nucleic acids Nature 1953\".",
"type": "string"
},
"queryTitle": {
"description": "Match against work titles only, e.g. \"Array programming with NumPy\".",
"type": "string"
},
"queryAuthor": {
"description": "Match against author names only, e.g. \"Charles R. Harris\".",
"type": "string"
},
"queryContainerTitle": {
"description": "Match against the container title (journal or book name) only, e.g. \"Nature\".",
"type": "string"
},
"filter": {
"description": "Structured filter object using Crossref hyphen-separated keys. All values must be strings. Boolean flag keys (has-abstract, has-references, has-full-text) require string values \"true\" or \"false\". Dissertations, and most standards, deposit their date as an approval date rather than a publication date, which the pub-date filters (from-pub-date, until-pub-date) do not read — bound them by date with from-approved-date and until-approved-date. Example: {\"type\":\"journal-article\",\"has-abstract\":\"true\",\"from-pub-date\":\"2023-01-01\"}",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"fields": {
"description": "Fields to return (reduces payload). Names are case-sensitive, and each fills one output field: DOI → doi, title → title, type → type, author → authors and authorCount, published / published-print / published-online → published, approved → approved, container-title → containerTitle and containerTitles, event → event, publisher → publisher, member → memberId, is-referenced-by-count → isReferencedByCount, score → score, abstract → abstract, volume → volume, issue → issue, page → page, article-number → articleNumber, ISSN → issn, updated-by → updatedBy, update-to → updateTo, funder → funders and funderCount, license → licenses, link → links. Omitted or empty, every name but funder, license, and link is selected; those three are returned only when named here. A work's funders are capped at the first 25, with funderCount the deposited total. A grant record carries no funders: its funder sits under its project, a field a works list cannot select. A selected field absent from a work means the record does not deposit it. DOI is always returned whether or not it is listed here, so every result stays resolvable by crossref_get_work, which also returns a work's whole funder list and the fields this list does not cover (references, relations, and the rest of the record).",
"type": "array",
"items": {
"type": "string",
"enum": [
"DOI",
"title",
"type",
"author",
"published",
"published-print",
"published-online",
"approved",
"container-title",
"event",
"publisher",
"member",
"is-referenced-by-count",
"score",
"abstract",
"volume",
"issue",
"page",
"article-number",
"ISSN",
"updated-by",
"update-to",
"funder",
"license",
"link"
],
"description": "Crossref select name"
}
},
"rows": {
"default": 20,
"description": "Number of results to return per page (default 20): 0–500 per call when fields names abstract or author, or is omitted or empty, which selects every field but funder, license, and link; 0–200 when fields names funder, license, or link, whatever else it names; 0–1000 when fields names none of those five. A value above 500 under the first kind of selection returns 500 and says so in notice, and one above 200 under the second returns 200 the same way — on an offset page the notice also names the offset that continues after the records returned. 0 returns no works, only totalResults and any facets, and does not advance a cursor walk.",
"type": "integer",
"minimum": 0,
"maximum": 1000
},
"facets": {
"description": "Value counts over the whole match set — the records totalResults counts, not just this page — keyed by facet name, each set to \"*\" or a number of values. Crossref returns the values with the highest counts, at most 1000 per facet; a facet whose values reach its limit may have more, and notice names it. Example: {\"published\":\"*\",\"publisher-name\":10} counts works per publication year and for the 10 publishers with the most. Pair with rows: 0 for the counts alone.",
"type": "object",
"propertyNames": {
"type": "string",
"enum": [
"affiliation",
"license",
"container-title",
"publisher-name",
"link-application",
"orcid",
"update-type",
"published",
"funder-name",
"archive",
"type-name",
"relation-type",
"ror-id",
"issn",
"source",
"journal-issue",
"category-name",
"assertion",
"assertion-group",
"journal-volume",
"funder-doi"
],
"description": "Crossref facet name"
},
"additionalProperties": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"const": "*"
},
{
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
{
"type": "string",
"pattern": "^[1-9]\\d*$",
"description": "A number of values written as a decimal string, e.g. \"10\""
}
],
"description": "\"*\" for up to 1000 values, or a number of values; a number above 1000 is applied as 1000"
}
},
"authorLimit": {
"default": 25,
"description": "Maximum number of authors to return per work (1–500 per call, default 25; a larger value, up to 100000, applies 500 and says so in notice). Ordinary records fit under the default; large-collaboration papers deposit thousands, and a page of them is large enough to exhaust a client context. Each work reports its full deposited total as authorCount — call crossref_get_work with that work doi to page the authors this cap left out.",
"type": "integer",
"minimum": 1,
"maximum": 100000
},
"offset": {
"description": "Zero-based result offset for offset-based paging. Cannot be used with cursor. Capped at ~10K: offset + rows cannot pass it, so a page that would returns the rows that fit and says so in notice, and an offset at or past it is refused. Use cursor for deeper paging. A search with filters only and no sort has no fixed order: identical requests can order its records differently, so successive offsets can repeat or skip one — sort:\"created\" with order:\"asc\" holds the order.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"cursor": {
"description": "Cursor token for deep paging. Pass \"*\" to start cursor-based paging (required past ~10K results), then pass the nextCursor value from each response until a response omits it, which means the list is exhausted. A walk with a query term runs by relevance unless sort is set; a walk with filters only runs in Crossref registration order. Relevance scores shift slightly between identical requests, so a relevance walk can repeat or skip a record at a page boundary — sort:\"created\" walks every match without repeats. Cannot be combined with offset, or with a publication-date sort (published, published-print, published-online), which Crossref does not walk by cursor.",
"type": "string"
},
"sort": {
"description": "Sort field. Omitted, an offset page with a query term is ranked by relevance, and so is a cursor walk with one (sent as score). The publication-date sorts (published, published-print, published-online) work with offset paging only — Crossref refuses them alongside cursor; every other sort works with either.",
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"enum": [
"relevance",
"score",
"is-referenced-by-count",
"published",
"published-print",
"published-online",
"deposited",
"indexed",
"created",
"updated",
"references-count"
],
"description": "Crossref sort field"
}
]
},
"order": {
"description": "Sort direction (asc or desc). Applies only alongside sort; without one it has no effect.",
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort direction"
}
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}