exa-js 2.19.0 → 2.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -120,7 +120,7 @@ for await (const chunk of exa.streamAnswer("Explain quantum computing")) {
120
120
  }
121
121
  ```
122
122
 
123
- ## Web Search tools
123
+ ## Web Search and Contents tools
124
124
 
125
125
  Use Exa as a `web_search` tool in an OpenAI or Anthropic loop. Call `webSearch()` with no arguments to get Exa's recommended settings for agentic search (`type: "auto"` and `contents: { highlights: true }`).
126
126
 
@@ -171,6 +171,19 @@ const response = await anthropic.messages.create({
171
171
  });
172
172
  ```
173
173
 
174
+ `getContents()` is available in the same namespaces and lets the model read pages it already has URLs for. It takes a list of URLs and accepts every `exa.getContents` option:
175
+
176
+ ```ts
177
+ const completion = await openai.chat.completions.create({
178
+ model: "gpt-5.6",
179
+ messages,
180
+ tools: [
181
+ exa.openai.webSearch(),
182
+ exa.openai.getContents({ summary: true, livecrawl: "preferred" }),
183
+ ],
184
+ });
185
+ ```
186
+
174
187
  ## Agent API
175
188
 
176
189
  ```ts
package/dist/index.d.mts CHANGED
@@ -3989,16 +3989,38 @@ type WebSearchToolConfig = RegularSearchOptions & {
3989
3989
  /** Tool description shown to the model. */
3990
3990
  description?: string;
3991
3991
  };
3992
+ type GetContentsToolConfig = ContentsOptions & {
3993
+ /**
3994
+ * Tool name shown to the model. Defaults to `"get_contents"`. Set a custom
3995
+ * name to avoid collisions, or to register multiple differently-configured
3996
+ * contents tools.
3997
+ */
3998
+ name?: string;
3999
+ /** Tool description shown to the model. */
4000
+ description?: string;
4001
+ };
3992
4002
  type ToolNamespace = {
3993
4003
  webSearch(config?: WebSearchToolConfig): WebSearchTool;
4004
+ getContents(config?: GetContentsToolConfig): GetContentsTool;
3994
4005
  };
3995
4006
  type SearchArgs = {
3996
4007
  query: string;
3997
4008
  };
4009
+ type GetContentsArgs = {
4010
+ urls: string[];
4011
+ };
3998
4012
  type WebSearchTool = ExaToolSpec<SearchArgs, SearchResponse<ContentsOptions>>;
4013
+ type GetContentsTool = ExaToolSpec<GetContentsArgs, SearchResponse<ContentsOptions>>;
3999
4014
  declare const DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION = "Search the web for up-to-date, relevant information. Describe the ideal page rather than listing keywords.";
4015
+ declare const DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION = "Read the full contents of web pages you already have URLs for, such as pages returned by a search or mentioned by the user.";
4000
4016
  /** Create a `web_search` tool. Defaults to `type: "auto"` and highlights. */
4001
4017
  declare function createWebSearchTool(exa: Exa, registry: ToolRegistry, config?: WebSearchToolConfig): WebSearchTool;
4018
+ /**
4019
+ * Create a `get_contents` tool that reads pages the model already has URLs for.
4020
+ * Inherits `exa.getContents` defaults, which return page text when no content
4021
+ * option is configured.
4022
+ */
4023
+ declare function createGetContentsTool(exa: Exa, registry: ToolRegistry, config?: GetContentsToolConfig): GetContentsTool;
4002
4024
  declare class ToolRegistry {
4003
4025
  private readonly registry;
4004
4026
  register(tool: ExaToolSpec): void;
@@ -4030,6 +4052,8 @@ declare class AnthropicTools {
4030
4052
  constructor(exa: Exa, registry: ToolRegistry);
4031
4053
  /** Anthropic `web_search` tool. Defaults to `auto` + highlights. */
4032
4054
  webSearch(config?: WebSearchToolConfig): AnthropicRunnable;
4055
+ /** Anthropic `get_contents` tool for reading pages by URL. */
4056
+ getContents(config?: GetContentsToolConfig): AnthropicRunnable;
4033
4057
  /**
4034
4058
  * Run the `tool_use` blocks in an assistant message and return the matching
4035
4059
  * `tool_result` blocks. Every `tool_use` block is answered so the follow-up
@@ -4099,6 +4123,8 @@ declare class OpenAIResponsesTools {
4099
4123
  }) => Promise<ResponsesFunctionCallOutput[]>);
4100
4124
  /** Responses API `web_search` tool. Defaults to `auto` + highlights. */
4101
4125
  webSearch(config?: WebSearchToolConfig): OpenAIResponsesRunnable;
4126
+ /** Responses API `get_contents` tool for reading pages by URL. */
4127
+ getContents(config?: GetContentsToolConfig): OpenAIResponsesRunnable;
4102
4128
  /**
4103
4129
  * Run the function calls in a Responses API response (or output item array)
4104
4130
  * and return `function_call_output` items. Every function call is answered
@@ -4118,6 +4144,8 @@ declare class OpenAITools {
4118
4144
  constructor(exa: Exa, registry: ToolRegistry);
4119
4145
  /** Chat Completions `web_search` tool. Defaults to `auto` + highlights. */
4120
4146
  webSearch(config?: WebSearchToolConfig): OpenAIRunnable;
4147
+ /** Chat Completions `get_contents` tool for reading pages by URL. */
4148
+ getContents(config?: GetContentsToolConfig): OpenAIRunnable;
4121
4149
  /**
4122
4150
  * Run the tool calls in a Chat Completions assistant message and return the
4123
4151
  * matching `role: "tool"` messages. Every tool call is answered so the
@@ -4219,6 +4247,8 @@ declare class ExaError extends Error {
4219
4247
  constructor(message: string, statusCode: number, timestamp?: string, path?: string, envelope?: ExaErrorEnvelope);
4220
4248
  }
4221
4249
 
4250
+ /** Exa-Beta token required for Dynamic Highlights (research preview). */
4251
+ declare const DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
4222
4252
  /**
4223
4253
  * Options for retrieving page contents
4224
4254
  * @typedef {Object} ContentsOptions
@@ -4378,6 +4408,14 @@ type NonDeepSearchOptions = BaseRegularSearchOptions & {
4378
4408
  * Uses a discriminated union to ensure additionalQueries is only allowed when type is a deep search variant.
4379
4409
  */
4380
4410
  type RegularSearchOptions = DeepSearchOptions | NonDeepSearchOptions;
4411
+ /**
4412
+ * Options for opting into Exa-Beta features.
4413
+ * @typedef {Object} BetaOptions
4414
+ * @property {string[]} [betas] - Exa-Beta tokens to send with the request (e.g. `[DYNAMIC_HIGHLIGHTS_BETA]` for Dynamic Highlights).
4415
+ */
4416
+ type BetaOptions = {
4417
+ betas?: string[];
4418
+ };
4381
4419
  /**
4382
4420
  * DEPRECATED: Used only by deprecated `findSimilar()` APIs. Use `search()` and `RegularSearchOptions` for new search flows. Will be removed in a future version.
4383
4421
  * @deprecated Use `search()` and `RegularSearchOptions` for new search flows. There is no direct replacement for URL-based similarity.
@@ -4430,13 +4468,15 @@ type TextContentsOptions = {
4430
4468
  * Deep search variants also support these options for returned highlights.
4431
4469
  * @typedef {Object} HighlightsContentsOptions
4432
4470
  * @property {string} [query] - The query string to use for highlights search.
4433
- * @property {number} [maxCharacters] - The maximum number of characters to return for highlights.
4471
+ * @property {number} [maxCharacters] - The maximum number of characters to return for highlights. Not compatible with `dynamic`.
4472
+ * @property {boolean} [dynamic] - Enable Dynamic Highlights (research preview): allocates one shared context budget across all results instead of a per-document budget; the model sizes the output itself. Not compatible with `maxCharacters`. Beta: requires passing `betas: [DYNAMIC_HIGHLIGHTS_BETA]` to the request.
4434
4473
  * @property {number} [numSentences] - DEPRECATED: Use maxCharacters instead.
4435
4474
  * @property {number} [highlightsPerUrl] - DEPRECATED: Use maxCharacters instead.
4436
4475
  */
4437
4476
  type HighlightsContentsOptions = {
4438
4477
  query?: string;
4439
4478
  maxCharacters?: number;
4479
+ dynamic?: boolean;
4440
4480
  /**
4441
4481
  * DEPRECATED: Use `maxCharacters` instead. Will be removed in a future version.
4442
4482
  * @deprecated Use `maxCharacters` instead. This legacy sizing field will be removed in a future version.
@@ -4861,7 +4901,7 @@ declare class Exa {
4861
4901
  * @param {RegularSearchOptions & { contents: false }} options - Search options with contents explicitly disabled
4862
4902
  * @returns {Promise<SearchResponse<{}>>} A list of relevant search results without contents.
4863
4903
  */
4864
- search(query: string, options: RegularSearchOptions & {
4904
+ search(query: string, options: RegularSearchOptions & BetaOptions & {
4865
4905
  contents: false | null | undefined;
4866
4906
  }): Promise<SearchResponse<{}>>;
4867
4907
  /**
@@ -4871,7 +4911,7 @@ declare class Exa {
4871
4911
  * @param {RegularSearchOptions & { contents: T }} options - Search options with specific contents
4872
4912
  * @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
4873
4913
  */
4874
- search<T extends ContentsOptions>(query: string, options: RegularSearchOptions & {
4914
+ search<T extends ContentsOptions>(query: string, options: RegularSearchOptions & BetaOptions & {
4875
4915
  contents: T;
4876
4916
  }): Promise<SearchResponse<T>>;
4877
4917
  /**
@@ -4882,7 +4922,7 @@ declare class Exa {
4882
4922
  * @param {Omit<DeepSearchOptions, 'contents'> | Omit<NonDeepSearchOptions, 'contents'>} options - Search options without contents
4883
4923
  * @returns {Promise<SearchResponse<{ text: true }>>} A list of relevant search results with text contents.
4884
4924
  */
4885
- search(query: string, options: Omit<DeepSearchOptions, "contents"> | Omit<NonDeepSearchOptions, "contents">): Promise<SearchResponse<{
4925
+ search(query: string, options: (Omit<DeepSearchOptions, "contents"> | Omit<NonDeepSearchOptions, "contents">) & BetaOptions): Promise<SearchResponse<{
4886
4926
  text: true;
4887
4927
  }>>;
4888
4928
  /**
@@ -4986,7 +5026,7 @@ declare class Exa {
4986
5026
  * @param {ContentsOptions} [options] - Additional options for retrieving document contents.
4987
5027
  * @returns {Promise<SearchResponse<T>>} A list of document contents for the requested URLs.
4988
5028
  */
4989
- getContents<T extends ContentsOptions>(urls: string | string[] | SearchResult<T>[], options?: T): Promise<SearchResponse<T>>;
5029
+ getContents<T extends ContentsOptions>(urls: string | string[] | SearchResult<T>[], options?: T & BetaOptions): Promise<SearchResponse<T>>;
4990
5030
  /**
4991
5031
  * Generate an answer with Zod schema for strongly typed output
4992
5032
  */
@@ -5056,4 +5096,4 @@ declare class Exa {
5056
5096
  private parseSSEStream;
5057
5097
  }
5058
5098
 
5059
- export { AGENT_BETA_HEADER, AGENT_MAX_EFFORT_BETA, AGENT_MONITORS_BETA_HEADER, type AddAgentMonitorEntitiesParams, AgentBetaClient, type AgentBetaOptions, type AgentBudget, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentDataSource, type AgentDataSourceProvider, type AgentEffort, type AgentError, type AgentEvent, type AgentGroundingCitation, type AgentGroundingEntry, type AgentInput, type AgentMonitor, type AgentMonitorChange, type AgentMonitorChangeEntity, type AgentMonitorChangeField, AgentMonitorChangesClient, type AgentMonitorCitation, type AgentMonitorContent, type AgentMonitorCreation, AgentMonitorEntitiesClient, type AgentMonitorEntity, type AgentMonitorEntityView, type AgentMonitorField, type AgentMonitorFieldMode, type AgentMonitorFieldValueType, type AgentMonitorRefresh, type AgentMonitorSnapshot, type AgentMonitorSnapshotEntity, AgentMonitorSnapshotFailedError, type AgentMonitorSnapshotResult, type AgentMonitorSnapshotStatus, type AgentMonitorSnapshotWaitOptions, AgentMonitorSnapshotsClient, type AgentMonitorStatus, type AgentMonitorUsage, type AgentMonitorsBetaOptions, AgentMonitorsClient, type AgentOutput, type AgentRun, AgentRunCancelledError, AgentRunEventsClient, AgentRunFailedError, type AgentRunStatus, type AgentRunTyped, AgentRunsClient, type AgentStopReason, type AgentUsage, type AgentWaitOptions, type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type AnthropicToolResult, AnthropicTools, type ArticleEntity, type BaseSearchOptions, BetaClient, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateAgentMonitorEntityParams, type CreateAgentMonitorFieldParams, type CreateAgentMonitorOptions, type CreateAgentMonitorParams, type CreateAgentMonitorSnapshotParams, type CreateAgentRunParams, type CreateAgentRunParamsTyped, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateSearchMonitorParams, type CreateSearchMonitorResponse, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, type DeletedAgentMonitor, type DeletedAgentRun, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExaErrorEnvelope, type ExaToolSpec, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type GroundingCitation, type GroundingEntry, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListAgentMonitorChangesParams, type ListAgentMonitorChangesResponse, type ListAgentMonitorEntitiesParams, type ListAgentMonitorEntitiesResponse, type ListAgentMonitorsParams, type ListAgentMonitorsResponse, type ListAgentRunEventsParams, type ListAgentRunEventsResponse, type ListAgentRunsParams, type ListAgentRunsResponse, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type ListSearchMonitorRunsParams, type ListSearchMonitorRunsResponse, type ListSearchMonitorsParams, type ListSearchMonitorsResponse, type ListWebhookAttemptsResponse, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetItemsOptions, type ListWebsetsResponse, type LivecrawlOptions, type Monitor, type MonitorBehavior, type MonitorCadence, MonitorObject, type MonitorRun, MonitorRunObject, MonitorRunStatus, MonitorRunType, MonitorStatus, OpenAIResponsesTools, type OpenAIToolMessage, OpenAITools, type PersonEntity, type PreviewWebsetParameters, type PreviewWebsetResponse, type RegularSearchOptions, type Research, type ResearchCreateParamsTyped, type ResearchCreateRequest, type ResearchCreateResponse, type ResearchDefinitionEvent, type ResearchEvent, type ResearchOperation, type ResearchOutputEvent, type ResearchPaperEntity, type ResearchPlanDefinitionEvent, type ResearchPlanOperationEvent, type ResearchPlanOutputEvent, type ResearchStatus, type ResearchStreamEvent, type ResearchStreamEventTyped, type ResearchTaskDefinitionEvent, type ResearchTaskOperationEvent, type ResearchTaskOutputEvent, type ResearchTyped, type ResponsesFunctionCallOutput, type SearchMonitor, type SearchMonitorRun, type SearchMonitorRunFailReason, type SearchMonitorRunOutput, type SearchMonitorRunStatus, SearchMonitorRunsClient, type SearchMonitorSearch, type SearchMonitorStatus, type SearchMonitorTrigger, type SearchMonitorWebhook, type SearchMonitorWebhookEvent, SearchMonitorsClient, type SearchResponse, type SearchResult, type SearchStreamChunk, type SectionTag, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type ToolDefinition, type ToolJsonSchema, type ToolNamespace, ToolRegistry, type TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type VerbosityOptions, type WaitUntilCompletedOptions, type WebSearchTool, type WebSearchToolConfig, type Webhook, type WebhookAttempt, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, WebsetExcludeSource, type WebsetHeadersLike, WebsetImportSource, type WebsetItem, type WebsetItemArticleProperties, type WebsetItemCompanyProperties, type WebsetItemCustomProperties, type WebsetItemEvaluation, WebsetItemEvaluationSatisfied, type WebsetItemPersonProperties, type WebsetItemResearchPaperProperties, WebsetItemSource, WebsetItemsClient, WebsetMonitorsClient, type WebsetSearch, WebsetSearchBehavior, WebsetSearchCanceledReason, WebsetSearchScopeSource, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, createWebSearchTool, Exa as default };
5099
+ export { AGENT_BETA_HEADER, AGENT_MAX_EFFORT_BETA, AGENT_MONITORS_BETA_HEADER, type AddAgentMonitorEntitiesParams, AgentBetaClient, type AgentBetaOptions, type AgentBudget, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentDataSource, type AgentDataSourceProvider, type AgentEffort, type AgentError, type AgentEvent, type AgentGroundingCitation, type AgentGroundingEntry, type AgentInput, type AgentMonitor, type AgentMonitorChange, type AgentMonitorChangeEntity, type AgentMonitorChangeField, AgentMonitorChangesClient, type AgentMonitorCitation, type AgentMonitorContent, type AgentMonitorCreation, AgentMonitorEntitiesClient, type AgentMonitorEntity, type AgentMonitorEntityView, type AgentMonitorField, type AgentMonitorFieldMode, type AgentMonitorFieldValueType, type AgentMonitorRefresh, type AgentMonitorSnapshot, type AgentMonitorSnapshotEntity, AgentMonitorSnapshotFailedError, type AgentMonitorSnapshotResult, type AgentMonitorSnapshotStatus, type AgentMonitorSnapshotWaitOptions, AgentMonitorSnapshotsClient, type AgentMonitorStatus, type AgentMonitorUsage, type AgentMonitorsBetaOptions, AgentMonitorsClient, type AgentOutput, type AgentRun, AgentRunCancelledError, AgentRunEventsClient, AgentRunFailedError, type AgentRunStatus, type AgentRunTyped, AgentRunsClient, type AgentStopReason, type AgentUsage, type AgentWaitOptions, type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type AnthropicToolResult, AnthropicTools, type ArticleEntity, type BaseSearchOptions, BetaClient, type BetaOptions, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateAgentMonitorEntityParams, type CreateAgentMonitorFieldParams, type CreateAgentMonitorOptions, type CreateAgentMonitorParams, type CreateAgentMonitorSnapshotParams, type CreateAgentRunParams, type CreateAgentRunParamsTyped, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateSearchMonitorParams, type CreateSearchMonitorResponse, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION, DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION, DYNAMIC_HIGHLIGHTS_BETA, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, type DeletedAgentMonitor, type DeletedAgentRun, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExaErrorEnvelope, type ExaToolSpec, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetContentsTool, type GetContentsToolConfig, type GetWebsetResponse, type GroundingCitation, type GroundingEntry, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListAgentMonitorChangesParams, type ListAgentMonitorChangesResponse, type ListAgentMonitorEntitiesParams, type ListAgentMonitorEntitiesResponse, type ListAgentMonitorsParams, type ListAgentMonitorsResponse, type ListAgentRunEventsParams, type ListAgentRunEventsResponse, type ListAgentRunsParams, type ListAgentRunsResponse, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type ListSearchMonitorRunsParams, type ListSearchMonitorRunsResponse, type ListSearchMonitorsParams, type ListSearchMonitorsResponse, type ListWebhookAttemptsResponse, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetItemsOptions, type ListWebsetsResponse, type LivecrawlOptions, type Monitor, type MonitorBehavior, type MonitorCadence, MonitorObject, type MonitorRun, MonitorRunObject, MonitorRunStatus, MonitorRunType, MonitorStatus, OpenAIResponsesTools, type OpenAIToolMessage, OpenAITools, type PersonEntity, type PreviewWebsetParameters, type PreviewWebsetResponse, type RegularSearchOptions, type Research, type ResearchCreateParamsTyped, type ResearchCreateRequest, type ResearchCreateResponse, type ResearchDefinitionEvent, type ResearchEvent, type ResearchOperation, type ResearchOutputEvent, type ResearchPaperEntity, type ResearchPlanDefinitionEvent, type ResearchPlanOperationEvent, type ResearchPlanOutputEvent, type ResearchStatus, type ResearchStreamEvent, type ResearchStreamEventTyped, type ResearchTaskDefinitionEvent, type ResearchTaskOperationEvent, type ResearchTaskOutputEvent, type ResearchTyped, type ResponsesFunctionCallOutput, type SearchMonitor, type SearchMonitorRun, type SearchMonitorRunFailReason, type SearchMonitorRunOutput, type SearchMonitorRunStatus, SearchMonitorRunsClient, type SearchMonitorSearch, type SearchMonitorStatus, type SearchMonitorTrigger, type SearchMonitorWebhook, type SearchMonitorWebhookEvent, SearchMonitorsClient, type SearchResponse, type SearchResult, type SearchStreamChunk, type SectionTag, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type ToolDefinition, type ToolJsonSchema, type ToolNamespace, ToolRegistry, type TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type VerbosityOptions, type WaitUntilCompletedOptions, type WebSearchTool, type WebSearchToolConfig, type Webhook, type WebhookAttempt, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, WebsetExcludeSource, type WebsetHeadersLike, WebsetImportSource, type WebsetItem, type WebsetItemArticleProperties, type WebsetItemCompanyProperties, type WebsetItemCustomProperties, type WebsetItemEvaluation, WebsetItemEvaluationSatisfied, type WebsetItemPersonProperties, type WebsetItemResearchPaperProperties, WebsetItemSource, WebsetItemsClient, WebsetMonitorsClient, type WebsetSearch, WebsetSearchBehavior, WebsetSearchCanceledReason, WebsetSearchScopeSource, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, createGetContentsTool, createWebSearchTool, Exa as default };
package/dist/index.d.ts CHANGED
@@ -3989,16 +3989,38 @@ type WebSearchToolConfig = RegularSearchOptions & {
3989
3989
  /** Tool description shown to the model. */
3990
3990
  description?: string;
3991
3991
  };
3992
+ type GetContentsToolConfig = ContentsOptions & {
3993
+ /**
3994
+ * Tool name shown to the model. Defaults to `"get_contents"`. Set a custom
3995
+ * name to avoid collisions, or to register multiple differently-configured
3996
+ * contents tools.
3997
+ */
3998
+ name?: string;
3999
+ /** Tool description shown to the model. */
4000
+ description?: string;
4001
+ };
3992
4002
  type ToolNamespace = {
3993
4003
  webSearch(config?: WebSearchToolConfig): WebSearchTool;
4004
+ getContents(config?: GetContentsToolConfig): GetContentsTool;
3994
4005
  };
3995
4006
  type SearchArgs = {
3996
4007
  query: string;
3997
4008
  };
4009
+ type GetContentsArgs = {
4010
+ urls: string[];
4011
+ };
3998
4012
  type WebSearchTool = ExaToolSpec<SearchArgs, SearchResponse<ContentsOptions>>;
4013
+ type GetContentsTool = ExaToolSpec<GetContentsArgs, SearchResponse<ContentsOptions>>;
3999
4014
  declare const DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION = "Search the web for up-to-date, relevant information. Describe the ideal page rather than listing keywords.";
4015
+ declare const DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION = "Read the full contents of web pages you already have URLs for, such as pages returned by a search or mentioned by the user.";
4000
4016
  /** Create a `web_search` tool. Defaults to `type: "auto"` and highlights. */
4001
4017
  declare function createWebSearchTool(exa: Exa, registry: ToolRegistry, config?: WebSearchToolConfig): WebSearchTool;
4018
+ /**
4019
+ * Create a `get_contents` tool that reads pages the model already has URLs for.
4020
+ * Inherits `exa.getContents` defaults, which return page text when no content
4021
+ * option is configured.
4022
+ */
4023
+ declare function createGetContentsTool(exa: Exa, registry: ToolRegistry, config?: GetContentsToolConfig): GetContentsTool;
4002
4024
  declare class ToolRegistry {
4003
4025
  private readonly registry;
4004
4026
  register(tool: ExaToolSpec): void;
@@ -4030,6 +4052,8 @@ declare class AnthropicTools {
4030
4052
  constructor(exa: Exa, registry: ToolRegistry);
4031
4053
  /** Anthropic `web_search` tool. Defaults to `auto` + highlights. */
4032
4054
  webSearch(config?: WebSearchToolConfig): AnthropicRunnable;
4055
+ /** Anthropic `get_contents` tool for reading pages by URL. */
4056
+ getContents(config?: GetContentsToolConfig): AnthropicRunnable;
4033
4057
  /**
4034
4058
  * Run the `tool_use` blocks in an assistant message and return the matching
4035
4059
  * `tool_result` blocks. Every `tool_use` block is answered so the follow-up
@@ -4099,6 +4123,8 @@ declare class OpenAIResponsesTools {
4099
4123
  }) => Promise<ResponsesFunctionCallOutput[]>);
4100
4124
  /** Responses API `web_search` tool. Defaults to `auto` + highlights. */
4101
4125
  webSearch(config?: WebSearchToolConfig): OpenAIResponsesRunnable;
4126
+ /** Responses API `get_contents` tool for reading pages by URL. */
4127
+ getContents(config?: GetContentsToolConfig): OpenAIResponsesRunnable;
4102
4128
  /**
4103
4129
  * Run the function calls in a Responses API response (or output item array)
4104
4130
  * and return `function_call_output` items. Every function call is answered
@@ -4118,6 +4144,8 @@ declare class OpenAITools {
4118
4144
  constructor(exa: Exa, registry: ToolRegistry);
4119
4145
  /** Chat Completions `web_search` tool. Defaults to `auto` + highlights. */
4120
4146
  webSearch(config?: WebSearchToolConfig): OpenAIRunnable;
4147
+ /** Chat Completions `get_contents` tool for reading pages by URL. */
4148
+ getContents(config?: GetContentsToolConfig): OpenAIRunnable;
4121
4149
  /**
4122
4150
  * Run the tool calls in a Chat Completions assistant message and return the
4123
4151
  * matching `role: "tool"` messages. Every tool call is answered so the
@@ -4219,6 +4247,8 @@ declare class ExaError extends Error {
4219
4247
  constructor(message: string, statusCode: number, timestamp?: string, path?: string, envelope?: ExaErrorEnvelope);
4220
4248
  }
4221
4249
 
4250
+ /** Exa-Beta token required for Dynamic Highlights (research preview). */
4251
+ declare const DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
4222
4252
  /**
4223
4253
  * Options for retrieving page contents
4224
4254
  * @typedef {Object} ContentsOptions
@@ -4378,6 +4408,14 @@ type NonDeepSearchOptions = BaseRegularSearchOptions & {
4378
4408
  * Uses a discriminated union to ensure additionalQueries is only allowed when type is a deep search variant.
4379
4409
  */
4380
4410
  type RegularSearchOptions = DeepSearchOptions | NonDeepSearchOptions;
4411
+ /**
4412
+ * Options for opting into Exa-Beta features.
4413
+ * @typedef {Object} BetaOptions
4414
+ * @property {string[]} [betas] - Exa-Beta tokens to send with the request (e.g. `[DYNAMIC_HIGHLIGHTS_BETA]` for Dynamic Highlights).
4415
+ */
4416
+ type BetaOptions = {
4417
+ betas?: string[];
4418
+ };
4381
4419
  /**
4382
4420
  * DEPRECATED: Used only by deprecated `findSimilar()` APIs. Use `search()` and `RegularSearchOptions` for new search flows. Will be removed in a future version.
4383
4421
  * @deprecated Use `search()` and `RegularSearchOptions` for new search flows. There is no direct replacement for URL-based similarity.
@@ -4430,13 +4468,15 @@ type TextContentsOptions = {
4430
4468
  * Deep search variants also support these options for returned highlights.
4431
4469
  * @typedef {Object} HighlightsContentsOptions
4432
4470
  * @property {string} [query] - The query string to use for highlights search.
4433
- * @property {number} [maxCharacters] - The maximum number of characters to return for highlights.
4471
+ * @property {number} [maxCharacters] - The maximum number of characters to return for highlights. Not compatible with `dynamic`.
4472
+ * @property {boolean} [dynamic] - Enable Dynamic Highlights (research preview): allocates one shared context budget across all results instead of a per-document budget; the model sizes the output itself. Not compatible with `maxCharacters`. Beta: requires passing `betas: [DYNAMIC_HIGHLIGHTS_BETA]` to the request.
4434
4473
  * @property {number} [numSentences] - DEPRECATED: Use maxCharacters instead.
4435
4474
  * @property {number} [highlightsPerUrl] - DEPRECATED: Use maxCharacters instead.
4436
4475
  */
4437
4476
  type HighlightsContentsOptions = {
4438
4477
  query?: string;
4439
4478
  maxCharacters?: number;
4479
+ dynamic?: boolean;
4440
4480
  /**
4441
4481
  * DEPRECATED: Use `maxCharacters` instead. Will be removed in a future version.
4442
4482
  * @deprecated Use `maxCharacters` instead. This legacy sizing field will be removed in a future version.
@@ -4861,7 +4901,7 @@ declare class Exa {
4861
4901
  * @param {RegularSearchOptions & { contents: false }} options - Search options with contents explicitly disabled
4862
4902
  * @returns {Promise<SearchResponse<{}>>} A list of relevant search results without contents.
4863
4903
  */
4864
- search(query: string, options: RegularSearchOptions & {
4904
+ search(query: string, options: RegularSearchOptions & BetaOptions & {
4865
4905
  contents: false | null | undefined;
4866
4906
  }): Promise<SearchResponse<{}>>;
4867
4907
  /**
@@ -4871,7 +4911,7 @@ declare class Exa {
4871
4911
  * @param {RegularSearchOptions & { contents: T }} options - Search options with specific contents
4872
4912
  * @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
4873
4913
  */
4874
- search<T extends ContentsOptions>(query: string, options: RegularSearchOptions & {
4914
+ search<T extends ContentsOptions>(query: string, options: RegularSearchOptions & BetaOptions & {
4875
4915
  contents: T;
4876
4916
  }): Promise<SearchResponse<T>>;
4877
4917
  /**
@@ -4882,7 +4922,7 @@ declare class Exa {
4882
4922
  * @param {Omit<DeepSearchOptions, 'contents'> | Omit<NonDeepSearchOptions, 'contents'>} options - Search options without contents
4883
4923
  * @returns {Promise<SearchResponse<{ text: true }>>} A list of relevant search results with text contents.
4884
4924
  */
4885
- search(query: string, options: Omit<DeepSearchOptions, "contents"> | Omit<NonDeepSearchOptions, "contents">): Promise<SearchResponse<{
4925
+ search(query: string, options: (Omit<DeepSearchOptions, "contents"> | Omit<NonDeepSearchOptions, "contents">) & BetaOptions): Promise<SearchResponse<{
4886
4926
  text: true;
4887
4927
  }>>;
4888
4928
  /**
@@ -4986,7 +5026,7 @@ declare class Exa {
4986
5026
  * @param {ContentsOptions} [options] - Additional options for retrieving document contents.
4987
5027
  * @returns {Promise<SearchResponse<T>>} A list of document contents for the requested URLs.
4988
5028
  */
4989
- getContents<T extends ContentsOptions>(urls: string | string[] | SearchResult<T>[], options?: T): Promise<SearchResponse<T>>;
5029
+ getContents<T extends ContentsOptions>(urls: string | string[] | SearchResult<T>[], options?: T & BetaOptions): Promise<SearchResponse<T>>;
4990
5030
  /**
4991
5031
  * Generate an answer with Zod schema for strongly typed output
4992
5032
  */
@@ -5056,4 +5096,4 @@ declare class Exa {
5056
5096
  private parseSSEStream;
5057
5097
  }
5058
5098
 
5059
- export { AGENT_BETA_HEADER, AGENT_MAX_EFFORT_BETA, AGENT_MONITORS_BETA_HEADER, type AddAgentMonitorEntitiesParams, AgentBetaClient, type AgentBetaOptions, type AgentBudget, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentDataSource, type AgentDataSourceProvider, type AgentEffort, type AgentError, type AgentEvent, type AgentGroundingCitation, type AgentGroundingEntry, type AgentInput, type AgentMonitor, type AgentMonitorChange, type AgentMonitorChangeEntity, type AgentMonitorChangeField, AgentMonitorChangesClient, type AgentMonitorCitation, type AgentMonitorContent, type AgentMonitorCreation, AgentMonitorEntitiesClient, type AgentMonitorEntity, type AgentMonitorEntityView, type AgentMonitorField, type AgentMonitorFieldMode, type AgentMonitorFieldValueType, type AgentMonitorRefresh, type AgentMonitorSnapshot, type AgentMonitorSnapshotEntity, AgentMonitorSnapshotFailedError, type AgentMonitorSnapshotResult, type AgentMonitorSnapshotStatus, type AgentMonitorSnapshotWaitOptions, AgentMonitorSnapshotsClient, type AgentMonitorStatus, type AgentMonitorUsage, type AgentMonitorsBetaOptions, AgentMonitorsClient, type AgentOutput, type AgentRun, AgentRunCancelledError, AgentRunEventsClient, AgentRunFailedError, type AgentRunStatus, type AgentRunTyped, AgentRunsClient, type AgentStopReason, type AgentUsage, type AgentWaitOptions, type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type AnthropicToolResult, AnthropicTools, type ArticleEntity, type BaseSearchOptions, BetaClient, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateAgentMonitorEntityParams, type CreateAgentMonitorFieldParams, type CreateAgentMonitorOptions, type CreateAgentMonitorParams, type CreateAgentMonitorSnapshotParams, type CreateAgentRunParams, type CreateAgentRunParamsTyped, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateSearchMonitorParams, type CreateSearchMonitorResponse, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, type DeletedAgentMonitor, type DeletedAgentRun, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExaErrorEnvelope, type ExaToolSpec, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type GroundingCitation, type GroundingEntry, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListAgentMonitorChangesParams, type ListAgentMonitorChangesResponse, type ListAgentMonitorEntitiesParams, type ListAgentMonitorEntitiesResponse, type ListAgentMonitorsParams, type ListAgentMonitorsResponse, type ListAgentRunEventsParams, type ListAgentRunEventsResponse, type ListAgentRunsParams, type ListAgentRunsResponse, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type ListSearchMonitorRunsParams, type ListSearchMonitorRunsResponse, type ListSearchMonitorsParams, type ListSearchMonitorsResponse, type ListWebhookAttemptsResponse, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetItemsOptions, type ListWebsetsResponse, type LivecrawlOptions, type Monitor, type MonitorBehavior, type MonitorCadence, MonitorObject, type MonitorRun, MonitorRunObject, MonitorRunStatus, MonitorRunType, MonitorStatus, OpenAIResponsesTools, type OpenAIToolMessage, OpenAITools, type PersonEntity, type PreviewWebsetParameters, type PreviewWebsetResponse, type RegularSearchOptions, type Research, type ResearchCreateParamsTyped, type ResearchCreateRequest, type ResearchCreateResponse, type ResearchDefinitionEvent, type ResearchEvent, type ResearchOperation, type ResearchOutputEvent, type ResearchPaperEntity, type ResearchPlanDefinitionEvent, type ResearchPlanOperationEvent, type ResearchPlanOutputEvent, type ResearchStatus, type ResearchStreamEvent, type ResearchStreamEventTyped, type ResearchTaskDefinitionEvent, type ResearchTaskOperationEvent, type ResearchTaskOutputEvent, type ResearchTyped, type ResponsesFunctionCallOutput, type SearchMonitor, type SearchMonitorRun, type SearchMonitorRunFailReason, type SearchMonitorRunOutput, type SearchMonitorRunStatus, SearchMonitorRunsClient, type SearchMonitorSearch, type SearchMonitorStatus, type SearchMonitorTrigger, type SearchMonitorWebhook, type SearchMonitorWebhookEvent, SearchMonitorsClient, type SearchResponse, type SearchResult, type SearchStreamChunk, type SectionTag, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type ToolDefinition, type ToolJsonSchema, type ToolNamespace, ToolRegistry, type TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type VerbosityOptions, type WaitUntilCompletedOptions, type WebSearchTool, type WebSearchToolConfig, type Webhook, type WebhookAttempt, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, WebsetExcludeSource, type WebsetHeadersLike, WebsetImportSource, type WebsetItem, type WebsetItemArticleProperties, type WebsetItemCompanyProperties, type WebsetItemCustomProperties, type WebsetItemEvaluation, WebsetItemEvaluationSatisfied, type WebsetItemPersonProperties, type WebsetItemResearchPaperProperties, WebsetItemSource, WebsetItemsClient, WebsetMonitorsClient, type WebsetSearch, WebsetSearchBehavior, WebsetSearchCanceledReason, WebsetSearchScopeSource, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, createWebSearchTool, Exa as default };
5099
+ export { AGENT_BETA_HEADER, AGENT_MAX_EFFORT_BETA, AGENT_MONITORS_BETA_HEADER, type AddAgentMonitorEntitiesParams, AgentBetaClient, type AgentBetaOptions, type AgentBudget, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentDataSource, type AgentDataSourceProvider, type AgentEffort, type AgentError, type AgentEvent, type AgentGroundingCitation, type AgentGroundingEntry, type AgentInput, type AgentMonitor, type AgentMonitorChange, type AgentMonitorChangeEntity, type AgentMonitorChangeField, AgentMonitorChangesClient, type AgentMonitorCitation, type AgentMonitorContent, type AgentMonitorCreation, AgentMonitorEntitiesClient, type AgentMonitorEntity, type AgentMonitorEntityView, type AgentMonitorField, type AgentMonitorFieldMode, type AgentMonitorFieldValueType, type AgentMonitorRefresh, type AgentMonitorSnapshot, type AgentMonitorSnapshotEntity, AgentMonitorSnapshotFailedError, type AgentMonitorSnapshotResult, type AgentMonitorSnapshotStatus, type AgentMonitorSnapshotWaitOptions, AgentMonitorSnapshotsClient, type AgentMonitorStatus, type AgentMonitorUsage, type AgentMonitorsBetaOptions, AgentMonitorsClient, type AgentOutput, type AgentRun, AgentRunCancelledError, AgentRunEventsClient, AgentRunFailedError, type AgentRunStatus, type AgentRunTyped, AgentRunsClient, type AgentStopReason, type AgentUsage, type AgentWaitOptions, type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type AnthropicToolResult, AnthropicTools, type ArticleEntity, type BaseSearchOptions, BetaClient, type BetaOptions, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateAgentMonitorEntityParams, type CreateAgentMonitorFieldParams, type CreateAgentMonitorOptions, type CreateAgentMonitorParams, type CreateAgentMonitorSnapshotParams, type CreateAgentRunParams, type CreateAgentRunParamsTyped, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateSearchMonitorParams, type CreateSearchMonitorResponse, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION, DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION, DYNAMIC_HIGHLIGHTS_BETA, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, type DeletedAgentMonitor, type DeletedAgentRun, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExaErrorEnvelope, type ExaToolSpec, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetContentsTool, type GetContentsToolConfig, type GetWebsetResponse, type GroundingCitation, type GroundingEntry, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListAgentMonitorChangesParams, type ListAgentMonitorChangesResponse, type ListAgentMonitorEntitiesParams, type ListAgentMonitorEntitiesResponse, type ListAgentMonitorsParams, type ListAgentMonitorsResponse, type ListAgentRunEventsParams, type ListAgentRunEventsResponse, type ListAgentRunsParams, type ListAgentRunsResponse, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type ListSearchMonitorRunsParams, type ListSearchMonitorRunsResponse, type ListSearchMonitorsParams, type ListSearchMonitorsResponse, type ListWebhookAttemptsResponse, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetItemsOptions, type ListWebsetsResponse, type LivecrawlOptions, type Monitor, type MonitorBehavior, type MonitorCadence, MonitorObject, type MonitorRun, MonitorRunObject, MonitorRunStatus, MonitorRunType, MonitorStatus, OpenAIResponsesTools, type OpenAIToolMessage, OpenAITools, type PersonEntity, type PreviewWebsetParameters, type PreviewWebsetResponse, type RegularSearchOptions, type Research, type ResearchCreateParamsTyped, type ResearchCreateRequest, type ResearchCreateResponse, type ResearchDefinitionEvent, type ResearchEvent, type ResearchOperation, type ResearchOutputEvent, type ResearchPaperEntity, type ResearchPlanDefinitionEvent, type ResearchPlanOperationEvent, type ResearchPlanOutputEvent, type ResearchStatus, type ResearchStreamEvent, type ResearchStreamEventTyped, type ResearchTaskDefinitionEvent, type ResearchTaskOperationEvent, type ResearchTaskOutputEvent, type ResearchTyped, type ResponsesFunctionCallOutput, type SearchMonitor, type SearchMonitorRun, type SearchMonitorRunFailReason, type SearchMonitorRunOutput, type SearchMonitorRunStatus, SearchMonitorRunsClient, type SearchMonitorSearch, type SearchMonitorStatus, type SearchMonitorTrigger, type SearchMonitorWebhook, type SearchMonitorWebhookEvent, SearchMonitorsClient, type SearchResponse, type SearchResult, type SearchStreamChunk, type SectionTag, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type ToolDefinition, type ToolJsonSchema, type ToolNamespace, ToolRegistry, type TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type VerbosityOptions, type WaitUntilCompletedOptions, type WebSearchTool, type WebSearchToolConfig, type Webhook, type WebhookAttempt, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, WebsetExcludeSource, type WebsetHeadersLike, WebsetImportSource, type WebsetItem, type WebsetItemArticleProperties, type WebsetItemCompanyProperties, type WebsetItemCustomProperties, type WebsetItemEvaluation, WebsetItemEvaluationSatisfied, type WebsetItemPersonProperties, type WebsetItemResearchPaperProperties, WebsetItemSource, WebsetItemsClient, WebsetMonitorsClient, type WebsetSearch, WebsetSearchBehavior, WebsetSearchCanceledReason, WebsetSearchScopeSource, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, createGetContentsTool, createWebSearchTool, Exa as default };
package/dist/index.js CHANGED
@@ -48,7 +48,9 @@ __export(index_exports, {
48
48
  BetaClient: () => BetaClient,
49
49
  CreateEnrichmentParametersFormat: () => CreateEnrichmentParametersFormat,
50
50
  CreateImportParametersFormat: () => CreateImportParametersFormat,
51
+ DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION: () => DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION,
51
52
  DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION: () => DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION,
53
+ DYNAMIC_HIGHLIGHTS_BETA: () => DYNAMIC_HIGHLIGHTS_BETA,
52
54
  EventType: () => EventType,
53
55
  EventsClient: () => EventsClient,
54
56
  Exa: () => Exa2,
@@ -88,6 +90,7 @@ __export(index_exports, {
88
90
  WebsetStatus: () => WebsetStatus,
89
91
  WebsetWebhooksClient: () => WebsetWebhooksClient,
90
92
  WebsetsClient: () => WebsetsClient,
93
+ createGetContentsTool: () => createGetContentsTool,
91
94
  createWebSearchTool: () => createWebSearchTool,
92
95
  default: () => index_default
93
96
  });
@@ -97,7 +100,7 @@ var import_cross_fetch = __toESM(require("cross-fetch"));
97
100
  // package.json
98
101
  var package_default = {
99
102
  name: "exa-js",
100
- version: "2.19.0",
103
+ version: "2.21.0",
101
104
  description: "Exa SDK for Node.js and the browser",
102
105
  publishConfig: {
103
106
  access: "public"
@@ -2414,7 +2417,8 @@ var WebsetsClient = class extends WebsetsBaseClient {
2414
2417
  // src/tools/core.ts
2415
2418
  var import_zod2 = require("zod");
2416
2419
  var DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION = "Search the web for up-to-date, relevant information. Describe the ideal page rather than listing keywords.";
2417
- function formatSearchResponse(response) {
2420
+ var DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION = "Read the full contents of web pages you already have URLs for, such as pages returned by a search or mentioned by the user.";
2421
+ function formatResults(response, emptyMessage) {
2418
2422
  const formatted = response.results.map((result) => {
2419
2423
  const lines = [
2420
2424
  `Title: ${result.title || "N/A"}`,
@@ -2422,6 +2426,9 @@ function formatSearchResponse(response) {
2422
2426
  `Published: ${result.publishedDate || "N/A"}`,
2423
2427
  `Author: ${result.author || "N/A"}`
2424
2428
  ];
2429
+ if (result.summary) {
2430
+ lines.push(`Summary: ${result.summary}`);
2431
+ }
2425
2432
  if (result.highlights && result.highlights.length > 0) {
2426
2433
  lines.push(`Highlights:
2427
2434
  ${result.highlights.join("\n")}`);
@@ -2430,7 +2437,13 @@ ${result.highlights.join("\n")}`);
2430
2437
  }
2431
2438
  return lines.join("\n");
2432
2439
  }).join("\n\n---\n\n");
2433
- return formatted || "No search results found.";
2440
+ return formatted || emptyMessage;
2441
+ }
2442
+ function formatSearchResponse(response) {
2443
+ return formatResults(response, "No search results found.");
2444
+ }
2445
+ function formatContentsResponse(response) {
2446
+ return formatResults(response, "No contents found.");
2434
2447
  }
2435
2448
  function registerTool(registry, tool) {
2436
2449
  registry.register(tool);
@@ -2493,6 +2506,33 @@ function createWebSearchTool(exa, registry, config = {}) {
2493
2506
  format: formatSearchResponse
2494
2507
  });
2495
2508
  }
2509
+ function createGetContentsTool(exa, registry, config = {}) {
2510
+ const {
2511
+ name = "get_contents",
2512
+ description = DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION,
2513
+ ...contentsOptions
2514
+ } = config;
2515
+ const inputSchema = import_zod2.z.object({
2516
+ urls: import_zod2.z.array(import_zod2.z.string()).describe(
2517
+ "Absolute URLs of the pages to read, including the scheme. Pass several URLs to read them in a single call."
2518
+ )
2519
+ });
2520
+ const jsonSchema = zodToJsonSchema(inputSchema);
2521
+ delete jsonSchema.$schema;
2522
+ return createTool(registry, {
2523
+ name,
2524
+ description,
2525
+ inputSchema,
2526
+ jsonSchema,
2527
+ definition: {
2528
+ name,
2529
+ description,
2530
+ parameters: jsonSchema
2531
+ },
2532
+ execute: ({ urls }) => exa.getContents(urls, contentsOptions),
2533
+ format: formatContentsResponse
2534
+ });
2535
+ }
2496
2536
  var ToolRegistry = class {
2497
2537
  constructor() {
2498
2538
  this.registry = /* @__PURE__ */ new Map();
@@ -2521,6 +2561,10 @@ var AnthropicTools = class {
2521
2561
  webSearch(config) {
2522
2562
  return runnable(createWebSearchTool(this.exa, this.registry, config));
2523
2563
  }
2564
+ /** Anthropic `get_contents` tool for reading pages by URL. */
2565
+ getContents(config) {
2566
+ return runnable(createGetContentsTool(this.exa, this.registry, config));
2567
+ }
2524
2568
  /**
2525
2569
  * Run the `tool_use` blocks in an assistant message and return the matching
2526
2570
  * `tool_result` blocks. Every `tool_use` block is answered so the follow-up
@@ -2649,6 +2693,12 @@ var OpenAIResponsesTools = class {
2649
2693
  createWebSearchTool(this.exa, this.registry, config)
2650
2694
  );
2651
2695
  }
2696
+ /** Responses API `get_contents` tool for reading pages by URL. */
2697
+ getContents(config) {
2698
+ return responsesRunnable(
2699
+ createGetContentsTool(this.exa, this.registry, config)
2700
+ );
2701
+ }
2652
2702
  /**
2653
2703
  * Run the function calls in a Responses API response (or output item array)
2654
2704
  * and return `function_call_output` items. Every function call is answered
@@ -2703,6 +2753,10 @@ var OpenAITools = class {
2703
2753
  webSearch(config) {
2704
2754
  return runnable2(createWebSearchTool(this.exa, this.registry, config));
2705
2755
  }
2756
+ /** Chat Completions `get_contents` tool for reading pages by URL. */
2757
+ getContents(config) {
2758
+ return runnable2(createGetContentsTool(this.exa, this.registry, config));
2759
+ }
2706
2760
  async handleToolCalls(assistantMessage, options) {
2707
2761
  if (isResponsesInput(assistantMessage)) {
2708
2762
  return this.handleResponsesToolCalls(assistantMessage, options);
@@ -2765,6 +2819,7 @@ function isResponsesInput(value) {
2765
2819
  var fetchImpl = typeof global !== "undefined" && global.fetch ? global.fetch : import_cross_fetch.default;
2766
2820
  var HeadersImpl = typeof global !== "undefined" && global.Headers ? global.Headers : import_cross_fetch.Headers;
2767
2821
  var DEFAULT_MAX_CHARACTERS = 1e4;
2822
+ var DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
2768
2823
  var NON_JSON_BODY_SNIPPET_LENGTH = 500;
2769
2824
  async function readResponseBody(response) {
2770
2825
  const text = await response.text();
@@ -2810,7 +2865,8 @@ var Exa2 = class {
2810
2865
  this.agent = new AgentClient(this);
2811
2866
  this.beta = new BetaClient(this.agent);
2812
2867
  this.tools = {
2813
- webSearch: (options) => createWebSearchTool(this, this.toolRegistry, options)
2868
+ webSearch: (options) => createWebSearchTool(this, this.toolRegistry, options),
2869
+ getContents: (options) => createGetContentsTool(this, this.toolRegistry, options)
2814
2870
  };
2815
2871
  this.openai = new OpenAITools(this, this.toolRegistry);
2816
2872
  this.anthropic = new AnthropicTools(this, this.toolRegistry);
@@ -2866,6 +2922,7 @@ var Exa2 = class {
2866
2922
  buildSearchRequestBody(query, options) {
2867
2923
  const requestOptions = { ...options ?? {} };
2868
2924
  delete requestOptions.stream;
2925
+ delete requestOptions.betas;
2869
2926
  if (options === void 0 || !("contents" in options)) {
2870
2927
  return {
2871
2928
  query,
@@ -3019,11 +3076,9 @@ var Exa2 = class {
3019
3076
  400 /* BadRequest */
3020
3077
  );
3021
3078
  }
3022
- return await this.request(
3023
- "/search",
3024
- "POST",
3025
- this.buildSearchRequestBody(query, options)
3026
- );
3079
+ const body = this.buildSearchRequestBody(query, options);
3080
+ const betaHeaders = headersForBetas(options?.betas);
3081
+ return betaHeaders ? await this.request("/search", "POST", body, void 0, betaHeaders) : await this.request("/search", "POST", body);
3027
3082
  }
3028
3083
  /**
3029
3084
  * Stream a search response as an async generator of OpenAI-style chat completion chunks.
@@ -3130,11 +3185,13 @@ var Exa2 = class {
3130
3185
  } else {
3131
3186
  requestUrls = urls.map((result) => result.url);
3132
3187
  }
3188
+ const { betas, ...contentsOptions } = options ?? {};
3133
3189
  const payload = {
3134
3190
  urls: requestUrls,
3135
- ...options
3191
+ ...contentsOptions
3136
3192
  };
3137
- return await this.request("/contents", "POST", payload);
3193
+ const betaHeaders = headersForBetas(betas);
3194
+ return betaHeaders ? await this.request("/contents", "POST", payload, void 0, betaHeaders) : await this.request("/contents", "POST", payload);
3138
3195
  }
3139
3196
  async answer(query, options) {
3140
3197
  if (options?.stream) {
@@ -3343,7 +3400,9 @@ var index_default = Exa2;
3343
3400
  BetaClient,
3344
3401
  CreateEnrichmentParametersFormat,
3345
3402
  CreateImportParametersFormat,
3403
+ DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION,
3346
3404
  DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION,
3405
+ DYNAMIC_HIGHLIGHTS_BETA,
3347
3406
  EventType,
3348
3407
  EventsClient,
3349
3408
  Exa,
@@ -3383,6 +3442,7 @@ var index_default = Exa2;
3383
3442
  WebsetStatus,
3384
3443
  WebsetWebhooksClient,
3385
3444
  WebsetsClient,
3445
+ createGetContentsTool,
3386
3446
  createWebSearchTool
3387
3447
  });
3388
3448
  //# sourceMappingURL=index.js.map