RESTful API providing access to 214M+ academic papers, 79M authors, 2.49B citations, venues, and SPECTER2 vector embeddings. Supports single-item lookups, keyword search, bulk retrieval, and citation/reference traversal.
openapi: 3.0.0
info:
title: Academic Graph API
version: '1.0'
description: "Fetch paper and author data from the Semantic Scholar Academic Graph\
\ (S2AG).\n <br><br>\n Some things to note:\n <ul>\n \
\ <li>If you are using an API key, it must be set in the header <code>x-api-key</code>\
\ (case-sensitive).</li>\n <li>We have two different IDs for a single paper:\n\
\ <ul>\n <li><code>paperId</code> - string - The primary way\
\ to identify papers when using our website or this API</li>\n <li><code>corpusId</code>\
\ - int64 - A second way to identify papers. Our datasets use corpusId when pointing\
\ to papers.</li>\n </ul>\n </li>\n <li>Other useful resources<ul>\n\
\ <li><a href=\"https://www.semanticscholar.org/product/api\">Overview</a></li>\n\
\ <li><a href=\"https://github.com/allenai/s2-folks/\">allenai/s2-folks</a></li>\n\
\ <li><a href=\"https://github.com/allenai/s2-folks/blob/main/FAQ.md\"\
>FAQ</a> in allenai/s2folks</li>\n </ul></li>\n "
servers:
- url: https://api.semanticscholar.org/graph/v1
paths:
/author/batch:
post:
summary: Get details for multiple authors at once
operationId: post_graph_get_authors
tags:
- Author Data
description: "* Fields is a single-value string parameter, not a multi-value\
\ one.\n* It is a query parameter, not to be submitted in the POST request's\
\ body.\n\nIn python:\n\n r = requests.post(\n 'https://api.semanticscholar.org/graph/v1/author/batch',\n\
\ params={'fields': 'name,hIndex,citationCount'},\n json={\"\
ids\":[\"1741101\", \"1780531\"]}\n )\n print(json.dumps(r.json(), indent=2))\n\
\n [\n {\n \"authorId\": \"1741101\",\n \"name\": \"\
Oren Etzioni\",\n \"citationCount\": 34803,\n \"hIndex\": 86\n\
\ },\n {\n \"authorId\": \"1780531\",\n \"name\":\
\ \"Daniel S. Weld\",\n \"citationCount\": 35526,\n \"hIndex\"\
: 89\n }\n ]\n\nOther Examples:\n<ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/batch</code></li>\n\
\ <ul>\n <li><code>{\"ids\":[\"1741101\", \"1780531\", \"48323507\"\
]}</code></li>\n <li>Returns details for 3 authors.</li>\n <li>Each\
\ author returns the field authorId and name if no other fields are specified.</li>\n\
\ </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/batch?fields=url,name,paperCount,papers,papers.title,papers.openAccessPdf</code></li>\n\
\ <ul>\n <li><code>{\"ids\":[\"1741101\", \"1780531\", \"48323507\"\
]}</code></li>\n <li>Returns authorID, url, name, paperCount, and list\
\ of papers for 3 authors.</li>\n <li>Each paper has its paperID, title,\
\ and link if available.</li>\n </ul>\n</ul>\n<br>\nLimitations:\n<ul>\n\
\ <li>Can only process 1,000 author ids at a time.</li>\n <li>Can only\
\ return up to 10 MB of data at a time.</li>\n</ul>"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorIdList'
responses:
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: List of authors with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorWithPapers'
/author/search:
get:
summary: Search for authors by name
operationId: get_graph_get_author_search
tags:
- Author Data
description: "Specifying <code>papers</code> fields in the request will return\
\ all papers linked to each author in the results. Set a <code>limit</code>\
\ on the search results to reduce output size and latency.<br><br>\nExamples:\n\
<ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/search?query=adam+smith</code></li>\n\
\ <ul>\n <li>Returns with total=490, offset=0, next=100, and data\
\ is a list of 100 authors.</li>\n <li>Each author has their authorId\
\ and name. </li>\n </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/search?query=adam+smith&fields=name,url,papers.title,papers.year&limit=5</code></li>\n\
\ <ul>\n <li>Returns with total=490, offset=0, next=5, and data\
\ is a list of 5 authors.</li>\n <li>Each author has authorId, name,\
\ url, and a list of their papers title and year.</li>\n </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/search?query=totalGarbageNonsense</code></li>\n\
\ <ul>\n <li>Returns with total = 0, offset=0, and data is a list\
\ of 0 author.</li>\n </ul>\n <br>\n Limitations:\n<ul>\n <li>Can\
\ only return up to 10 MB of data at a time.</li>\n</ul>"
responses:
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: Batch of authors with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorSearchBatch'
/author/{author_id}:
get:
summary: Details about an author
operationId: get_graph_get_author
tags:
- Author Data
description: "Examples:\n<ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/1741101</code></li>\n\
\ <ul>\n <li>Returns the author's authorId and name.</li>\n </ul>\n\
\ <li><code>https://api.semanticscholar.org/graph/v1/author/1741101?fields=url,papers</code></li>\n\
\ <ul>\n <li>Returns the author's authorId, url, and list of papers.\
\ </li>\n <li>Each paper has its paperId plus its title.</li>\n \
\ </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/1741101?fields=url,papers.abstract,papers.authors</code></li>\n\
\ <ul>\n <li>Returns the author's authorId, url, and list of papers.\
\ </li>\n <li>Each paper has its paperId, abstract, and list of authors.</li>\n\
\ <li>In that list of authors, each author has their authorId and name.</li>\n\
\ </ul>\n <br>\n Limitations:\n <ul>\n <li>Can only return\
\ up to 10 MB of data at a time.</li>\n </ul>\n</ul>"
responses:
'404':
description: Bad paper id
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: Author with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorWithPapers'
/author/{author_id}/papers:
get:
summary: Details about an author's papers
operationId: get_graph_get_author_papers
tags:
- Author Data
description: "Fetch the papers of an author in batches.<br>\nOnly retrieves\
\ the most recent 10,000 citations/references for papers belonging to the\
\ batch.<br>\nTo retrieve the full set of citations for a paper,\nuse the\
\ /paper/{paper_id}/citations endpoint\n<br><br>\nExamples:\n<ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/1741101/papers</code></li>\n\
\ <ul>\n <li>Return with offset=0, and data is a list of the first\
\ 100 papers.</li>\n <li>Each paper has its paperId and title.</li>\n\
\ </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/1741101/papers?fields=url,year,authors&limit=2</code></li>\n\
\ <ul>\n <li>Returns with offset=0, next=2, and data is a list of\
\ 2 papers.</li>\n <li>Each paper has its paperId, url, year, and list\
\ of authors.</li>\n <li>Each author has their authorId and name.</li>\n\
\ </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/1741101/papers?fields=citations.authors&offset=260</code></li>\n\
\ <ul>\n <li>Returns with offset=260, and data is a list of the\
\ last 4 papers.</li>\n <li>Each paper has its paperId and a list of\
\ citations.</li>\n <li>Each citation has its paperId and a list of\
\ authors.</li>\n <li>Each author has their authorId and name.</li>\n\
\ </ul>\n</ul>"
responses:
'404':
description: Bad paper id
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: List of papers with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorPaperBatch'
/paper/autocomplete:
get:
summary: Suggest paper query completions
operationId: get_graph_get_paper_autocomplete
tags:
- Paper Data
description: 'To support interactive query-completion, return minimal information
about papers matching a partial query
Example:
<code>https://api.semanticscholar.org/graph/v1/paper/autocomplete?query=semanti</code>'
responses:
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: Batch of papers with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/PaperAutocomplete'
/paper/batch:
post:
summary: Get details for multiple papers at once
operationId: post_graph_get_papers
tags:
- Paper Data
description: "* Fields is a single-value string parameter, not a multi-value\
\ one.\n* It is a query parameter, not to be submitted in the POST request's\
\ body.\n\nIn python:\n\n r = requests.post(\n 'https://api.semanticscholar.org/graph/v1/paper/batch',\n\
\ params={'fields': 'referenceCount,citationCount,title'},\n \
\ json={\"ids\": [\"649def34f8be52c8b66281af98ae884c09aef38b\", \"ARXIV:2106.15928\"\
]}\n )\n print(json.dumps(r.json(), indent=2))\n\n [\n {\n \
\ \"paperId\": \"649def34f8be52c8b66281af98ae884c09aef38b\",\n \
\ \"title\": \"Construction of the Literature Graph in Semantic Scholar\"\
,\n \"referenceCount\": 27,\n \"citationCount\": 299\n \
\ },\n {\n \"paperId\": \"f712fab0d58ae6492e3cdfc1933dae103ec12d5d\"\
,\n \"title\": \"Reinfection and low cross-immunity as drivers of epidemic\
\ resurgence under high seroprevalence: a model-based approach with application\
\ to Amazonas, Brazil\",\n \"referenceCount\": 13,\n \"citationCount\"\
: 0\n }\n ]\n\nOther Examples:\n<ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/batch</code></li>\n\
\ <ul>\n <li><code>{\"ids\":[\"649def34f8be52c8b66281af98ae884c09aef38b\"\
, \"ARXIV:2106.15928\"]}</code></li>\n <li>Returns details for 2 papers.</li>\n\
\ <li>Each paper has its paperId and title. </li>\n </ul>\n \
\ <li><code>https://api.semanticscholar.org/graph/v1/paper/batch?fields=title,isOpenAccess,openAccessPdf,authors</code></li>\n\
\ <ul>\n <li><code>{\"ids\":[\"649def34f8be52c8b66281af98ae884c09aef38b\"\
, \"ARXIV:2106.15928\"]}</code></li>\n <li>Returns all requested info\
\ plus paper IDs for 2 papers.</li>\n </ul>\n</ul>\n<br>\nLimitations:\n\
<ul>\n <li>Can only process 500 paper ids at a time.</li>\n <li>Can\
\ only return up to 10 MB of data at a time.</li>\n <li>Can only return\
\ up to 9999 citations at a time.</li>\n <li>For a list of supported IDs\
\ reference the \"Details about a paper\" endpoint.</li>\n</ul>"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaperBatch'
responses:
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: List of papers with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/FullPaper'
/paper/search:
get:
summary: Paper relevance search
operationId: get_graph_paper_relevance_search
tags:
- Paper Data
description: "Examples:\n<ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/search?query=covid+vaccination&offset=100&limit=3</code></li>\n\
\ <ul>\n <li>Returns with total=576278, offset=100, next=103, and data\
\ is a list of 3 papers.</li>\n <li>Each paper has its paperId and title.\
\ </li>\n </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/search?query=covid&fields=url,abstract,authors</code></li>\n\
\ <ul>\n <li>Returns with total=639637, offset=0, next=100, and data is\
\ a list of 100 papers.</li>\n <li>Each paper has paperId, url, abstract,\
\ and a list of authors.</li>\n <li>Each author under that list has authorId\
\ and name.</li>\n </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/search?query=totalGarbageNonsense</code></li>\n\
\ <ul>\n <li>Returns with total=0, offset=0, and data is a list of 0 papers.</li>\n\
\ </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/search?query=covid&year=2020-2023&openAccessPdf&fieldsOfStudy=Physics,Philosophy&fields=title,year,authors</code></li>\n\
\ <ul>\n <li>Returns with total=8471, offset=0, next=10, and data is a\
\ list of 10 papers. </li>\n <li>Filters to include only papers published\
\ between 2020-2023.</li>\n <li>Filters to include only papers with open\
\ access PDFs.</li>\n <li>Filters to include only papers that have a field\
\ of study either matching Physics or Philosophy.</li>\n <li>Each paper\
\ has the fields paperId, title, year, and authors.</li>\n </ul>\n <br>\n\
\ Limitations:\n <ul>\n <li>Can only return up to 1,000 relevance-ranked\
\ results. For larger queries, see \"/search/bulk\" or the Datasets API.</li>\n\
\ <li>Can only return up to 10 MB of data at a time.</li>\n </ul>\n\
</ul>"
responses:
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: Batch of papers with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/PaperRelevanceSearchBatch'
/paper/search/bulk:
get:
summary: Paper bulk search
operationId: get_graph_paper_bulk_search
tags:
- Paper Data
description: 'Behaves similarly to <code>/paper/search</code>, but is intended
for bulk retrieval of basic paper data without search relevance:
<ul>
<li>Text query is optional and supports boolean logic for document matching.</li>
<li>Papers can be filtered using various criteria.</li>
<li>Up to 1,000 papers will be returned in each call.</li>
<li>If there are more matching papers, a continuation "token" will be present.</li>
<li>The query can be repeated with the token param added to efficiently continue
fetching matching papers.</li>
</ul>
<br>
Returns a structure with an estimated total matches, batch of matching papers,
and a continuation token if more results are available.
<br>
Limitations:
<ul>
<li>Nested paper data, such as citations, references, etc, is not available
via this method.</li>
<li>Up to 10,000,000 papers can be fetched via this method. For larger needs,
please use the <a href="datasets/">Datasets API</a> to retrieve full copies
of the corpus.</li>
</ul>'
responses:
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: Batch of papers with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/PaperBulkSearchBatch'
/paper/search/match:
get:
summary: Paper title search
operationId: get_graph_paper_title_search
tags:
- Paper Data
description: "Behaves similarly to <code>/paper/search</code>, but is intended\
\ for retrieval of a single paper based on closest title match to given query.\n\
Examples:\n<ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/search/match?query=Construction\
\ of the Literature Graph in Semantic Scholar</code></li>\n <ul>\n <li>Returns\
\ a single paper that is the closest title match.</li>\n <li>Each paper\
\ has its paperId, title, and matchScore as well as any other requested fields.</li>\n\
\ </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/search/match?query=totalGarbageNonsense</code></li>\n\
\ <ul>\n <li>Returns with a 404 error and a \"Title match not found\"\
\ message.</li>\n </ul>\n</ul>\n <br>\n Limitations:\n <ul>\n \
\ <li>Will only return the single highest match result.</li>\n </ul>\n\
</ul>"
responses:
'404':
description: No title match
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: Best Title match paper with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/PaperMatch'
/paper/{paper_id}:
get:
summary: Details about a paper
operationId: get_graph_get_paper
tags:
- Paper Data
description: "Examples:\n<ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/649def34f8be52c8b66281af98ae884c09aef38b</code></li>\n\
\ <ul>\n <li>Returns a paper with its paperId and title. </li>\n\
\ </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/649def34f8be52c8b66281af98ae884c09aef38b?fields=url,year,authors</code></li>\n\
\ <ul>\n <li>Returns the paper's paperId, url, year, and list of\
\ authors. </li>\n <li>Each author has authorId and name.</li>\n \
\ </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/649def34f8be52c8b66281af98ae884c09aef38b?fields=citations.authors</code></li>\n\
\ <ul>\n <li>Returns the paper's paperId and list of citations.\
\ </li>\n <li>Each citation has its paperId plus its list of authors.</li>\n\
\ <li>Each author has their 2 always included fields of authorId and\
\ name.</li>\n </ul>\n <br>\n Limitations:\n <ul>\n <li>Can\
\ only return up to 10 MB of data at a time.</li>\n </ul>\n</ul>"
responses:
'404':
description: Bad paper id
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: Paper with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/FullPaper'
/paper/{paper_id}/authors:
get:
summary: Details about a paper's authors
operationId: get_graph_get_paper_authors
tags:
- Paper Data
description: "Examples:\n<ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/649def34f8be52c8b66281af98ae884c09aef38b/authors</code></li>\n\
\ <ul>\n <li>Returns with offset=0, and data is a list of all 3\
\ authors.</li>\n <li>Each author has their authorId and name</li>\n\
\ </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/649def34f8be52c8b66281af98ae884c09aef38b/authors?fields=affiliations,papers&limit=2</code></li>\n\
\ <ul>\n <li>Returns with offset=0, next=2, and data is a list of\
\ 2 authors.</li>\n <li>Each author has their authorId, affiliations,\
\ and list of papers.</li>\n <li>Each paper has its paperId and title.</li>\n\
\ </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/649def34f8be52c8b66281af98ae884c09aef38b/authors?fields=url,papers.year,papers.authors&offset=2</code></li>\n\
\ <ul>\n <li>Returns with offset=2, and data is a list containing\
\ the last author.</li>\n <li>This author has their authorId, url,\
\ and list of papers.</li>\n <li>Each paper has its paperId, year,\
\ and list of authors.</li>\n <li>In that list of authors, each author\
\ has their authorId and name.</li>\n </ul>\n</ul>"
responses:
'404':
description: Bad paper id
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: List of Authors with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorBatch'
/paper/{paper_id}/citations:
get:
summary: Details about a paper's citations
operationId: get_graph_get_paper_citations
tags:
- Paper Data
description: "Fetch details about the papers that cite this paper (i.e. papers\
\ in whose bibliography this paper appears)\n<br><br>\nExamples:\n<ul>\n \
\ <li>Let's suppose that the paper in the examples below has 1600 citations...</li>\n\
\ <li><code>https://api.semanticscholar.org/graph/v1/paper/649def34f8be52c8b66281af98ae884c09aef38b/citations</code></li>\n\
\ <ul>\n <li>Returns with offset=0, next=100, and data is a list\
\ of 100 citations.</li>\n <li>Each citation has a citingPaper which\
\ contains its paperId and title.</li>\n </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/649def34f8be52c8b66281af98ae884c09aef38b/citations?fields=contexts,intents,isInfluential,abstract&offset=200&limit=10</code></li>\n\
\ <ul>\n <li>Returns with offset=200, next=210, and data is a list\
\ of 10 citations.</li>\n <li>Each citation has contexts, intents,\
\ isInfluential, and a citingPaper which contains its paperId and abstract.</li>\n\
\ </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/649def34f8be52c8b66281af98ae884c09aef38b/citations?fields=authors&offset=1500&limit=500</code></li>\n\
\ <ul>\n <li>Returns with offset=1500, and data is a list of the\
\ last 100 citations.</li>\n <li>Each citation has a citingPaper which\
\ contains its paperId plus a list of authors</li>\n <li>The authors\
\ under each citingPaper has their authorId and name.</li>\n </ul>\n</ul>"
responses:
'404':
description: Bad paper id
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: Batch of citations with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/CitationBatch'
/paper/{paper_id}/references:
get:
summary: Details about a paper's references
operationId: get_graph_get_paper_references
tags:
- Paper Data
description: "Fetch details about the papers cited by this paper (i.e. appearing\
\ in this paper's bibliography)\n<br><br>\nExamples:\n<ul>\n <li>Let's\
\ suppose that the paper in the examples below has 1600 references...</li>\n\
\ <li><code>https://api.semanticscholar.org/graph/v1/paper/649def34f8be52c8b66281af98ae884c09aef38b/references</code></li>\n\
\ <ul>\n <li>Returns with offset=0, next=100, and data is a list\
\ of 100 references.</li>\n <li>Each reference has a citedPaper which\
\ contains its paperId and title.</li>\n </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/649def34f8be52c8b66281af98ae884c09aef38b/references?fields=contexts,intents,isInfluential,abstract&offset=200&limit=10</code></li>\n\
\ <ul>\n <li>Returns with offset=200, next=210, and data is a list\
\ of 10 references.</li>\n <li>Each reference has contexts, intents,\
\ isInfluential, and a citedPaper which contains its paperId and abstract.</li>\n\
\ </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/paper/649def34f8be52c8b66281af98ae884c09aef38b/references?fields=authors&offset=1500&limit=500</code></li>\n\
\ <ul>\n <li>Returns with offset=1500, and data is a list of the\
\ last 100 references.</li>\n <li>Each reference has a citedPaper which\
\ contains its paperId plus a list of authors</li>\n <li>The authors\
\ under each citedPaper has their authorId and name.</li>\n </ul>\n</ul>"
responses:
'404':
description: Bad paper id
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: Batch of references with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/ReferenceBatch'
/snippet/search:
get:
summary: Text snippet search
operationId: get_snippet_search
tags:
- Snippet Text
description: "Return the text snippets that most closely match the query. Text\
\ snippets are excerpts of approximately 500 words, drawn from a paper's title,\
\ abstract, and body text, but excluding figure captions and the bibliography.\n\
It will return the highest ranked snippet first, as well as some basic data\
\ about the paper it was found in.\nExamples:\n<ul>\n <li><code>https://api.semanticscholar.org/graph/v1/snippet/search?query=The\
\ literature graph is a property graph with directed edges&limit=1</code></li>\n\
\ <ul>\n <li>Returns a single snippet that is the highest ranked match.</li>\n\
\ <li>Each snippet has text, snippetKind, section, annotation data, and\
\ score. As well as the following data about the paper it comes from: corpusId,\
\ title, authors, and openAccessInfo.</li>\n </ul>\n</ul>\n <br>\n Limitations:\n\
\ <ul>\n <li>You must include a query.</li>\n <li>If you\
\ don't set a limit, it will automatically return 10 results.</li>\n \
\ <li>The max limit allowed is 1000.</li>\n </ul>\n</ul>"
responses:
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: Best snippet match with default fields
content:
application/json:
schema:
$ref: '#/components/schemas/SnippetMatch'
components:
schemas:
Error404:
properties:
error:
type: string
description: "Depending on the case, error message may be any of these:\n\
<ul>\n <li><code>\"Paper/Author/Object not found\"</code></li>\n \
\ <li><code>\"Paper/Author/Object with id ### not found\"</code></li>\n\
</ul>"
example: Requested object not found
type: object
Error400:
properties:
error:
type: string
description: "Depending on the case, error message may be any of these:\n\
<ul>\n <li><code>\"Unrecognized or unsupported fields: [bad1, bad2,\
\ etc...]\"</code></li>\n <li><code>\"Unacceptable query params: [badK1=badV1,\
\ badK2=badV2, etc...}]\"</code></li>\n <li><code>\"Response would\
\ exceed maximum size....\"</code></li>\n <ul><li>This error will\
\ occur when the response exceeds 10 MB. Suggestions to either break the\
\ request into smaller batches, or make use of the limit and offset features\
\ will be presented.</li></ul>\n <li>A custom message string</li></ul>"
example: 'Unrecognized or unsupported fields: [author.creditCardNumber,
garbage]'
type: object
FullPaper:
properties:
paperId:
type: string
description: Semantic Scholar’s primary unique identifier for a paper.
example: 5c5751d45e298cea054f32b392c12c61027d2fe7
corpusId:
type: integer
description: Semantic Scholar’s secondary unique identifier for a paper.
example: 215416146
externalIds:
type: object
description: 'An object that contains the paper’s unique identifiers in
external sources. The external sources are limited to: ArXiv, MAG, ACL,
PubMed, Medline, PubMedCentral, DBLP, and DOI.'
example:
MAG: '3015453090'
DBLP: conf/acl/LoWNKW20
ACL: 2020.acl-main.447
DOI: 10.18653/V1/2020.ACL-MAIN.447
CorpusId: 215416146
url:
type: string
description: URL of the paper on the Semantic Scholar website.
example: https://www.semanticscholar.org/paper/5c5751d45e298cea054f32b392c12c61027d2fe7
title:
type: string
description: Title of the paper.
example: Construction of the Literature Graph in Semantic Scholar
abstract:
type: string
description: The paper's abstract. Note that due
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/semantic-scholar/refs/heads/main/openapi/semantic-scholar-academic-graph-openapi.yml