swagger.json

{"swagger": "2.0", "basePath": "/recommendations/v1", "paths": {"/papers/": {"parameters": [{"default": 100, "type": "integer", "in": "query", "description": "How many recommendations to return. Maximum 500.", "name": "limit"}, {"in": "query", "description": "A comma-separated list of the fields to be returned.<br><br>\n\nThe following case-sensitive paper fields are recognized:\n<ul>\n    <li><code>paperId</code> - Always included</li>\n    <li><code>externalIds</code></li>\n    <li><code>url</code></li>\n    <li><code>title</code> - Included if no fields are specified</li>\n    <li><code>abstract</code></li>\n    <li><code>venue</code></li>\n    <li><code>year</code></li>\n    <li><code>referenceCount</code></li>\n    <li><code>citationCount</code></li>\n    <li><code>influentialCitationCount</code></li>\n    <li><code>isOpenAccess</code></li>\n    <li><code>fieldsOfStudy</code></li>\n    <li><code>s2FieldsOfStudy</code></li>\n    <li><code>authors</code> - Up to 500 will be returned</li>\n    <ul>\n        <li><code>authorId</code> - Always included</li>\n        <li><code>name</code> - Always included</li>\n    </ul>\n</ul>\n<br><br>\nExamples:\n<ul>\n    <li><code>https://api.semanticscholar.org/recommendations/v1/papers/forpaper/321d1f1f1f?fields=url,abstract,authors</code></li>\n    <ul>\n        <li>Each paper has paperId, url, abstract, and a list of authors.</li>\n    </ul>\n</ul>", "name": "fields", "type": "string"}], "post": {"responses": {"404": {"description": "Input papers not found", "schema": {"$ref": "#/definitions/Error404"}}, "400": {"description": "Bad query parameters", "schema": {"$ref": "#/definitions/Error400"}}, "200": {"description": "List of recommendations with default or requested fields", "schema": {"$ref": "#/definitions/Paper%20Recommendations"}}}, "summary": "Get recommended papers for lists of positive and negative example papers", "operationId": "post_papers", "parameters": [{"name": "payload", "required": true, "in": "body", "schema": {"$ref": "#/definitions/Paper%20Input"}}], "tags": ["Paper Recommendations"]}}, "/papers/forpaper/{paper_id}": {"parameters": [{"default": 100, "type": "integer", "in": "query", "description": "How many recommendations to return. Maximum 500.", "name": "limit"}, {"in": "query", "description": "A comma-separated list of the fields to be returned.<br><br>\n\nThe following case-sensitive paper fields are recognized:\n<ul>\n    <li><code>paperId</code> - Always included</li>\n    <li><code>externalIds</code></li>\n    <li><code>url</code></li>\n    <li><code>title</code> - Included if no fields are specified</li>\n    <li><code>abstract</code></li>\n    <li><code>venue</code></li>\n    <li><code>year</code></li>\n    <li><code>referenceCount</code></li>\n    <li><code>citationCount</code></li>\n    <li><code>influentialCitationCount</code></li>\n    <li><code>isOpenAccess</code></li>\n    <li><code>fieldsOfStudy</code></li>\n    <li><code>s2FieldsOfStudy</code></li>\n    <li><code>authors</code> - Up to 500 will be returned</li>\n    <ul>\n        <li><code>authorId</code> - Always included</li>\n        <li><code>name</code> - Always included</li>\n    </ul>\n</ul>\n<br><br>\nExamples:\n<ul>\n    <li><code>https://api.semanticscholar.org/recommendations/v1/papers/forpaper/321d1f1f1f?fields=url,abstract,authors</code></li>\n    <ul>\n        <li>Each paper has paperId, url, abstract, and a list of authors.</li>\n    </ul>\n</ul>", "name": "fields", "type": "string"}, {"name": "paper_id", "in": "path", "required": true, "type": "string"}], "get": {"responses": {"404": {"description": "Input papers not found", "schema": {"$ref": "#/definitions/Error404"}}, "400": {"description": "Bad query parameters", "schema": {"$ref": "#/definitions/Error400"}}, "200": {"description": "List of recommendations with default or requested fields", "schema": {"$ref": "#/definitions/Paper%20Recommendations"}}}, "summary": "Get recommended papers for a single positive example paper", "operationId": "get_papers_for_paper", "tags": ["Paper Recommendations"]}}}, "info": {"title": "Recommendations API", "version": "1.0", "description": "Get Semantic Scholar's recommended papers given other papers as input. All methods will return up to LIMIT recommendations if they are available."}, "produces": ["application/json"], "consumes": ["application/json"], "tags": [{"name": "Paper Recommendations"}], "definitions": {"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": "Paper with id 0 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>A custom message string</li></ul>", "example": "Unrecognized or unsupported fields: [author.creditCardNumber, garbage]"}}, "type": "object"}, "Paper Recommendations": {"properties": {"recommendedPapers": {"type": "array", "items": {"$ref": "#/definitions/FullPaper"}}}, "type": "object"}, "FullPaper": {"required": ["paperId"], "properties": {"paperId": {"type": "string", "example": "649def34f8be52c8b66281af98ae884c09aef38b"}, "externalIds": {"type": "object", "description": "Other catalog IDs for this paper, if known. Supports ArXiv, MAG, ACL, PubMed, Medline, PubMedCentral, DBLP, DOI.", "example": {"ArXiv": "...", "DBLP": "...", "PubMedCentral": "..."}}, "url": {"type": "string", "description": "URL on the Semantic Scholar website", "example": "https://www.semanticscholar.org/paper/649def34f8be52c8b66281af98ae884c09aef38b"}, "title": {"type": "string", "title": "This field will be provided if no fields are specified", "example": "Construction of the Literature Graph in Semantic Scholar"}, "abstract": {"type": "string", "example": "We describe a deployed scalable system for organizing published scientific literature into a heterogeneous graph to facilitate algorithmic manipulation and discovery."}, "venue": {"type": "string", "example": "NAACL"}, "year": {"type": "integer", "example": 2018}, "referenceCount": {"type": "integer", "example": 321}, "citationCount": {"type": "integer", "example": 987}, "influentialCitationCount": {"type": "integer", "description": "https://www.semanticscholar.org/faq#influential-citations", "example": 654}, "isOpenAccess": {"type": "boolean", "description": "https://www.openaccess.nl/en/what-is-open-access"}, "fieldsOfStudy": {"type": "object", "description": "A list of high-level academic categories from external sources.", "example": ["Computer Science"]}, "s2FieldsOfStudy": {"type": "object", "description": "A list of high-level academic categories, inc their sources", "example": [{"category": "Computer Science", "source": "external"}, {"category": "Computer Science", "source": "s2-fos-model"}, {"category": "Mathematics", "source": "s2-fos-model"}]}, "publicationTypes": {"type": "array", "description": "The type of this publication", "example": ["Journal Article", "Review"], "items": {"type": "string"}}, "publicationDate": {"type": "string", "description": "Year-month-day when this paper was published", "example": "2015-01-17"}, "journal": {"type": "object", "description": "Journal name, volume, and pages", "example": {"name": "Remote Sensing of Environment", "pages": "255-271", "volume": "176"}}, "authors": {"type": "array", "items": {"title": "Author Info", "allOf": [{"$ref": "#/definitions/Author"}]}}, "citations": {"type": "array", "title": "Paper Info 2", "items": {"$ref": "#/definitions/PaperInfo2"}}, "references": {"type": "array", "items": {"title": "Paper Info 2", "allOf": [{"$ref": "#/definitions/PaperInfo2"}]}}, "embedding": {"$ref": "#/definitions/Embedding"}, "tldr": {"$ref": "#/definitions/Tldr"}}, "type": "object"}, "Author": {"required": ["authorId"], "properties": {"authorId": {"type": "string", "example": "1741101"}, "externalIds": {"type": "object", "description": "ORCID/DBLP IDs for this author, if known", "example": {"DBLP": 123, "ORCID": 456}}, "url": {"type": "string", "description": "URL on the Semantic Scholar website", "example": "https://www.semanticscholar.org/author/1741101"}, "name": {"type": "string", "title": "This field will be provided if no fields are specified", "example": "Oren Etzioni"}, "aliases": {"type": "object", "description": "List of aliases", "example": ["O Et-zioni", "Oren Etzioni"]}, "affiliations": {"type": "object", "description": "List of affiliations", "example": ["Allen Institute for AI"]}, "homepage": {"type": "string", "description": "Author's own homepage", "example": "https://allenai.org/"}, "paperCount": {"type": "string", "description": "Author's total publications count", "example": 10}, "citationCount": {"type": "string", "description": "Author's total citations count", "example": 50}, "hIndex": {"type": "string", "description": "https://www.semanticscholar.org/faq#h-index", "example": 5}}, "type": "object"}, "PaperInfo2": {"required": ["paperId"], "properties": {"paperId": {"type": "string", "example": "0000000000000000000"}, "externalIds": {"type": "object", "description": "Other catalog IDs for this paper, if known. Supports ArXiv, MAG, ACL, PubMed, Medline, PubMedCentral, DBLP, DOI.", "example": {"ArXiv": "...", "DBLP": "...", "PubMedCentral": "..."}}, "url": {"type": "string", "description": "URL on the Semantic Scholar website", "example": "https://www.semanticscholar.org/paper/0000000000000000000"}, "title": {"type": "string", "title": "This field will be provided if no fields are specified", "example": "Some paper that's citing or referencing the main paper in the query"}, "abstract": {"type": "string", "example": "Abstract here..."}, "venue": {"type": "string", "example": "NAACL"}, "year": {"type": "integer", "example": 2018}, "referenceCount": {"type": "integer", "example": 123}, "citationCount": {"type": "integer", "example": 456}, "influentialCitationCount": {"type": "integer", "example": 789}, "isOpenAcess": {"type": "boolean", "description": "https://www.openaccess.nl/en/what-is-open-access"}, "fieldsOfStudy": {"type": "object", "description": "A list of high-level academic categories from external sources.", "example": ["Computer Science"]}, "s2FieldsOfStudy": {"type": "object", "description": "A list of high-level academic categories, inc their sources", "example": [{"category": "Computer Science", "source": "external"}, {"category": "Computer Science", "source": "s2-fos-model"}, {"category": "Mathematics", "source": "s2-fos-model"}]}, "authors": {"type": "array", "items": {"title": "Author Info", "allOf": [{"$ref": "#/definitions/AuthorInfo"}]}}}, "type": "object"}, "AuthorInfo": {"required": ["authorId", "name"], "properties": {"authorId": {"type": "string", "example": "1741101"}, "name": {"type": "string", "example": "Oren Etzioni"}}, "type": "object"}, "Embedding": {"required": ["model", "vector"], "properties": {"model": {"type": "string", "description": "The underlying model+version that produced the embedding", "example": "specter@v0.1.1"}, "vector": {"type": "object", "description": "Numerical embedding vector", "example": [-8.82082748413086, -2.6610865592956543]}}, "type": "object"}, "Tldr": {"required": ["model", "text"], "properties": {"model": {"type": "string", "description": "The underlying model+version that produced the tldr", "example": "tldr@v2.0.0"}, "text": {"type": "string", "description": "paper TLDR summary", "example": "This paper reduces literature graph construction into familiar NLP tasks, point out research challenges due to differences from standard formulations of these tasks, and report empirical results for each task."}}, "type": "object"}, "Paper Input": {"properties": {"positivePaperIds": {"type": "array", "items": {"type": "string", "example": "649def34f8be52c8b66281af98ae884c09aef38b"}}, "negativePaperIds": {"type": "array", "items": {"type": "string", "example": "ArXiv:1805.02262"}}}, "type": "object"}}, "responses": {"ParseError": {"description": "When a mask can't be parsed"}, "MaskError": {"description": "When any error occurs on mask"}}}