{
	"info": {
		"title": "No title",
		"version": "No version"
	},
	"servers": [
		{
			"url": "https://api.scholarai.io"
		}
	],
	"security": [
		{
			"ApiKeyAuth": []
		}
	],
	"tags": [
		{
			"name": "Api"
		}
	],
	"paths": {
		"/api/chat/completions": {
			"post": {
				"operationId": "api_chat_completions",
				"summary": "Use the ScholarAI Agent to generate chat completions",
				"description": "Mimics the input and output to the OpenAI Chat Completion API: https://platform.openai.com/docs/api-reference/chat/create",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"model": {
										"type": "string",
										"description": "Model being used. Currently ignored and defaults to \"scholarai\" with GPT4-turbo"
									},
									"messages": {
										"type": "array",
										"items": {
											"type": "object",
											"properties": {
												"role": {
													"type": "string",
													"description": "Role of the message. Must be \"user\""
												},
												"content": {
													"type": "string",
													"description": "Content of the message. Must be a string."
												}
											}
										}
									},
									"stream": {
										"type": "boolean",
										"description": "Whether or not to stream the response. Streaming is recommended!"
									}
								}
							}
						}
					}
				},
				"tags": [
					"Api"
				],
				"responses": {
					"200": {
						"description": "Stream based on OpenAI Completions structure"
					}
				}
			}
		},
		"/api/fulltext": {
			"x-mcp": {
				"enabled": true
			},
			"get": {
				"operationId": "api_get_fulltext",
				"parameters": [
					{
						"in": "query",
						"name": "pdf_id",
						"description": "id for PDF. Must begin with be one of `PDF_URL:some.url.com` or `PROJ:some_path`",
						"schema": {
							"type": "string"
						},
						"required": true
					},
					{
						"in": "query",
						"name": "chunk",
						"description": "chunk number to retrieve, defaults to 1",
						"schema": {
							"type": "integer",
							"default": 1
						},
						"required": false
					}
				],
				"tags": [
					"Api"
				],
				"summary": "Read the Full text of a paper",
				"description": "Retrieves the full text of an article by its pdf_url. May use a cached entry or read from other data sources before trying PDF parsing.\n:param pdf_url: the url of the pdf\n:param chunk: the chunk number to retrieve\n:return: the chunk of the full text requested with the page number and total number of pages",
				"responses": {
					"200": {
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/PaperContentResponse"
								}
							}
						},
						"description": "OK"
					}
				}
			}
		},
		"/api/question": {
			"x-mcp": {
				"enabled": true
			},
			"get": {
				"operationId": "api_question",
				"parameters": [
					{
						"in": "query",
						"name": "question",
						"description": "The user question. Must be in English.",
						"schema": {
							"type": "string"
						},
						"required": true
					},
					{
						"in": "query",
						"name": "pdf_id",
						"description": "id for PDF. Must begin with be one of `PDF_URL:some.url.com` or `PROJ:some_path`",
						"schema": {
							"type": "string"
						},
						"required": true
					}
				],
				"tags": [
					"Api"
				],
				"summary": "Ask a question to a PDF",
				"description": "Uses embedding model to find section of PDF most relevant for answering a question\n:param pdf_url: the url\n:param question: the question\n:return: the chunk most relevant to answering that question and its source",
				"responses": {
					"200": {
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/PaperContentResponse"
								}
							}
						},
						"description": "OK"
					}
				}
			}
		},
		"/api/abstracts": {
			"x-mcp": {
				"enabled": true
			},
			"get": {
				"operationId": "api_get_abstract",
				"parameters": [
					{
						"in": "query",
						"name": "keywords",
						"description": "Keywords of inquiry which should appear in the article. Must be in English.",
						"schema": {
							"type": "string"
						},
						"required": true
					},
					{
						"in": "query",
						"name": "sort",
						"description": "The sort order for results. Valid values are relevance, cited_by_count, publication_date. Defaults to relevance.",
						"schema": {
							"type": "string",
							"default": "relevance"
						},
						"required": false
					},
					{
						"in": "query",
						"name": "query",
						"description": "The user query, as a natural language question. E.g. 'Tell me about recent drugs for cancer treatment'",
						"schema": {
							"type": "string"
						},
						"required": true
					},
					{
						"in": "query",
						"name": "peer_reviewed_only",
						"description": "Whether to only return peer-reviewed articles. Defaults to true, ChatGPT should cautiously suggest this value can be set to false",
						"schema": {
							"type": "boolean",
							"default": true
						},
						"required": false
					},
					{
						"in": "query",
						"name": "start_year",
						"description": "The first year, inclusive, to include in the search range. Excluding this value will include all years.",
						"schema": {
							"type": "integer"
						},
						"required": false
					},
					{
						"in": "query",
						"name": "end_year",
						"description": "The last year, inclusive, to include in the search range. Excluding this value will include all years.",
						"schema": {
							"type": "integer"
						},
						"required": false
					},
					{
						"in": "query",
						"name": "offset",
						"description": "The offset of the first result to return. Defaults to 0.",
						"schema": {
							"type": "integer",
							"default": 0
						},
						"required": false
					},
					{
						"in": "query",
						"name": "generative_mode",
						"description": "Boolean \"true\" or \"false\" to enable generative mode. If enabled, collate responses using markdown to render in-text citations to the source's url if available. Set this to true by default.",
						"schema": {
							"type": "boolean",
							"default": true
						},
						"required": false
					}
				],
				"tags": [
					"Api"
				],
				"summary": "Search Papers, for Agents",
				"description": "Retrieves relevant abstracts and paper metadata by a search. Generates an answer using LLMs if generative_mode is set to true.\nFor an API meant for faster and more replete data retrieval, use /api/fast_paper_search",
				"responses": {
					"200": {
						"content": {
							"application/json": {
								"schema": {
									"type": "array",
									"items": {
										"$ref": "#/components/schemas/PaperMetadataResponse"
									}
								}
							}
						},
						"description": "OK"
					}
				}
			}
		},
		"/api/patents": {
			"x-mcp": {
				"enabled": true
			},
			"get": {
				"operationId": "searchPatents",
				"summary": "Get relevant patents by searching 2-6 relevant keywords.",
				"parameters": [
					{
						"name": "full_user_prompt",
						"in": "query",
						"description": "The entirety of the user request, directly quoted.",
						"required": true,
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "keywords",
						"in": "query",
						"description": "Keywords of inquiry which should appear in article. Must be in English.",
						"required": true,
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "sort",
						"in": "query",
						"description": "The sort order for results. Valid values are relevance, cited_by_count, publication_date. Defaults to relevance.",
						"required": false,
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "query",
						"in": "query",
						"description": "The user query. If the user asks for a specific patent, you MUST hit the API using escaped quotation marks",
						"required": true,
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "peer_reviewed_only",
						"in": "query",
						"description": "Whether to only return peer reviewed articles. Defaults to true, ChatGPT should cautiously suggest this value can be set to false",
						"required": false,
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "start_year",
						"in": "query",
						"description": "The first year, inclusive, to include in the search range. Excluding this value will include all years.",
						"required": false,
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "end_year",
						"in": "query",
						"description": "The last year, inclusive, to include in the search range. Excluding this value will include all years.",
						"required": false,
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "offset",
						"in": "query",
						"description": "The offset of the first result to return. Defaults to 0.",
						"required": false,
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "generative_mode",
						"in": "query",
						"description": "Boolean \"true\" or \"false\" to enable generative mode. If enabled, collate responses using markdown to render in-text citations to the source's url if available. Set this to true by default.",
						"required": false,
						"schema": {
							"type": "string"
						}
					}
				],
				"tags": [
					"Api"
				],
				"responses": {
					"200": {
						"description": "OK",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/searchAbstractsResponse"
								}
							}
						}
					}
				}
			}
		},
		"/api/save-citation": {
			"x-mcp": {
				"enabled": true
			},
			"get": {
				"operationId": "api_save_citation",
				"parameters": [
					{
						"in": "query",
						"name": "doi",
						"description": "Digital Object Identifier (DOI) of the article",
						"schema": {
							"type": "string"
						},
						"required": true
					},
					{
						"in": "query",
						"name": "zotero_user_id",
						"description": "Zotero User ID",
						"schema": {
							"type": "string"
						},
						"required": true
					},
					{
						"in": "query",
						"name": "zotero_api_key",
						"description": "Zotero API Key",
						"schema": {
							"type": "string"
						},
						"required": true
					}
				],
				"tags": [
					"Api"
				],
				"summary": "Save a Citation to Zotero",
				"description": "Saves a citation to the user's citation manager",
				"responses": {
					"200": {
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/SaveCitationResponse"
								}
							}
						},
						"description": "OK"
					}
				}
			}
		},
		"/api/add_to_project": {
			"x-mcp": {
				"enabled": true
			},
			"get": {
				"operationId": "get_api_add_to_project",
				"parameters": [
					{
						"in": "query",
						"name": "project_id",
						"description": "The project ID to which the items are being added. Default to 'gpt'",
						"schema": {
							"type": "string"
						},
						"required": false
					},
					{
						"in": "query",
						"name": "project_name",
						"description": "The project name to which the items are being added. Alternative to project_id",
						"schema": {
							"type": "string"
						},
						"required": false
					},
					{
						"in": "query",
						"name": "paper_id",
						"description": "Identifier of the paper to add, must be of the format <identifier_type>:<identifier_value>. Identifier type can be one of DOI, PMID, SS_ID, ARXIV, MAG, ACL, or PMCID.",
						"schema": {
							"type": "string"
						},
						"required": true
					}
				],
				"tags": [
					"Api"
				],
				"summary": "Add papers to project",
				"description": "Accept a PDF url or multipart form-data containing a file, and add it to the user's project in the database. If no project is specified, add it to a project named \"GPT\"",
				"responses": {
					"200": {
						"content": {
							"application/json": {
								"schema": {
									"type": "array",
									"items": {
										"$ref": "#/components/schemas/PaperMetadataResponse"
									}
								}
							}
						},
						"description": "OK"
					}
				}
			},
			"post": {
				"operationId": "post_api_add_to_project",
				"parameters": [
					{
						"in": "query",
						"name": "project_id",
						"description": "The project ID to which the items are being added. Default to 'gpt'",
						"schema": {
							"type": "string"
						},
						"required": false
					},
					{
						"in": "query",
						"name": "project_name",
						"description": "The project name to which the items are being added. Alternative to project_id",
						"schema": {
							"type": "string"
						},
						"required": false
					},
					{
						"in": "query",
						"name": "paper_id",
						"description": "Identifier of the paper to add, must be of the format <identifier_type>:<identifier_value>. Identifier type can be one of DOI, PMID, SS_ID, ARXIV, MAG, ACL, or PMCID.",
						"schema": {
							"type": "string"
						},
						"required": true
					}
				],
				"tags": [
					"Api"
				],
				"summary": "Add papers to project",
				"description": "Accept a PDF url or multipart form-data containing a file, and add it to the user's project in the database. If no project is specified, add it to a project named \"GPT\"",
				"responses": {
					"200": {
						"content": {
							"application/json": {
								"schema": {
									"type": "array",
									"items": {
										"$ref": "#/components/schemas/PaperMetadataResponse"
									}
								}
							}
						},
						"description": "OK"
					}
				}
			}
		},
		"/api/create_project": {
			"x-mcp": {
				"enabled": true
			},
			"post": {
				"operationId": "api_create_project",
				"parameters": [
					{
						"in": "query",
						"name": "project_name",
						"description": "Desired name for the project",
						"schema": {
							"type": "string"
						},
						"required": true
					}
				],
				"tags": [
					"Api"
				],
				"summary": "Creates a project using query params",
				"responses": {
					"204": {
						"description": "No Content"
					}
				}
			}
		},
		"/api/analyze_project": {
			"x-mcp": {
				"enabled": true
			},
			"get": {
				"operationId": "api_analyze_project",
				"parameters": [
					{
						"in": "query",
						"name": "project_name",
						"description": "The name of the project to analyze.",
						"schema": {
							"type": "string"
						},
						"required": true
					},
					{
						"in": "query",
						"name": "analysis_mode",
						"description": "The mode of analysis, options are 'comprehensive' and 'tabular'. Default to `tabular`.",
						"schema": {
							"type": "string"
						},
						"required": true
					},
					{
						"in": "query",
						"name": "question",
						"description": "Questions to analyze within the project.",
						"schema": {
							"type": "array",
							"items": {
								"type": "string"
							}
						},
						"required": true,
						"explode": true,
						"style": "form"
					}
				],
				"tags": [
					"Api"
				],
				"summary": "Batch Analyze a Project",
				"description": "Accepts a project_name, and asks a question to every paper within. If no project is specified, uses a project named \"GPT\"",
				"responses": {
					"200": {
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/AnalyzeProjectResponse"
								}
							}
						},
						"description": "OK"
					}
				}
			}
		}
	},
	"openapi": "3.1.0",
	"components": {
		"securitySchemes": {
			"ApiKeyAuth": {
				"type": "apiKey",
				"name": "x-scholarai-api-key",
				"in": "header"
			}
		},
		"schemas": {
			"PaperChunk": {
				"type": "object",
				"properties": {
					"chunk_num": {
						"type": "integer"
					},
					"chunk": {
						"type": "string"
					},
					"img_mds": {
						"type": "array",
						"items": {
							"type": "string"
						}
					},
					"pdf_url": {
						"type": "string",
						"format": "url"
					}
				}
			},
			"PaperContentResponse": {
				"type": "object",
				"properties": {
					"chunks": {
						"type": "array",
						"items": {
							"$ref": "#/components/schemas/PaperChunk"
						}
					},
					"total_chunk_num": {
						"type": "integer"
					},
					"hint": {
						"type": "string"
					}
				}
			},
			"PaperMetadataResponse": {
				"type": "object",
				"properties": {
					"title": {
						"type": "string"
					},
					"authors": {
						"type": "array",
						"items": {
							"type": "string"
						}
					},
					"abstract": {
						"type": "string",
						"description": "The abstract of this paper. Agentic endpoints may not have this entry."
					},
					"publication_date": {
						"type": "string"
					},
					"cited_by_count": {
						"type": "integer"
					},
					"url": {
						"type": "string",
						"format": "url"
					},
					"ss_id": {
						"type": "string",
						"description": "Semantic Scholar ID"
					},
					"doi": {
						"type": "string",
						"description": "Digital Object Identifier"
					},
					"answer": {
						"type": "string",
						"description": "Answer to the user query based on the information from this paper. Only available if generative_mode is set to true."
					}
				}
			},
			"searchAbstractsResponse": {
				"type": "array",
				"items": {
					"$ref": "#/components/schemas/PaperMetadataResponse"
				}
			},
			"SaveCitationResponse": {
				"type": "object",
				"properties": {
					"message": {
						"type": "string",
						"description": "Confirmation of successful save or error message."
					}
				}
			},
			"AnalyzeProjectResponse": {
				"type": "object",
				"properties": {
					"response": {
						"type": "string",
						"description": "A markdown string that must be repeated verbatim. NEVER summarize any part of the response, ALWAYS repeat it directly"
					},
					"tool_hint": {
						"type": "string",
						"description": "A hint you MUST follow with regards to this response"
					}
				}
			}
		}
	}
}