exa-js/dist/index.d.ts

Exa SDK for Node.js and the browser

declare const isBeta = false;
/**
 * Search options for performing a search query.
 * @typedef {Object} SearchOptions
 * @property {number} [numResults] - Number of search results to return. Default 10. Max 10 for basic plans.
 * @property {string[]} [includeDomains] - List of domains to include in the search.
 * @property {string[]} [excludeDomains] - List of domains to exclude in the search.
 * @property {string} [startCrawlDate] - Start date for results based on crawl date.
 * @property {string} [endCrawlDate] - End date for results based on crawl date.
 * @property {string} [startPublishedDate] - Start date for results based on published date.
 * @property {string} [endPublishedDate] - End date for results based on published date.
 * @property {string} [category] - A data category to focus on, with higher comprehensivity and data cleanliness. Currently, the only category is company.
 * @property {string[]} [includeText] - List of strings that must be present in webpage text of results. Currently only supports 1 string of up to 5 words.
 * @property {string[]} [excludeText] - List of strings that must not be present in webpage text of results. Currently only supports 1 string of up to 5 words.
 * @property {string[]} [flags] - Experimental flags
 */
type BaseSearchOptions = {
    numResults?: number;
    includeDomains?: string[];
    excludeDomains?: string[];
    startCrawlDate?: string;
    endCrawlDate?: string;
    startPublishedDate?: string;
    endPublishedDate?: string;
    category?: "company" | "research paper" | "news" | "pdf" | "github" | "tweet" | "personal site" | "linkedin profile" | "financial report";
    includeText?: string[];
    excludeText?: string[];
    flags?: string[];
};
/**
 * Search options for performing a search query.
 * @typedef {Object} RegularSearchOptions
 */
type RegularSearchOptions = BaseSearchOptions & {
    /**
     * If true, the search results are moderated for safety.
     */
    moderation?: boolean;
    useAutoprompt?: boolean;
    type?: "keyword" | "neural" | "auto";
};
/**
 * Options for finding similar links.
 * @typedef {Object} FindSimilarOptions
 * @property {boolean} [excludeSourceDomain] - If true, excludes links from the base domain of the input.
 */
type FindSimilarOptions = BaseSearchOptions & {
    excludeSourceDomain?: boolean;
};
type ExtrasOptions = {
    links?: number;
    imageLinks?: number;
};
/**
 * Search options for performing a search query.
 * @typedef {Object} ContentsOptions
 * @property {TextContentsOptions | boolean} [text] - Options for retrieving text contents.
 * @property {HighlightsContentsOptions | boolean} [highlights] - Options for retrieving highlights.
 * @property {SummaryContentsOptions | boolean} [summary] - Options for retrieving summary.
 * @property {LivecrawlOptions} [livecrawl] - Options for livecrawling contents. Default is "never" for neural/auto search, "fallback" for keyword search.
 * @property {number} [livecrawlTimeout] - The timeout for livecrawling. Max and default is 10000ms.
 * @property {boolean} [filterEmptyResults] - If true, filters out results with no contents. Default is true.
 * @property {number} [subpages] - The number of subpages to return for each result, where each subpage is derived from an internal link for the result.
 * @property {string | string[]} [subpageTarget] - Text used to match/rank subpages in the returned subpage list. You could use "about" to get *about* page for websites. Note that this is a fuzzy matcher.
 * @property {ExtrasOptions} [extras] - Miscelleneous data derived from results
 */
type ContentsOptions = {
    text?: TextContentsOptions | true;
    highlights?: HighlightsContentsOptions | true;
    summary?: SummaryContentsOptions | true;
    livecrawl?: LivecrawlOptions;
    livecrawlTimeout?: number;
    filterEmptyResults?: boolean;
    subpages?: number;
    subpageTarget?: string | string[];
    extras?: ExtrasOptions;
} & (typeof isBeta extends true ? {} : {});
/**
 * Options for livecrawling contents
 * @typedef {string} LivecrawlOptions
 */
type LivecrawlOptions = "never" | "fallback" | "always" | "auto";
/**
 * Options for retrieving text from page.
 * @typedef {Object} TextContentsOptions
 * @property {number} [maxCharacters] - The maximum number of characters to return.
 * @property {boolean} [includeHtmlTags] - If true, includes HTML tags in the returned text. Default: false
 */
type TextContentsOptions = {
    maxCharacters?: number;
    includeHtmlTags?: boolean;
};
/**
 * Options for retrieving highlights from page.
 * @typedef {Object} HighlightsContentsOptions
 * @property {string} [query] - The query string to use for highlights search.
 * @property {number} [numSentences] - The number of sentences to return for each highlight.
 * @property {number} [highlightsPerUrl] - The number of highlights to return for each URL.
 */
type HighlightsContentsOptions = {
    query?: string;
    numSentences?: number;
    highlightsPerUrl?: number;
};
/**
 * Represents a JSON Schema definition used for structured summary output.
 * To learn more visit https://json-schema.org/overview/what-is-jsonschema.
 */
type JSONSchema = {
    $schema?: string;
    title?: string;
    description?: string;
    type: "object" | "array" | "string" | "number" | "boolean" | "null" | "integer";
    properties?: Record<string, JSONSchema>;
    items?: JSONSchema | JSONSchema[];
    required?: string[];
    enum?: any[];
    additionalProperties?: boolean | JSONSchema;
    definitions?: Record<string, JSONSchema>;
    patternProperties?: Record<string, JSONSchema>;
    allOf?: JSONSchema[];
    anyOf?: JSONSchema[];
    oneOf?: JSONSchema[];
    not?: JSONSchema;
};
/**
 * Options for retrieving summary from page.
 * @typedef {Object} SummaryContentsOptions
 * @property {string} [query] - The query string to use for summary generation.
 * @property {JSONSchema} [schema] - JSON schema for structured output from summary.
 */
type SummaryContentsOptions = {
    query?: string;
    schema?: JSONSchema;
};
/**
 * @typedef {Object} TextResponse
 * @property {string} text - Text from page
 */
type TextResponse = {
    text: string;
};
/**
 * @typedef {Object} HighlightsResponse
 * @property {string[]} highlights - The highlights as an array of strings.
 * @property {number[]} highlightScores - The corresponding scores as an array of floats, 0 to 1
 */
type HighlightsResponse = {
    highlights: string[];
    highlightScores: number[];
};
/**
 * @typedef {Object} SummaryResponse
 * @property {string} summary - The generated summary of the page content.
 */
type SummaryResponse = {
    summary: string;
};
/**
 * @typedef {Object} ExtrasResponse
 * @property {string[]} links - The links on the page of a result
 * @property {string[]} imageLinks - The image links on the page of a result
 */
type ExtrasResponse = {
    extras: {
        links?: string[];
        imageLinks?: string[];
    };
};
/**
 * @typedef {Object} SubpagesResponse
 * @property {ContentsResultComponent<T extends ContentsOptions>} subpages - The subpages for a result
 */
type SubpagesResponse<T extends ContentsOptions> = {
    subpages: ContentsResultComponent<T>[];
};
type Default<T extends {}, U> = [keyof T] extends [never] ? U : T;
/**
 * @typedef {Object} ContentsResultComponent
 * Depending on 'ContentsOptions', this yields a combination of 'TextResponse', 'HighlightsResponse', 'SummaryResponse', or an empty object.
 *
 * @template T - A type extending from 'ContentsOptions'.
 */
type ContentsResultComponent<T extends ContentsOptions> = Default<(T["text"] extends object | true ? TextResponse : {}) & (T["highlights"] extends object | true ? HighlightsResponse : {}) & (T["summary"] extends object | true ? SummaryResponse : {}) & (T["subpages"] extends number ? SubpagesResponse<T> : {}) & (T["extras"] extends object ? ExtrasResponse : {}), TextResponse>;
/**
 * Represents the cost breakdown related to contents retrieval. Fields are optional because
 * only non-zero costs are included.
 * @typedef {Object} CostDollarsContents
 * @property {number} [text] - The cost in dollars for retrieving text.
 * @property {number} [highlights] - The cost in dollars for retrieving highlights.
 * @property {number} [summary] - The cost in dollars for retrieving summary.
 */
type CostDollarsContents = {
    text?: number;
    highlights?: number;
    summary?: number;
};
/**
 * Represents the cost breakdown related to search. Fields are optional because
 * only non-zero costs are included.
 * @typedef {Object} CostDollarsSeearch
 * @property {number} [neural] - The cost in dollars for neural search.
 * @property {number} [keyword] - The cost in dollars for keyword search.
 */
type CostDollarsSeearch = {
    neural?: number;
    keyword?: number;
};
/**
 * Represents the total cost breakdown. Only non-zero costs are included.
 * @typedef {Object} CostDollars
 * @property {number} total - The total cost in dollars.
 * @property {CostDollarsSeearch} [search] - The cost breakdown for search.
 * @property {CostDollarsContents} [contents] - The cost breakdown for contents.
 */
type CostDollars = {
    total: number;
    search?: CostDollarsSeearch;
    contents?: CostDollarsContents;
};
/**
 * Represents a search result object.
 * @typedef {Object} SearchResult
 * @property {string} title - The title of the search result.
 * @property {string} url - The URL of the search result.
 * @property {string} [publishedDate] - The estimated creation date of the content.
 * @property {string} [author] - The author of the content, if available.
 * @property {number} [score] - Similarity score between the query/url and the result.
 * @property {string} id - The temporary ID for the document.
 * @property {string} [image] - A representative image for the content, if any.
 * @property {string} [favicon] - A favicon for the site, if any.
 */
type SearchResult<T extends ContentsOptions> = {
    title: string | null;
    url: string;
    publishedDate?: string;
    author?: string;
    score?: number;
    id: string;
    image?: string;
    favicon?: string;
} & ContentsResultComponent<T>;
/**
 * Represents a search response object.
 * @typedef {Object} SearchResponse
 * @property {Result[]} results - The list of search results.
 * @property {string} [autopromptString] - The autoprompt string, if applicable.
 * @property {string} [autoDate] - The autoprompt date, if applicable.
 * @property {string} requestId - The request ID for the search.
 * @property {CostDollars} [costDollars] - The cost breakdown for this request.
 */
type SearchResponse<T extends ContentsOptions> = {
    results: SearchResult<T>[];
    autopromptString?: string;
    autoDate?: string;
    requestId: string;
    costDollars?: CostDollars;
};
/**
 * Options for the answer endpoint
 * @typedef {Object} AnswerOptions
 * @property {boolean} [stream] - Whether to stream the response. Default false.
 * @property {boolean} [text] - Whether to include text in the source results. Default false.
 * @property {"exa" | "exa-pro"} [model] - The model to use for generating the answer. Default "exa".
 */
type AnswerOptions = {
    stream?: boolean;
    text?: boolean;
    model?: "exa" | "exa-pro";
};
/**
 * Represents an answer response object from the /answer endpoint.
 * @typedef {Object} AnswerResponse
 * @property {string} answer - The generated answer text.
 * @property {SearchResult<{}>[]} citations - The sources used to generate the answer.
 * @property {string} [requestId] - Optional request ID for the answer.
 */
type AnswerResponse = {
    answer: string;
    citations: SearchResult<{}>[];
    requestId?: string;
};
type AnswerStreamChunk = {
    /**
     * The partial text content of the answer (if present in this chunk).
     */
    content?: string;
    /**
     * Citations associated with the current chunk of text (if present).
     */
    citations?: Array<{
        id: string;
        url: string;
        title?: string;
        publishedDate?: string;
        author?: string;
        text?: string;
    }>;
};
/**
 * Represents a streaming answer response chunk from the /answer endpoint.
 * @typedef {Object} AnswerStreamResponse
 * @property {string} [answer] - A chunk of the generated answer text.
 * @property {SearchResult<{}>[]]} [citations] - The sources used to generate the answer.
 */
type AnswerStreamResponse = {
    answer?: string;
    citations?: SearchResult<{}>[];
};
/**
 * The Exa class encapsulates the API's endpoints.
 */
declare class Exa {
    private baseURL;
    private headers;
    /**
     * Helper method to separate out the contents-specific options from the rest.
     */
    private extractContentsOptions;
    /**
     * Constructs the Exa API client.
     * @param {string} apiKey - The API key for authentication.
     * @param {string} [baseURL] - The base URL of the Exa API.
     */
    constructor(apiKey?: string, baseURL?: string);
    /**
     * Makes a request to the Exa API.
     * @param {string} endpoint - The API endpoint to call.
     * @param {string} method - The HTTP method to use.
     * @param {any} [body] - The request body for POST requests.
     * @returns {Promise<any>} The response from the API.
     */
    private request;
    /**
     * Performs a search with an Exa prompt-engineered query.
     *
     * @param {string} query - The query string.
     * @param {RegularSearchOptions} [options] - Additional search options
     * @returns {Promise<SearchResponse<{}>>} A list of relevant search results.
     */
    search(query: string, options?: RegularSearchOptions): Promise<SearchResponse<{}>>;
    /**
     * Performs a search with an Exa prompt-engineered query and returns the contents of the documents.
     *
     * @param {string} query - The query string.
     * @param {RegularSearchOptions & T} [options] - Additional search + contents options
     * @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
     */
    searchAndContents<T extends ContentsOptions>(query: string, options?: RegularSearchOptions & T): Promise<SearchResponse<T>>;
    /**
     * Finds similar links to the provided URL.
     * @param {string} url - The URL for which to find similar links.
     * @param {FindSimilarOptions} [options] - Additional options for finding similar links.
     * @returns {Promise<SearchResponse<{}>>} A list of similar search results.
     */
    findSimilar(url: string, options?: FindSimilarOptions): Promise<SearchResponse<{}>>;
    /**
     * Finds similar links to the provided URL and returns the contents of the documents.
     * @param {string} url - The URL for which to find similar links.
     * @param {FindSimilarOptions & T} [options] - Additional options for finding similar links + contents.
     * @returns {Promise<SearchResponse<T>>} A list of similar search results, including requested contents.
     */
    findSimilarAndContents<T extends ContentsOptions>(url: string, options?: FindSimilarOptions & T): Promise<SearchResponse<T>>;
    /**
     * Retrieves contents of documents based on URLs.
     * @param {string | string[] | SearchResult[]} urls - A URL or array of URLs, or an array of SearchResult objects.
     * @param {ContentsOptions} [options] - Additional options for retrieving document contents.
     * @returns {Promise<SearchResponse<T>>} A list of document contents for the requested URLs.
     */
    getContents<T extends ContentsOptions>(urls: string | string[] | SearchResult<T>[], options?: T): Promise<SearchResponse<T>>;
    /**
     * Generate an answer to a query.
     * @param {string} query - The question or query to answer.
     * @param {AnswerOptions} [options] - Additional options for answer generation.
     * @returns {Promise<AnswerResponse>} The generated answer and source references.
     *
     * Note: For streaming responses, use the `streamAnswer` method:
     * ```ts
     * for await (const chunk of exa.streamAnswer(query)) {
     *   // Handle chunks
     * }
     * ```
     */
    answer(query: string, options?: AnswerOptions): Promise<AnswerResponse>;
    /**
     * Stream an answer as an async generator
     *
     * Each iteration yields a chunk with partial text (`content`) or new citations.
     * Use this if you'd like to read the answer incrementally, e.g. in a chat UI.
     *
     * Example usage:
     * ```ts
     * for await (const chunk of exa.streamAnswer("What is quantum computing?", { text: false })) {
     *   if (chunk.content) process.stdout.write(chunk.content);
     *   if (chunk.citations) {
     *     console.log("\nCitations: ", chunk.citations);
     *   }
     * }
     * ```
     */
    streamAnswer(query: string, options?: {
        text?: boolean;
        model?: "exa" | "exa-pro";
    }): AsyncGenerator<AnswerStreamChunk>;
    private processChunk;
}

export { AnswerOptions, AnswerResponse, AnswerStreamChunk, AnswerStreamResponse, BaseSearchOptions, ContentsOptions, ContentsResultComponent, CostDollars, CostDollarsContents, CostDollarsSeearch, Default, ExtrasOptions, ExtrasResponse, FindSimilarOptions, HighlightsContentsOptions, HighlightsResponse, JSONSchema, LivecrawlOptions, RegularSearchOptions, SearchResponse, SearchResult, SubpagesResponse, SummaryContentsOptions, SummaryResponse, TextContentsOptions, TextResponse, Exa as default };