{"openapi":"3.1.0","info":{"title":"Scholars Reading List search","description":"Search ~200 million scholarly papers by meaning or exact words. Guide for programs and agents: [llms.txt](llms.txt).","version":"0.3"},"paths":{"/search":{"get":{"summary":"Search","description":"Search papers by meaning or by exact words. Retracted papers are always left out. Answers: mode, results,\nfilters, timing; by meaning also ranking; by exact words also matches (exact count) and query (as understood).","operationId":"search_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":2000,"description":"A question, a description, keywords, or keyword syntax: \"phrase\", OR, NOT/-word, brackets, word*, \"a b\"~5, title:/abstract:/keywords:","title":"Q"},"description":"A question, a description, keywords, or keyword syntax: \"phrase\", OR, NOT/-word, brackets, word*, \"a b\"~5, title:/abstract:/keywords:"},{"name":"k","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of results, 1-100. No paging: ask for up to 100 at once.","default":10,"title":"K"},"description":"Number of results, 1-100. No paging: ask for up to 100 at once."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","pattern":"^(auto|semantic|keyword)$","description":"semantic = by meaning; keyword = exact words (English stemming); auto = keyword when q uses search syntax, else semantic","default":"auto","title":"Mode"},"description":"semantic = by meaning; keyword = exact words (English stemming); auto = keyword when q uses search syntax, else semantic"},{"name":"collection","in":"query","required":false,"schema":{"type":"string","description":"all (default) or smr: only papers ScienceMadeReadable can open (PubMed Central, CC BY, research articles).","default":"all","title":"Collection"},"description":"all (default) or smr: only papers ScienceMadeReadable can open (PubMed Central, CC BY, research articles)."},{"name":"year_from","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Earliest publication year.","title":"Year From"},"description":"Earliest publication year."},{"name":"year_to","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Latest publication year.","title":"Year To"},"description":"Latest publication year."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only this publication type (article, review, preprint, book, book-chapter, conference-paper, dissertation, report, letter, editorial, dataset, ...). Without it, non-publications (datasets, figures, covers) are left out.","title":"Type"},"description":"Only this publication type (article, review, preprint, book, book-chapter, conference-paper, dissertation, report, letter, editorial, dataset, ...). Without it, non-publications (datasets, figures, covers) are left out."},{"name":"open_access","in":"query","required":false,"schema":{"type":"boolean","description":"Only open-access papers.","default":false,"title":"Open Access"},"description":"Only open-access papers."},{"name":"license","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only this licence, e.g. cc-by.","title":"License"},"description":"Only this licence, e.g. cc-by."},{"name":"pmc_open_access","in":"query","required":false,"schema":{"type":"boolean","description":"Only papers whose full text is in PubMed Central's open-access set.","default":false,"title":"Pmc Open Access"},"description":"Only papers whose full text is in PubMed Central's open-access set."},{"name":"abstracts","in":"query","required":false,"schema":{"type":"boolean","description":"Include abstracts. false makes answers about 10x smaller.","default":true,"title":"Abstracts"},"description":"Include abstracts. false makes answers about 10x smaller."},{"name":"nprobe","in":"query","required":false,"schema":{"type":"integer","maximum":1024,"minimum":1,"description":"Index lists scanned (search by meaning): more = slower and slightly more complete. Rarely needed.","default":128,"title":"Nprobe"},"description":"Index lists scanned (search by meaning): more = slower and slightly more complete. Rarely needed."},{"name":"depth","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":10,"description":"Candidates re-scored exactly before filtering (search by meaning). Rarely needed.","default":300,"title":"Depth"},"description":"Candidates re-scored exactly before filtering (search by meaning). Rarely needed."},{"name":"map","in":"query","required":false,"schema":{"type":"boolean","description":"Add map-of-science positions (x, y in 0-1) to results and the question.","default":false,"title":"Map"},"description":"Add map-of-science positions (x, y in 0-1) to results and the question."},{"name":"junk_penalty","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":10,"minimum":0},{"type":"null"}],"description":"Search by meaning ranks by similarity - junk_penalty x junk (how likely a record is spam or not scholarship). Default 0.3 for all, 0 for smr; 0 = pure similarity.","title":"Junk Penalty"},"description":"Search by meaning ranks by similarity - junk_penalty x junk (how likely a record is spam or not scholarship). Default 0.3 for all, 0 for smr; 0 = pure similarity."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/search/{q}":{"get":{"summary":"Search Text","description":"The same search with the question in the address and the answer as plain text (Markdown), for AI tools\nthat can only open a web address: /search/why do cats purr. Spaces may be written %20 or +.","operationId":"search_text_search__q__get","parameters":[{"name":"q","in":"path","required":true,"schema":{"type":"string","title":"Q"}},{"name":"k","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of results, 1-100. No paging: ask for up to 100 at once.","default":10,"title":"K"},"description":"Number of results, 1-100. No paging: ask for up to 100 at once."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","pattern":"^(auto|semantic|keyword)$","description":"As in /search: auto, semantic or keyword.","default":"auto","title":"Mode"},"description":"As in /search: auto, semantic or keyword."},{"name":"collection","in":"query","required":false,"schema":{"type":"string","description":"all (default) or smr: only papers ScienceMadeReadable can open (PubMed Central, CC BY, research articles).","default":"all","title":"Collection"},"description":"all (default) or smr: only papers ScienceMadeReadable can open (PubMed Central, CC BY, research articles)."},{"name":"year_from","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Earliest publication year.","title":"Year From"},"description":"Earliest publication year."},{"name":"year_to","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Latest publication year.","title":"Year To"},"description":"Latest publication year."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only this publication type (article, review, preprint, book, book-chapter, conference-paper, dissertation, report, letter, editorial, dataset, ...). Without it, non-publications (datasets, figures, covers) are left out.","title":"Type"},"description":"Only this publication type (article, review, preprint, book, book-chapter, conference-paper, dissertation, report, letter, editorial, dataset, ...). Without it, non-publications (datasets, figures, covers) are left out."},{"name":"open_access","in":"query","required":false,"schema":{"type":"boolean","description":"Only open-access papers.","default":false,"title":"Open Access"},"description":"Only open-access papers."},{"name":"license","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only this licence, e.g. cc-by.","title":"License"},"description":"Only this licence, e.g. cc-by."},{"name":"pmc_open_access","in":"query","required":false,"schema":{"type":"boolean","description":"Only papers whose full text is in PubMed Central's open-access set.","default":false,"title":"Pmc Open Access"},"description":"Only papers whose full text is in PubMed Central's open-access set."},{"name":"abstracts","in":"query","required":false,"schema":{"type":"boolean","description":"Include abstracts. false makes answers about 10x smaller.","default":true,"title":"Abstracts"},"description":"Include abstracts. false makes answers about 10x smaller."}],"responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/similar/{ref}":{"get":{"summary":"Similar","description":"Papers closest in meaning to one paper. ref: W-number (W2782456798), DOI or PMCID. 404 when the paper is\nnot in the index searched by meaning (older years are still being added).","operationId":"similar_similar__ref__get","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","title":"Ref"}},{"name":"k","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of results, 1-100. No paging: ask for up to 100 at once.","default":10,"title":"K"},"description":"Number of results, 1-100. No paging: ask for up to 100 at once."},{"name":"year_from","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Earliest publication year.","title":"Year From"},"description":"Earliest publication year."},{"name":"year_to","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Latest publication year.","title":"Year To"},"description":"Latest publication year."},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only this publication type (article, review, preprint, book, book-chapter, conference-paper, dissertation, report, letter, editorial, dataset, ...). Without it, non-publications (datasets, figures, covers) are left out.","title":"Type"},"description":"Only this publication type (article, review, preprint, book, book-chapter, conference-paper, dissertation, report, letter, editorial, dataset, ...). Without it, non-publications (datasets, figures, covers) are left out."},{"name":"open_access","in":"query","required":false,"schema":{"type":"boolean","description":"Only open-access papers.","default":false,"title":"Open Access"},"description":"Only open-access papers."},{"name":"license","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only this licence, e.g. cc-by.","title":"License"},"description":"Only this licence, e.g. cc-by."},{"name":"pmc_open_access","in":"query","required":false,"schema":{"type":"boolean","description":"Only papers whose full text is in PubMed Central's open-access set.","default":false,"title":"Pmc Open Access"},"description":"Only papers whose full text is in PubMed Central's open-access set."},{"name":"abstracts","in":"query","required":false,"schema":{"type":"boolean","description":"Include abstracts. false makes answers about 10x smaller.","default":true,"title":"Abstracts"},"description":"Include abstracts. false makes answers about 10x smaller."},{"name":"nprobe","in":"query","required":false,"schema":{"type":"integer","maximum":1024,"minimum":1,"description":"Index lists scanned (search by meaning): more = slower and slightly more complete. Rarely needed.","default":128,"title":"Nprobe"},"description":"Index lists scanned (search by meaning): more = slower and slightly more complete. Rarely needed."},{"name":"depth","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":10,"description":"Candidates re-scored exactly before filtering (search by meaning). Rarely needed.","default":300,"title":"Depth"},"description":"Candidates re-scored exactly before filtering (search by meaning). Rarely needed."},{"name":"collection","in":"query","required":false,"schema":{"type":"string","description":"all (default) or smr: only papers ScienceMadeReadable can open (PubMed Central, CC BY, research articles).","default":"all","title":"Collection"},"description":"all (default) or smr: only papers ScienceMadeReadable can open (PubMed Central, CC BY, research articles)."},{"name":"junk_penalty","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":10,"minimum":0},{"type":"null"}],"description":"Search by meaning ranks by similarity - junk_penalty x junk (how likely a record is spam or not scholarship). Default 0.3 for all, 0 for smr; 0 = pure similarity.","title":"Junk Penalty"},"description":"Search by meaning ranks by similarity - junk_penalty x junk (how likely a record is spam or not scholarship). Default 0.3 for all, 0 for smr; 0 = pure similarity."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/map/place":{"get":{"summary":"Map Place","description":"Map-of-science positions (x, y in 0-1) of up to 200 papers (ids=W1,W2 or DOIs) and/or a question (q).","operationId":"map_place_map_place_get","parameters":[{"name":"ids","in":"query","required":false,"schema":{"type":"string","default":"","title":"Ids"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Q"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/map/regions":{"get":{"summary":"Map Regions","description":"Map-of-science field names, colours and label positions, and the release id used in tile URLs.","operationId":"map_regions_map_regions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/works/{ref}/authors":{"get":{"summary":"Work Authors","description":"Who wrote a paper, in order, with their author ids (A-numbers) for /authors/{id}. Positions OpenAlex could not\ntie to a person are left out.","operationId":"work_authors_works__ref__authors_get","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","title":"Ref"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/works/{ref}/context":{"get":{"summary":"Work Context","description":"Everything around one paper, for its page: its authors in order with ids, publication counts and h-index;\nits organisations, and which author signed from which (\"affiliations\": \"exact\", from OpenAlex's authorships;\n\"none\" while that index is missing: then the organisations are the paper's, not tied to authors); its references\nand the papers citing it (counts, counts per year, the most cited, the newest citing ones, and up to 400 of each as\n[year, citations, W-number, title] to draw a timeline); and the whole-field maps that hold it, with its group and\nsubgroup there (most specific map first). Links count only papers in the snapshot.","operationId":"work_context_works__ref__context_get","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","title":"Ref"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/works/{ref}/links":{"get":{"summary":"Work Links","description":"One paper's references or citing papers, a page at a time (title, year, citations, first author, map position,\nreadable on the site), with the list's total.","operationId":"work_links_works__ref__links_get","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","title":"Ref"}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","pattern":"^(references|cited_by)$","description":"references (what it cites) or cited_by (what cites it).","default":"cited_by","title":"Direction"},"description":"references (what it cites) or cited_by (what cites it)."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","pattern":"^(cited|newest|oldest)$","description":"Most cited first, newest or oldest.","default":"cited","title":"Sort"},"description":"Most cited first, newest or oldest."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/works/{ref}":{"get":{"summary":"Work","description":"One paper's full record. ref: W2782456798, https://openalex.org/W..., a DOI (10.1038/..., https://doi.org/...,\ndoi:...) or a PMCID (PMC1234567). Covers every paper in the corpus, all years.","operationId":"work_works__ref__get","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","title":"Ref"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/map/counts":{"get":{"summary":"Map Counts","description":"Exact publications per year and subfield over the whole corpus (for the map's charts).","operationId":"map_counts_map_counts_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/walk":{"get":{"summary":"Walk","description":"The citation walk from one paper: the k papers citing most of the same references, and what they cite that\nthe starting paper does not. answers = the strongest \"should also read / should have cited\" candidates\n(W-numbers); nodes = the papers (title, year, citations, topic, map position, readable on the site); links =\ncitation edges. 0.5-5 s. Returns an error when the paper has no references in the snapshot.","operationId":"walk_walk_get","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":300,"description":"W-number or DOI of the starting paper.","title":"Id"},"description":"W-number or DOI of the starting paper."},{"name":"k","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"How many papers sharing its references to walk through.","default":30,"title":"K"},"description":"How many papers sharing its references to walk through."},{"name":"max_refs","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Papers listing more references count as outliers (0 = no limit).","default":300,"title":"Max Refs"},"description":"Papers listing more references count as outliers (0 = no limit)."},{"name":"max_cites","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Papers cited more often count as outliers (0 = no limit).","default":500,"title":"Max Cites"},"description":"Papers cited more often count as outliers (0 = no limit)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/topics":{"get":{"summary":"Topics","description":"The research groups inside a topic, and what to read in each. The papers (closest in meaning, or exact-word\nmatches) are grouped by the works they cite and the words they use; each group gets a name (the phrases most\nover-represented in it) and reading lists computed from its own papers' citations: core (most cited by the\ngroup), distinctive (cited mostly by this group), rising (recent works gathering citations fast), start_here\n(recent papers citing most of the group's key works, often reviews), bridges (papers linking to another group),\nnewest, foundations (whole-field maps only: works cited most from outside the field; their other lists keep to\npapers of the field), and experts (authors with the highest position-weighted h-index inside the group); \"overall\" has the\nsame lists for the whole topic. Word clouds: each group's \"cloud\" holds the phrases it uses more than the other\ngroups, and overall's the phrases the topic uses more than the rest of science (share = of its papers, lift = how\nmany times more often, score = LDAvis relevance with lambda 0.6, what the order follows). Every paper comes\nwith its group and map position. 2-6 s the first time (up to ~30 s when the disk cache is cold), then instant\n(cached for the data release). Counts as 5 requests at the public door. With read=N: one group in depth, with\nabstracts (part=lists: its reading lists; part=papers&page=N: all of its papers, most central first).","operationId":"topics_topics_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":2000,"description":"A question or topic in plain words (by meaning), or exact-words syntax (quotes, AND/OR/NOT, word*), as in /search.","title":"Q"},"description":"A question or topic in plain words (by meaning), or exact-words syntax (quotes, AND/OR/NOT, word*), as in /search."},{"name":"papers","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":200,"description":"How many papers to map: the closest in meaning, or the best exact-word matches. More = broader, slower.","default":1000,"title":"Papers"},"description":"How many papers to map: the closest in meaning, or the best exact-word matches. More = broader, slower."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","pattern":"^(auto|semantic|keyword)$","description":"As in /search.","default":"auto","title":"Mode"},"description":"As in /search."},{"name":"year_from","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Earliest publication year.","title":"Year From"},"description":"Earliest publication year."},{"name":"year_to","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Latest publication year.","title":"Year To"},"description":"Latest publication year."},{"name":"group","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":50,"minimum":1},{"type":"null"}],"description":"Split this group of the map (its id, from a previous answer) into its own groups.","title":"Group"},"description":"Split this group of the map (its id, from a previous answer) into its own groups."},{"name":"read","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":50,"minimum":0},{"type":"null"}],"description":"Read this group of the map in depth, with abstracts: its reading lists (part=lists) or all of its papers, most central first (part=papers), in pages of ~64k characters (page=N). The map must exist (409 if not: call /topics first). read=0: the whole topic's reading lists (lists only). Counts as 1 request, not 5.","title":"Read"},"description":"Read this group of the map in depth, with abstracts: its reading lists (part=lists) or all of its papers, most central first (part=papers), in pages of ~64k characters (page=N). The map must exist (409 if not: call /topics first). read=0: the whole topic's reading lists (lists only). Counts as 1 request, not 5."},{"name":"part","in":"query","required":false,"schema":{"type":"string","pattern":"^(lists|papers|more|word)$","description":"With read: lists (its reading lists) or papers (all its papers, page by page); more: one reading list further than the map gives (list=, offset=, limit=), its items as in the map's lenses, with the list's total length; word: the group's papers that use one word of its cloud (word=, limit=), most central first, read among its 3,000 most central papers.","default":"lists","title":"Part"},"description":"With read: lists (its reading lists) or papers (all its papers, page by page); more: one reading list further than the map gives (list=, offset=, limit=), its items as in the map's lenses, with the list's total length; word: the group's papers that use one word of its cloud (word=, limit=), most central first, read among its 3,000 most central papers."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Which page: of the map itself (as text), or with read of the group's lists or papers. Each answer says how many pages there are and what to call next.","default":1,"title":"Page"},"description":"Which page: of the map itself (as text), or with read of the group's lists or papers. Each answer says how many pages there are and what to call next."},{"name":"abstracts","in":"query","required":false,"schema":{"type":"string","pattern":"^(full|short|none)$","description":"With read: full abstracts, their first sentences, or none.","default":"full","title":"Abstracts"},"description":"With read: full abstracts, their first sentences, or none."},{"name":"scope","in":"query","required":false,"schema":{"type":"string","pattern":"^(closest|field)$","description":"closest (default): the papers closest to the question, mapped in seconds. field: the whole research field (every paper on topic, up to a million: by meaning, an AI judge, the exact phrase and the studies the field cites), mapped by a background job the first time (15-30 minutes for most topics, up to ~2 hours for the biggest), then kept for everyone; while it is being made the answer is HTTP 202 with its progress; too broad: 422 (/fields/suggest?narrower=true gives parts of it). Groups of 300+ papers are split into subgroups (group=N), and their subgroups of 1,500+ papers once more.","default":"closest","title":"Scope"},"description":"closest (default): the papers closest to the question, mapped in seconds. field: the whole research field (every paper on topic, up to a million: by meaning, an AI judge, the exact phrase and the studies the field cites), mapped by a background job the first time (15-30 minutes for most topics, up to ~2 hours for the biggest), then kept for everyone; while it is being made the answer is HTTP 202 with its progress; too broad: 422 (/fields/suggest?narrower=true gives parts of it). Groups of 300+ papers are split into subgroups (group=N), and their subgroups of 1,500+ papers once more."},{"name":"definition","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"With scope=field: what the topic covers, in a sentence (optional; it settles ambiguous words). One map per topic: a topic already mapped or waiting under other words (a synonym, an abbreviation, no definition or one with the same scope) opens that map, and field.same_as (progress.same_as while it is made) names it; a narrower, broader or other topic gets its own.","title":"Definition"},"description":"With scope=field: what the topic covers, in a sentence (optional; it settles ambiguous words). One map per topic: a topic already mapped or waiting under other words (a synonym, an abbreviation, no definition or one with the same scope) opens that map, and field.same_as (progress.same_as while it is made) names it; a narrower, broader or other topic gets its own."},{"name":"list","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(core|start_here|rising|distinctive|foundations|bridges|newest|experts)$"},{"type":"null"}],"description":"With part=more: which reading list (core, start_here, rising, distinctive, foundations, bridges, newest, experts).","title":"List"},"description":"With part=more: which reading list (core, start_here, rising, distinctive, foundations, bridges, newest, experts)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":0,"description":"With part=more: the first item (0: the list's start).","default":8,"title":"Offset"},"description":"With part=more: the first item (0: the list's start)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"With part=more: how many items.","default":25,"title":"Limit"},"description":"With part=more: how many items."},{"name":"word","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}],"description":"With part=word: a word or phrase of the group's word cloud.","title":"Word"},"description":"With part=word: a word or phrase of the group's word cloud."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/fields/queue":{"get":{"summary":"Fields Queue","description":"Whole-field maps being made and waiting, in order, with when each should be ready. Two lines: maps paid for\non sciencemadereadable.com go first; the free line follows (about `free_per_day` maps a day). Topics in the\nline are public, as their maps will be.","operationId":"fields_queue_fields_queue_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/fields/suggest":{"get":{"summary":"Fields Suggest","description":"Five well-phrased versions of a topic before asking for its whole-field map, each with a one-sentence\ndefinition that sets its scope and settles ambiguous words (\"LLM\": large language models, or the law degree):\nthe closest to what was typed first, then narrower, broader or other readings (`note` says which). Written by\nan AI (Kimi K3), cached; a few seconds the first time. 503 when unavailable: the topic as typed still works.\nCounts as 5 requests at the public door.","operationId":"fields_suggest_fields_suggest_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":300,"description":"The topic as someone typed it.","title":"Q"},"description":"The topic as someone typed it."},{"name":"definition","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":600},{"type":"null"}],"description":"What they said it covers (optional).","title":"Definition"},"description":"What they said it covers (optional)."},{"name":"narrower","in":"query","required":false,"schema":{"type":"boolean","description":"Only narrower parts of the topic (it was refused as too broad for a whole-field map).","default":false,"title":"Narrower"},"description":"Only narrower parts of the topic (it was refused as too broad for a whole-field map)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/fields":{"get":{"summary":"Fields Made","description":"Every whole-field map made so far (public: anyone can open them with /topics?scope=field and the same topic\nand definition), newest first, or the maps that cover q: of the 50 studies closest in meaning to q, the share\neach map holds (`score`; \"direct preference optimization\" -> LLM post-training 0.6+, an unrelated subject 0).\n`checked`, when present: a larger model (Kimi K3) judged a random sample of the map's papers (`on_topic` of\n`judged`), and `found` estimates the share of the on-topic candidates the map kept.","operationId":"fields_made_fields_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Words or a question: the maps that hold most of the 50 studies closest to it first (score: that share, 0-1).","title":"Q"},"description":"Words or a question: the maps that hold most of the 50 studies closest to it first (score: that share, 0-1)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/topics/{q}":{"get":{"summary":"Topics Text","description":"The same topic map with the question in the address and the answer as plain text (Markdown): every group,\nevery reading list, every expert. /topics/intermittent fasting. With read=N: one group in depth, with abstracts\n(?read=2&part=lists, then ?read=2&part=papers&page=1, 2, ...).","operationId":"topics_text_topics__q__get","parameters":[{"name":"q","in":"path","required":true,"schema":{"type":"string","title":"Q"}},{"name":"papers","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":200,"description":"How many papers to map: the closest in meaning, or the best exact-word matches. More = broader, slower.","default":1000,"title":"Papers"},"description":"How many papers to map: the closest in meaning, or the best exact-word matches. More = broader, slower."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","pattern":"^(auto|semantic|keyword)$","description":"As in /search.","default":"auto","title":"Mode"},"description":"As in /search."},{"name":"year_from","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Earliest publication year.","title":"Year From"},"description":"Earliest publication year."},{"name":"year_to","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Latest publication year.","title":"Year To"},"description":"Latest publication year."},{"name":"group","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":50,"minimum":1},{"type":"null"}],"description":"Split this group of the map (its id, from a previous answer) into its own groups.","title":"Group"},"description":"Split this group of the map (its id, from a previous answer) into its own groups."},{"name":"read","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":50,"minimum":0},{"type":"null"}],"description":"Read this group of the map in depth, with abstracts: its reading lists (part=lists) or all of its papers, most central first (part=papers), in pages of ~64k characters (page=N). The map must exist (409 if not: call /topics first). read=0: the whole topic's reading lists (lists only). Counts as 1 request, not 5.","title":"Read"},"description":"Read this group of the map in depth, with abstracts: its reading lists (part=lists) or all of its papers, most central first (part=papers), in pages of ~64k characters (page=N). The map must exist (409 if not: call /topics first). read=0: the whole topic's reading lists (lists only). Counts as 1 request, not 5."},{"name":"part","in":"query","required":false,"schema":{"type":"string","pattern":"^(lists|papers)$","description":"With read: lists (its reading lists) or papers (all its papers, page by page); more: one reading list further than the map gives (list=, offset=, limit=), its items as in the map's lenses, with the list's total length; word: the group's papers that use one word of its cloud (word=, limit=), most central first, read among its 3,000 most central papers.","default":"lists","title":"Part"},"description":"With read: lists (its reading lists) or papers (all its papers, page by page); more: one reading list further than the map gives (list=, offset=, limit=), its items as in the map's lenses, with the list's total length; word: the group's papers that use one word of its cloud (word=, limit=), most central first, read among its 3,000 most central papers."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Which page: of the map itself (as text), or with read of the group's lists or papers. Each answer says how many pages there are and what to call next.","default":1,"title":"Page"},"description":"Which page: of the map itself (as text), or with read of the group's lists or papers. Each answer says how many pages there are and what to call next."},{"name":"abstracts","in":"query","required":false,"schema":{"type":"string","pattern":"^(full|short|none)$","description":"With read: full abstracts, their first sentences, or none.","default":"full","title":"Abstracts"},"description":"With read: full abstracts, their first sentences, or none."},{"name":"scope","in":"query","required":false,"schema":{"type":"string","pattern":"^(closest|field)$","description":"closest (default): the papers closest to the question, mapped in seconds. field: the whole research field (every paper on topic, up to a million: by meaning, an AI judge, the exact phrase and the studies the field cites), mapped by a background job the first time (15-30 minutes for most topics, up to ~2 hours for the biggest), then kept for everyone; while it is being made the answer is HTTP 202 with its progress; too broad: 422 (/fields/suggest?narrower=true gives parts of it). Groups of 300+ papers are split into subgroups (group=N), and their subgroups of 1,500+ papers once more.","default":"closest","title":"Scope"},"description":"closest (default): the papers closest to the question, mapped in seconds. field: the whole research field (every paper on topic, up to a million: by meaning, an AI judge, the exact phrase and the studies the field cites), mapped by a background job the first time (15-30 minutes for most topics, up to ~2 hours for the biggest), then kept for everyone; while it is being made the answer is HTTP 202 with its progress; too broad: 422 (/fields/suggest?narrower=true gives parts of it). Groups of 300+ papers are split into subgroups (group=N), and their subgroups of 1,500+ papers once more."},{"name":"definition","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"description":"With scope=field: what the topic covers, in a sentence (optional; it settles ambiguous words). One map per topic: a topic already mapped or waiting under other words (a synonym, an abbreviation, no definition or one with the same scope) opens that map, and field.same_as (progress.same_as while it is made) names it; a narrower, broader or other topic gets its own.","title":"Definition"},"description":"With scope=field: what the topic covers, in a sentence (optional; it settles ambiguous words). One map per topic: a topic already mapped or waiting under other words (a synonym, an abbreviation, no definition or one with the same scope) opens that map, and field.same_as (progress.same_as while it is made) names it; a narrower, broader or other topic gets its own."}],"responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/authors":{"get":{"summary":"Authors","description":"Authors by name: those whose display name holds every word of q (initials as prefixes), the most published\nfirst; if no name matches, each word is tried with one letter of difference (\"how\" says which). Each result\ncarries its publication count, citations, h-index, years, commonest topic and (when known) main institution,\nand \"match\": \"full\" when every word of q is in the name. Authors are OpenAlex's author records: a person\ncan have several, and about a quarter of recent author listings have none.","operationId":"authors_authors_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"A name, or part of one: 'Larivière', 'V Larivière', 'wang wei'. Accents and case do not matter; one-letter words are initials.","title":"Q"},"description":"A name, or part of one: 'Larivière', 'V Larivière', 'wang wei'. Accents and case do not matter; one-letter words are initials."},{"name":"k","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":10,"title":"K"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(json|text)$","description":"text: the answer as Markdown for a model to read (the same facts).","default":"json","title":"Format"},"description":"text: the answer as Markdown for a model to read (the same facts)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/authors/{ref}":{"get":{"summary":"Author","description":"One author's profile, shaped like a topic map (/topics): their publications in groups by field (OpenAlex's\nfield of each paper's primary topic; subfields inside; or subfields with topics inside when most of their work\nis in one field), each with reading lists (cited: most cited; newest; first: as first author) and map\npositions; \"overall\" has the same lists for all their work plus \"coauthors\" (people they publish with most,\nwith the most cited shared paper). \"person\" holds the figures: publications, citations, h-index, years, papers\na year, positions on papers, institutions. Lists hold their first 8 items; read=&list=&offset=&limit= gives the\nnext ones. Only OpenAlex's author records: a person split into several records has several pages.","operationId":"author_authors__ref__get","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","title":"Ref"}},{"name":"read","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(\\d{1,3}(\\.\\d{1,3})?)?$"},{"type":"null"}],"description":"With list=: which unit's list to read further: empty (all their work), a group (\"3\"), a subgroup (\"3.2\").","title":"Read"},"description":"With list=: which unit's list to read further: empty (all their work), a group (\"3\"), a subgroup (\"3.2\")."},{"name":"list","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(cited|newest|first|coauthors)$"},{"type":"null"}],"description":"With read: which list.","title":"List"},"description":"With read: which list."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":0,"default":8,"title":"Offset"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":25,"title":"Limit"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(json|text)$","description":"text: the answer as Markdown for a model to read (the same facts).","default":"json","title":"Format"},"description":"text: the answer as Markdown for a model to read (the same facts)."},{"name":"records","in":"query","required":false,"schema":{"type":"string","pattern":"^(person|one)$","description":"person (default): every OpenAlex record carrying this person's ORCID, as one page; one: this record only, as OpenAlex has it.","default":"person","title":"Records"},"description":"person (default): every OpenAlex record carrying this person's ORCID, as one page; one: this record only, as OpenAlex has it."},{"name":"with","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":400},{"type":"null"}],"description":"Other records of the same person, seen together on one page (comma-separated A-numbers, up to 19): OpenAlex often splits one person, historical figures most of all; /authors/{id}/namesakes lists the records with the same name.","title":"With"},"description":"Other records of the same person, seen together on one page (comma-separated A-numbers, up to 19): OpenAlex often splits one person, historical figures most of all; /authors/{id}/namesakes lists the records with the same name."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/institutions":{"get":{"summary":"Institutions","description":"Institutions (universities, hospitals, companies, agencies: OpenAlex's I-records) by name: those whose name\nholds every word of q, the most published first; \"works\" is their paper count. Only organisations OpenAlex\ncould match from affiliation strings: on recent papers that is 60-90 % of them.","operationId":"institutions_institutions_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200,"description":"An organisation's name, or part of it.","title":"Q"},"description":"An organisation's name, or part of it."},{"name":"k","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":10,"title":"K"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(json|text)$","description":"text: the answer as Markdown for a model to read (the same facts).","default":"json","title":"Format"},"description":"text: the answer as Markdown for a model to read (the same facts)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/institutions/{ref}":{"get":{"summary":"Institution","description":"One institution's profile, shaped like /authors/{ref}: its papers in groups by field, each with lists cited,\nnewest, people (its authors on the most of those papers, with the most cited one) and partners (the other\norganisations on its papers: who it works with); \"overall\" the same for all its work; \"person\" the figures\n(papers, citations, h-index, years, authors, country, kind, ROR). Large universities take a few seconds the\nfirst time.","operationId":"institution_institutions__ref__get","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","title":"Ref"}},{"name":"read","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(\\d{1,3}(\\.\\d{1,3})?)?$"},{"type":"null"}],"description":"As for /authors/{ref}.","title":"Read"},"description":"As for /authors/{ref}."},{"name":"list","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(cited|newest|people|partners)$"},{"type":"null"}],"title":"List"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":0,"default":8,"title":"Offset"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":25,"title":"Limit"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(json|text)$","description":"text: the answer as Markdown for a model to read (the same facts).","default":"json","title":"Format"},"description":"text: the answer as Markdown for a model to read (the same facts)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/sources":{"get":{"summary":"Sources","description":"Sources (journals, conferences, repositories, book series: OpenAlex's S-records) by name or ISSN: those whose\nname holds every word of q, the exact name first, then the most published. Each has its type, ISSN, publisher,\npublications, citations, h-index, years and share of open-access papers.","operationId":"sources_sources_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200,"description":"A journal's (conference's, repository's) name, or part of it ('nature', 'j ecol' does not work: whole words, the last may be a prefix), or an ISSN.","title":"Q"},"description":"A journal's (conference's, repository's) name, or part of it ('nature', 'j ecol' does not work: whole words, the last may be a prefix), or an ISSN."},{"name":"k","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":10,"title":"K"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(json|text)$","description":"text: the answer as Markdown for a model to read (the same facts).","default":"json","title":"Format"},"description":"text: the answer as Markdown for a model to read (the same facts)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/sources/{ref}":{"get":{"summary":"Source","description":"One source's profile (a journal, conference, repository or book series; S-number or ISSN), shaped like\n/authors/{ref}: its publications in groups by field, each with lists cited, newest, authors (who publishes most in\nit, with their most cited paper there) and institutions (where its authors are from), and a word cloud (what its\npapers say: the whole against all of science, each field against the rest of the source, from a sample of up to\n3,000 papers plus 400 of each field); \"person\" the figures (type, ISSN, publisher, publications, citations,\nh-index, years, open-access share, authors, and \"recent\": the mean and median citations of its papers of three\ncomplete years 2-4 years back; OpenAlex's counts, not an impact factor). A paper counts for the source of its\nprimary location. Large journals take a few seconds the first time, then are kept.","operationId":"source_sources__ref__get","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","title":"Ref"}},{"name":"read","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(\\d{1,3}(\\.\\d{1,3})?)?$"},{"type":"null"}],"description":"As for /authors/{ref}.","title":"Read"},"description":"As for /authors/{ref}."},{"name":"list","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(cited|newest|authors|institutions)$"},{"type":"null"}],"title":"List"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":0,"default":8,"title":"Offset"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":25,"title":"Limit"}},{"name":"word","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}],"description":"A word of the source's (or, with read=, one field's) word cloud: its papers that use it, among the sample the clouds are counted on, the most cited first.","title":"Word"},"description":"A word of the source's (or, with read=, one field's) word cloud: its papers that use it, among the sample the clouds are counted on, the most cited first."},{"name":"format","in":"query","required":false,"schema":{"type":"string","pattern":"^(json|text)$","description":"text: the answer as Markdown for a model to read (the same facts).","default":"json","title":"Format"},"description":"text: the answer as Markdown for a model to read (the same facts)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"servers":[{"url":".","description":"where this spec was loaded from"},{"url":"https://api.sciencemadereadable.com/api/data","description":"public (30 requests/minute per address)"}]}