# generated by fastapi-codegen:
# filename: openapi.yaml
# timestamp: 2025-07-07T16:44:08+00:00
from __future__ import annotations
from datetime import datetime
from enum import Enum
from typing import List, Optional, Union
from pydantic import AnyUrl, BaseModel, Field, conint, constr
class AnswerCitation(BaseModel):
author: Optional[str] = Field(
None,
description='If available, the author of the content.',
examples=['Dan Milmon'],
)
favicon: Optional[AnyUrl] = Field(
None,
description="The URL of the favicon for the search result's domain, if available.",
examples=[
'https://assets.guim.co.uk/static/frontend/icons/homescreen/apple-touch-icon.svg'
],
)
id: Optional[str] = Field(
None,
description='The temporary ID for the document.',
examples=[
'https://www.theguardian.com/science/2024/dec/11/spacex-valued-at-350bn-as-company-agrees-to-buy-shares-from-employees'
],
)
image: Optional[AnyUrl] = Field(
None,
description='The URL of the image associated with the search result, if available.',
examples=[
'https://i.guim.co.uk/img/media/7cfee7e84b24b73c97a079c402642a333ad31e77/0_380_6176_3706/master/6176.jpg?width=1200&height=630&quality=85&auto=format&fit=crop&overlay-align=bottom%2Cleft&overlay-width=100p&overlay-base64=L2ltZy9zdGF0aWMvb3ZlcmxheXMvdGctZGVmYXVsdC5wbmc&enable=upscale&s=71ebb2fbf458c185229d02d380c01530'
],
)
publishedDate: Optional[str] = Field(
None,
description='An estimate of the creation date, from parsing HTML content. Format is YYYY-MM-DD.',
examples=['2023-11-16T01:36:32.547Z'],
)
text: Optional[str] = Field(
None,
description='The full text content of each source. Only present when includeText is enabled.',
examples=['SpaceX valued at $350bn as company agrees to buy shares from ...'],
)
title: Optional[str] = Field(
None,
description='The title of the search result.',
examples=['SpaceX valued at $350bn as company agrees to buy shares from ...'],
)
url: Optional[AnyUrl] = Field(
None,
description='The URL of the search result.',
examples=[
'https://www.theguardian.com/science/2024/dec/11/spacex-valued-at-350bn-as-company-agrees-to-buy-shares-from-employees'
],
)
class AnswerResult(BaseModel):
answer: Optional[str] = Field(
None,
description='The generated answer based on search results.',
examples=['$350 billion.'],
)
citations: Optional[List[AnswerCitation]] = Field(
None, description='Search results used to generate the answer.'
)
class Extras(BaseModel):
imageLinks: Optional[int] = Field(
0, description='Number of images to return for each result.', examples=[1]
)
links: Optional[int] = Field(
0, description='Number of URLs to return from each webpage.', examples=[1]
)
class Highlights(BaseModel):
highlightsPerUrl: Optional[int] = Field(
1, description='The number of snippets to return for each result.', examples=[1]
)
numSentences: Optional[int] = Field(
5,
description='The number of sentences to return for each snippet.',
examples=[1],
)
query: Optional[str] = Field(
None,
description="Custom query to direct the LLM's selection of highlights.",
examples=['Key advancements'],
)
class Livecrawl(Enum):
never = 'never'
fallback = 'fallback'
always = 'always'
auto = 'auto'
class Summary(BaseModel):
query: Optional[str] = Field(
None,
description='Custom query for the LLM-generated summary.',
examples=['Main developments'],
)
class Text(BaseModel):
includeHtmlTags: Optional[bool] = Field(
False,
description='Include HTML tags, which can help LLMs understand text structure.',
examples=[False],
)
maxCharacters: Optional[int] = Field(
None,
description='Maximum character limit for the full page text.',
examples=[1000],
)
class ContentsRequest(BaseModel):
extras: Optional[Extras] = Field(None, description='Extra parameters to pass.')
highlights: Optional[Highlights] = Field(
None,
description='Text snippets the LLM identifies as most relevant from each page.',
)
livecrawl: Optional[Livecrawl] = Field(
None,
description="Options for livecrawling pages.\n'never': Disable livecrawling (default for neural search).\n'fallback': Livecrawl when cache is empty (default for keyword search).\n'always': Always livecrawl.\n'auto': Use an LLM to detect if query needs real-time content.\n",
examples=['always'],
)
livecrawlTimeout: Optional[int] = Field(
10000,
description='The timeout for livecrawling in milliseconds.',
examples=[1000],
)
subpageTarget: Optional[Union[str, List[str]]] = Field(
None,
description='Keyword to find specific subpages of search results. Can be a single string or an array of strings, comma delimited.',
examples=['sources'],
)
subpages: Optional[int] = Field(
0,
description='The number of subpages to crawl. The actual number crawled may be limited by system constraints.',
examples=[1],
)
summary: Optional[Summary] = Field(None, description='Summary of the webpage')
text: Optional[Union[bool, Text]] = None
class Result(BaseModel):
author: Optional[str] = Field(
None,
description='If available, the author of the content.',
examples=[
'Humza Naveed, University of Engineering and Technology (UET), Lahore, Pakistan'
],
)
favicon: Optional[AnyUrl] = Field(
None,
description="The URL of the favicon for the search result's domain.",
examples=['https://arxiv.org/favicon.ico'],
)
id: Optional[str] = Field(
None,
description='The temporary ID for the document. Useful for /contents endpoint.',
examples=['https://arxiv.org/abs/2307.06435'],
)
image: Optional[AnyUrl] = Field(
None,
description='The URL of an image associated with the search result, if available.',
examples=['https://arxiv.org/pdf/2307.06435.pdf/page_1.png'],
)
publishedDate: Optional[str] = Field(
None,
description='An estimate of the creation date, from parsing HTML content. Format is YYYY-MM-DD.',
examples=['2023-11-16T01:36:32.547Z'],
)
score: Optional[float] = Field(
None,
description='A number from 0 to 1 representing similarity between the query/url and the result.',
examples=[0.4600165784358978],
)
title: Optional[str] = Field(
None,
description='The title of the search result.',
examples=['A Comprehensive Overview of Large Language Models'],
)
url: Optional[AnyUrl] = Field(
None,
description='The URL of the search result.',
examples=['https://arxiv.org/pdf/2307.06435.pdf'],
)
class Extras1(BaseModel):
links: Optional[List[str]] = Field(
None, description='Array of links from the search result.', examples=[[]]
)
class ResultWithContent(Result):
extras: Optional[Extras1] = Field(None, description='Results from extras.')
highlightScores: Optional[List[float]] = Field(
None,
description='Array of cosine similarity scores for each highlighted',
examples=[[0.4600165784358978]],
)
highlights: Optional[List[str]] = Field(
None,
description='Array of highlights extracted from the search result content.',
examples=[['Such requirements have limited their adoption...']],
)
subpages: Optional[List[ResultWithContent]] = Field(
None,
description='Array of subpages for the search result.',
examples=[
[
{
'author': 'Yongliang Shen, Microsoft Research Asia, Kaitao Song, Microsoft Research Asia, Xu Tan, Microsoft Research Asia, Dongsheng Li, Microsoft Research Asia, Weiming Lu, Microsoft Research Asia, Yueting Zhuang, Microsoft Research Asia, yzhuang@zju.edu.cn, Zhejiang University, Microsoft Research Asia, Microsoft Research, Microsoft Research Asia',
'highlightScores': [0.32679107785224915],
'highlights': [
'2) Recently, some researchers started to investigate the integration of using tools or models in LLMs .'
],
'id': 'https://arxiv.org/abs/2303.17580',
'publishedDate': '2023-11-16T01:36:20.486Z',
'summary': 'HuggingGPT is a framework using ChatGPT as a central controller to orchestrate various AI models from Hugging Face to solve complex tasks. ChatGPT plans the task, selects appropriate models based on their descriptions, executes subtasks, and summarizes the results. This approach addresses limitations of LLMs by allowing them to handle multimodal data (vision, speech) and coordinate multiple models for complex tasks, paving the way for more advanced AI systems.',
'text': 'HuggingGPT: Solving AI Tasks with ChatGPT and its Friends in Hugging Face Date Published: 2023-05-25 Authors: Yongliang Shen, Microsoft Research Asia Kaitao Song, Microsoft Research Asia Xu Tan, Microsoft Research Asia Dongsheng Li, Microsoft Research Asia Weiming Lu, Microsoft Research Asia Yueting Zhuang, Microsoft Research Asia, yzhuang@zju.edu.cn Zhejiang University, Microsoft Research Asia Microsoft Research, Microsoft Research Asia Abstract Solving complicated AI tasks with different domains and modalities is a key step toward artificial general intelligence. While there are abundant AI models available for different domains and modalities, they cannot handle complicated AI tasks. Considering large language models (LLMs) have exhibited exceptional ability in language understanding, generation, interaction, and reasoning, we advocate that LLMs could act as a controller to manage existing AI models to solve complicated AI tasks and language could be a generic interface to empower t',
'title': 'HuggingGPT: Solving AI Tasks with ChatGPT and its Friends in Hugging Face',
'url': 'https://arxiv.org/pdf/2303.17580.pdf',
}
]
],
)
summary: Optional[str] = Field(
None,
description='Summary of the webpage',
examples=[
'This overview paper on Large Language Models (LLMs) highlights key developments...'
],
)
text: Optional[str] = Field(
None,
description='The full content text of the search result.',
examples=[
'Abstract Large Language Models (LLMs) have recently demonstrated remarkable capabilities...'
],
)
class Model(Enum):
exa = 'exa'
exa_pro = 'exa-pro'
class AnswerPostRequest(BaseModel):
model: Optional[Model] = Field(
'exa',
description='The search model to use for the answer. Exa passes only one query to exa, while exa-pro also passes 2 expanded queries to our search model.',
)
query: constr(min_length=1) = Field(
...,
description='The question or query to answer.',
examples=['What is the latest valuation of SpaceX?'],
)
stream: Optional[bool] = Field(
False,
description='If true, the response is returned as a server-sent events (SSS) stream.',
)
text: Optional[bool] = Field(
False,
description='If true, the response includes full text content in the search results',
)
class AnswerPostResponse(BaseModel):
answer: Optional[str] = Field(
None, description='Partial answer chunk when streaming is enabled.'
)
citations: Optional[List[AnswerCitation]] = None
class ContentsPostRequest(ContentsRequest):
ids: Optional[List[str]] = Field(
None,
description="Deprecated - use 'urls' instead. Array of document IDs obtained from searches.",
examples=[['https://arxiv.org/pdf/2307.06435']],
)
urls: List[str] = Field(
...,
description="Array of URLs to crawl (backwards compatible with 'ids' parameter).",
examples=[['https://arxiv.org/pdf/2307.06435']],
)
class ContentsPostResponse(BaseModel):
results: Optional[List[ResultWithContent]] = None
class FindSimilarPostResponse(BaseModel):
results: Optional[List[ResultWithContent]] = Field(
None,
description='A list of search results containing title, URL, published date, author, and score.',
)
class Category(Enum):
company = 'company'
research_paper = 'research paper'
news = 'news'
pdf = 'pdf'
github = 'github'
tweet = 'tweet'
personal_site = 'personal site'
linkedin_profile = 'linkedin profile'
financial_report = 'financial report'
class Type(Enum):
keyword = 'keyword'
neural = 'neural'
auto = 'auto'
class SearchType(Enum):
neural = 'neural'
keyword = 'keyword'
class SearchPostResponse(BaseModel):
results: Optional[List[ResultWithContent]] = Field(
None,
description='A list of search results containing title, URL, published date, author, and score.',
)
searchType: Optional[SearchType] = Field(
None,
description='For auto searches, indicates which search type was selected.',
examples=['auto'],
)
class CommonRequest(BaseModel):
contents: Optional[ContentsRequest] = None
endCrawlDate: Optional[datetime] = Field(
None,
description='Crawl date refers to the date that Exa discovered a link. Results will include links that were crawled before this date. Must be specified in ISO 8601 format.',
examples=['2023-12-31'],
)
endPublishedDate: Optional[datetime] = Field(
None,
description='Only links with a published date before this will be returned. Must be specified in ISO 8601 format.',
examples=['2023-12-31'],
)
excludeDomains: Optional[List[str]] = Field(
None,
description='List of domains to exclude from search results. If specified, no results will be returned from these domains.',
)
excludeText: Optional[List[str]] = Field(
None,
description='List of strings that must not be present in webpage text of results. Currently, only 1 string is supported, of up to 5 words.',
examples=[['course']],
)
includeDomains: Optional[List[str]] = Field(
None,
description='List of domains to include in the search. If specified, results will only come from these domains.',
examples=[['arxiv.org', 'paperswithcode.com']],
)
includeText: Optional[List[str]] = Field(
None,
description='List of strings that must be present in webpage text of results. Currently, only 1 string is supported, of up to 5 words.',
examples=[['large language model']],
)
numResults: Optional[conint(le=100)] = Field(
10,
description='Number of results to return (up to thousands of results available for custom plans)',
examples=[10],
)
startCrawlDate: Optional[datetime] = Field(
None,
description='Crawl date refers to the date that Exa discovered a link. Results will include links that were crawled after this date. Must be specified in ISO 8601 format.',
examples=['2023-01-01'],
)
startPublishedDate: Optional[datetime] = Field(
None,
description='Only links with a published date after this will be returned. Must be specified in ISO 8601 format.',
examples=['2023-01-01'],
)
class FindSimilarPostRequest(CommonRequest):
url: str = Field(
...,
description='The url for which you would like to find similar links.',
examples=['https://arxiv.org/abs/2307.06435'],
)
class SearchPostRequest(CommonRequest):
category: Optional[Category] = Field(
None, description='A data category to focus on.', examples=['research paper']
)
query: str = Field(
...,
description='The query string for the search.',
examples=['Latest developments in LLM capabilities'],
)
type: Optional[Type] = Field(
'auto',
description='The type of search. Neural uses an embeddings-based model, keyword is google-like SERP. Default is auto, which automatically decides between keyword and neural.',
examples=['auto'],
)
useAutoprompt: Optional[bool] = Field(
True,
description='Autoprompt converts your query to an Exa-style query. Enabled by default for auto search, optional for neural search, and not available for keyword search.',
examples=[True],
)
ResultWithContent.model_rebuild()
