exa-js 2.12.1 → 2.14.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/dist/index.d.ts CHANGED
@@ -1,5 +1,278 @@
1
1
  import { ZodSchema } from 'zod';
2
2
 
3
+ /**
4
+ * Types for the Exa Agent API.
5
+ */
6
+
7
+ /**
8
+ * @deprecated Agent API beta header is no longer required for `exa.agent`.
9
+ * Retained for legacy `exa.beta.agent` compatibility.
10
+ */
11
+ declare const AGENT_BETA_HEADER = "agent-2026-05-07";
12
+ interface AgentBetaOptions {
13
+ /**
14
+ * @deprecated Agent API beta header is no longer required for `exa.agent`.
15
+ * Values supplied to `exa.beta.agent` are sent as the `Exa-Beta` header.
16
+ */
17
+ betas?: string[];
18
+ }
19
+ type AgentRunStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
20
+ type AgentStopReason = "schema_satisfied" | "budget_reached" | "error" | "cancelled";
21
+ type AgentConfidence = "low" | "medium" | "high";
22
+ type AgentEffort = "low" | "medium" | "high" | "xhigh" | "auto";
23
+ interface AgentInput {
24
+ data?: Record<string, unknown>[];
25
+ exclusion?: Record<string, unknown>[];
26
+ [key: string]: unknown;
27
+ }
28
+ interface AgentGroundingCitation {
29
+ url: string;
30
+ title?: string | null;
31
+ [key: string]: unknown;
32
+ }
33
+ interface AgentGroundingEntry {
34
+ field: string;
35
+ citations: AgentGroundingCitation[];
36
+ score?: number | null;
37
+ confidence?: AgentConfidence | null;
38
+ [key: string]: unknown;
39
+ }
40
+ interface AgentOutput {
41
+ text?: string | null;
42
+ structured?: unknown;
43
+ grounding?: AgentGroundingEntry[] | null;
44
+ [key: string]: unknown;
45
+ }
46
+ interface AgentUsage {
47
+ agentComputeUnits?: number;
48
+ searches?: number;
49
+ emails?: number;
50
+ phoneNumbers?: number;
51
+ [key: string]: unknown;
52
+ }
53
+ interface AgentCostDollars {
54
+ total?: number;
55
+ agentCompute?: number;
56
+ search?: number;
57
+ emails?: number;
58
+ phoneNumbers?: number;
59
+ [key: string]: unknown;
60
+ }
61
+ interface AgentError {
62
+ type?: string;
63
+ code?: string;
64
+ message?: string;
65
+ path?: string;
66
+ keyword?: string;
67
+ expected?: unknown;
68
+ actual?: unknown;
69
+ [key: string]: unknown;
70
+ }
71
+ interface AgentRun {
72
+ id: string;
73
+ object?: string;
74
+ status: AgentRunStatus;
75
+ stopReason?: AgentStopReason | null;
76
+ createdAt?: string;
77
+ completedAt?: string | null;
78
+ request?: Record<string, unknown>;
79
+ output?: AgentOutput | null;
80
+ usage?: AgentUsage;
81
+ costDollars?: AgentCostDollars;
82
+ error?: AgentError;
83
+ [key: string]: unknown;
84
+ }
85
+ type AgentRunTyped<T> = Omit<AgentRun, "output"> & {
86
+ output?: (Omit<AgentOutput, "structured"> & {
87
+ structured?: T;
88
+ }) | null;
89
+ };
90
+ interface ListAgentRunsParams {
91
+ cursor?: string;
92
+ limit?: number;
93
+ }
94
+ interface ListAgentRunsResponse {
95
+ object?: string;
96
+ data: AgentRun[];
97
+ hasMore: boolean;
98
+ nextCursor: string | null;
99
+ }
100
+ interface DeletedAgentRun {
101
+ id: string;
102
+ object?: string;
103
+ deleted: boolean;
104
+ }
105
+ interface AgentEvent {
106
+ id?: string;
107
+ event: string;
108
+ data: Record<string, unknown>;
109
+ createdAt?: string;
110
+ [key: string]: unknown;
111
+ }
112
+ interface ListAgentRunEventsParams {
113
+ cursor?: string;
114
+ limit?: number;
115
+ }
116
+ interface ListAgentRunEventsResponse {
117
+ object?: string;
118
+ data: AgentEvent[];
119
+ hasMore: boolean;
120
+ nextCursor: string | null;
121
+ }
122
+ interface CreateAgentRunParams {
123
+ query: string;
124
+ systemPrompt?: string;
125
+ input?: AgentInput;
126
+ outputSchema?: Record<string, unknown>;
127
+ effort?: AgentEffort;
128
+ previousRunId?: string;
129
+ metadata?: Record<string, unknown>;
130
+ }
131
+ type CreateAgentRunParamsTyped<T> = Omit<CreateAgentRunParams, "outputSchema"> & {
132
+ outputSchema?: T;
133
+ };
134
+ type AgentCreateOptions<T = Record<string, unknown>> = CreateAgentRunParamsTyped<Record<string, unknown> | ZodSchema<T>> & {
135
+ stream?: boolean;
136
+ };
137
+
138
+ /**
139
+ * Base client for the Exa Agent API.
140
+ */
141
+
142
+ type QueryParams$3 = Record<string, string | number | boolean | string[] | undefined>;
143
+ type RequestBody$2 = Record<string, unknown>;
144
+ declare class AgentBaseClient {
145
+ protected client: Exa;
146
+ constructor(client: Exa);
147
+ protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody$2, params?: QueryParams$3, headers?: Record<string, string>): Promise<T>;
148
+ protected rawRequest(endpoint: string, method?: string, data?: RequestBody$2, params?: QueryParams$3, headers?: Record<string, string>): Promise<Response>;
149
+ protected buildPaginationParams(pagination?: ListAgentRunsParams | ListAgentRunEventsParams): QueryParams$3;
150
+ }
151
+
152
+ /**
153
+ * Client for the Exa Agent API.
154
+ */
155
+
156
+ type WithBetaOptions<T> = T & AgentBetaOptions;
157
+ declare class AgentRunEventsClient extends AgentBaseClient {
158
+ /**
159
+ * List stored events for an Agent run.
160
+ */
161
+ list(runId: string, options?: ListAgentRunEventsParams): Promise<ListAgentRunEventsResponse>;
162
+ }
163
+ declare class AgentRunsClient extends AgentBaseClient {
164
+ /**
165
+ * Client for Agent run events.
166
+ */
167
+ events: AgentRunEventsClient;
168
+ constructor(client: Exa);
169
+ /**
170
+ * Create an Agent run.
171
+ */
172
+ create<T>(params: AgentCreateOptions<T> & {
173
+ stream: true;
174
+ }): Promise<AsyncGenerator<AgentEvent>>;
175
+ create<T>(params: AgentCreateOptions<T> & {
176
+ stream?: false;
177
+ }): Promise<AgentRunTyped<T>>;
178
+ create(params: CreateAgentRunParams): Promise<AgentRun>;
179
+ /**
180
+ * Get an Agent run by ID.
181
+ */
182
+ get(runId: string): Promise<AgentRun>;
183
+ /**
184
+ * List Agent runs.
185
+ */
186
+ list(options?: ListAgentRunsParams): Promise<ListAgentRunsResponse>;
187
+ /**
188
+ * Iterate through all Agent runs, handling pagination automatically.
189
+ */
190
+ listAll(options?: ListAgentRunsParams): AsyncGenerator<AgentRun>;
191
+ /**
192
+ * Collect all Agent runs into an array.
193
+ */
194
+ getAll(options?: ListAgentRunsParams): Promise<AgentRun[]>;
195
+ /**
196
+ * Cancel a queued or running Agent run.
197
+ */
198
+ cancel(runId: string): Promise<AgentRun>;
199
+ /**
200
+ * Delete a stored Agent run.
201
+ */
202
+ delete(runId: string): Promise<DeletedAgentRun>;
203
+ /**
204
+ * Poll an Agent run until it reaches a terminal status.
205
+ */
206
+ pollUntilFinished(runId: string, options?: {
207
+ pollInterval?: number;
208
+ timeoutMs?: number;
209
+ }): Promise<AgentRun & {
210
+ status: "completed" | "failed" | "cancelled";
211
+ }>;
212
+ }
213
+ declare class AgentClient {
214
+ /**
215
+ * @internal
216
+ */
217
+ readonly client: Exa;
218
+ /**
219
+ * Client for Agent runs.
220
+ */
221
+ runs: AgentRunsClient;
222
+ constructor(client: Exa);
223
+ }
224
+ declare class AgentBetaRunEventsClient extends AgentRunEventsClient {
225
+ /**
226
+ * List stored events for an Agent run.
227
+ *
228
+ * @deprecated Use exa.agent.runs.events instead.
229
+ */
230
+ list(runId: string, options?: WithBetaOptions<ListAgentRunEventsParams>): Promise<ListAgentRunEventsResponse>;
231
+ }
232
+ declare class AgentBetaRunsClient extends AgentRunsClient {
233
+ /**
234
+ * @deprecated Use exa.agent.runs.events instead.
235
+ */
236
+ events: AgentBetaRunEventsClient;
237
+ constructor(client: Exa);
238
+ create<T>(params: WithBetaOptions<AgentCreateOptions<T>> & {
239
+ stream: true;
240
+ }): Promise<AsyncGenerator<AgentEvent>>;
241
+ create<T>(params: WithBetaOptions<AgentCreateOptions<T>> & {
242
+ stream?: false;
243
+ }): Promise<AgentRunTyped<T>>;
244
+ create(params: CreateAgentRunParams & AgentBetaOptions): Promise<AgentRun>;
245
+ get(runId: string, options?: AgentBetaOptions): Promise<AgentRun>;
246
+ list(options?: WithBetaOptions<ListAgentRunsParams>): Promise<ListAgentRunsResponse>;
247
+ listAll(options?: WithBetaOptions<ListAgentRunsParams>): AsyncGenerator<AgentRun>;
248
+ getAll(options?: WithBetaOptions<ListAgentRunsParams>): Promise<AgentRun[]>;
249
+ cancel(runId: string, options?: AgentBetaOptions): Promise<AgentRun>;
250
+ delete(runId: string, options?: AgentBetaOptions): Promise<DeletedAgentRun>;
251
+ pollUntilFinished(runId: string, options?: WithBetaOptions<{
252
+ pollInterval?: number;
253
+ timeoutMs?: number;
254
+ }>): Promise<AgentRun & {
255
+ status: "completed" | "failed" | "cancelled";
256
+ }>;
257
+ }
258
+ /**
259
+ * @deprecated Use AgentClient instead.
260
+ */
261
+ declare class AgentBetaClient extends AgentClient {
262
+ /**
263
+ * @deprecated Use exa.agent.runs instead.
264
+ */
265
+ runs: AgentBetaRunsClient;
266
+ constructor(clientOrAgent: Exa | AgentClient);
267
+ }
268
+ declare class BetaClient {
269
+ /**
270
+ * @deprecated Use exa.agent instead.
271
+ */
272
+ agent: AgentBetaClient;
273
+ constructor(clientOrAgent: Exa | AgentClient);
274
+ }
275
+
3
276
  /**
4
277
  * Types for the Search Monitors API
5
278
  */
@@ -34,7 +307,11 @@ interface GroundingEntry {
34
307
  }
35
308
  interface SearchMonitorRunOutput {
36
309
  results?: Record<string, unknown>[] | null;
37
- content?: string | null;
310
+ /**
311
+ * Synthesized output. When the monitor is configured with an `outputSchema`,
312
+ * the API returns this as a structured object; otherwise it is a string.
313
+ */
314
+ content?: string | Record<string, unknown> | null;
38
315
  grounding?: GroundingEntry[] | null;
39
316
  }
40
317
  interface SearchMonitor {
@@ -3256,6 +3533,7 @@ declare class ExaError extends Error {
3256
3533
  * @property {TextContentsOptions | boolean} [text] - Options for retrieving text contents.
3257
3534
  * @property {HighlightsContentsOptions | boolean} [highlights] - Options for retrieving highlights.
3258
3535
  * @property {SummaryContentsOptions | boolean} [summary] - Options for retrieving summary.
3536
+ * @property {ContextOptions | boolean} [context] - DEPRECATED: Use `text` or `highlights` instead. Will be removed in a future version.
3259
3537
  * @property {number} [maxAgeHours] - Maximum age of cached content in hours. If content is older, it will be fetched fresh. Special values: 0 = always fetch fresh content, -1 = never fetch fresh (use cached content only). Example: 168 = fetch fresh for pages older than 7 days.
3260
3538
  * @property {boolean} [filterEmptyResults] - If true, filters out results with no contents. Default is true.
3261
3539
  * @property {number} [subpages] - The number of subpages to return for each result, where each subpage is derived from an internal link for the result.
@@ -3267,7 +3545,10 @@ type ContentsOptions = {
3267
3545
  highlights?: HighlightsContentsOptions | true;
3268
3546
  summary?: SummaryContentsOptions | true;
3269
3547
  livecrawl?: LivecrawlOptions;
3270
- /** @deprecated Use `highlights` or `text` instead. Will be removed in a future version. */
3548
+ /**
3549
+ * DEPRECATED: Use `text` or `highlights` instead. Will be removed in a future version.
3550
+ * @deprecated Use `text` or `highlights` instead. This legacy `context` field will be removed in a future version.
3551
+ */
3271
3552
  context?: ContextOptions | true;
3272
3553
  livecrawlTimeout?: number;
3273
3554
  maxAgeHours?: number;
@@ -3368,11 +3649,13 @@ type DeepObjectOutputSchema = {
3368
3649
  type DeepOutputSchema = DeepTextOutputSchema | DeepObjectOutputSchema;
3369
3650
  /**
3370
3651
  * Contents options for deep search.
3371
- * @deprecated The `context` field is deprecated. Use `highlights` or `text` instead.
3372
3652
  */
3373
3653
  type DeepContentsOptions = Omit<ContentsOptions, "context"> & {
3374
- /** @deprecated Use `highlights` or `text` instead. Will be removed in a future version. */
3375
- context?: Omit<ContextOptions, never> | true;
3654
+ /**
3655
+ * DEPRECATED: Use `text` or `highlights` instead. Will be removed in a future version.
3656
+ * @deprecated Use `text` or `highlights` instead. This legacy `context` field will be removed in a future version.
3657
+ */
3658
+ context?: ContextOptions | true;
3376
3659
  };
3377
3660
  /**
3378
3661
  * Search options for deep search types, which additionally support additional queries.
@@ -3402,6 +3685,9 @@ type NonDeepSearchOptions = BaseRegularSearchOptions & {
3402
3685
  */
3403
3686
  type RegularSearchOptions = DeepSearchOptions | NonDeepSearchOptions;
3404
3687
  /**
3688
+ * DEPRECATED: Used only by deprecated `findSimilar()` APIs. Use `search()` and `RegularSearchOptions` for new search flows. Will be removed in a future version.
3689
+ * @deprecated Use `search()` and `RegularSearchOptions` for new search flows. There is no direct replacement for URL-based similarity.
3690
+ *
3405
3691
  * Options for finding similar links.
3406
3692
  * @typedef {Object} FindSimilarOptions
3407
3693
  * @property {boolean} [excludeSourceDomain] - If true, excludes links from the base domain of the input.
@@ -3451,33 +3737,41 @@ type TextContentsOptions = {
3451
3737
  * @typedef {Object} HighlightsContentsOptions
3452
3738
  * @property {string} [query] - The query string to use for highlights search.
3453
3739
  * @property {number} [maxCharacters] - The maximum number of characters to return for highlights.
3454
- * @property {number} [numSentences] - Deprecated. Use maxCharacters instead.
3455
- * @property {number} [highlightsPerUrl] - Deprecated. Use maxCharacters instead.
3740
+ * @property {number} [numSentences] - DEPRECATED: Use maxCharacters instead.
3741
+ * @property {number} [highlightsPerUrl] - DEPRECATED: Use maxCharacters instead.
3456
3742
  */
3457
3743
  type HighlightsContentsOptions = {
3458
3744
  query?: string;
3459
3745
  maxCharacters?: number;
3460
- /** @deprecated Use maxCharacters instead */
3746
+ /**
3747
+ * DEPRECATED: Use `maxCharacters` instead. Will be removed in a future version.
3748
+ * @deprecated Use `maxCharacters` instead. This legacy sizing field will be removed in a future version.
3749
+ */
3461
3750
  numSentences?: number;
3462
- /** @deprecated Use maxCharacters instead */
3751
+ /**
3752
+ * DEPRECATED: Use `maxCharacters` instead. Will be removed in a future version.
3753
+ * @deprecated Use `maxCharacters` instead. This legacy sizing field will be removed in a future version.
3754
+ */
3463
3755
  highlightsPerUrl?: number;
3464
3756
  };
3465
3757
  /**
3466
3758
  * Options for retrieving summary from page.
3467
3759
  * @typedef {Object} SummaryContentsOptions
3468
3760
  * @property {string} [query] - The query string to use for summary generation.
3469
- * @property {JSONSchema} [schema] - JSON schema for structured output from summary.
3761
+ * @property {Record<string, unknown> | ZodSchema} [schema] - JSON schema for structured output from summary.
3470
3762
  */
3471
3763
  type SummaryContentsOptions = {
3472
3764
  query?: string;
3473
3765
  schema?: Record<string, unknown> | ZodSchema;
3474
3766
  };
3475
3767
  /**
3476
- * @deprecated Use Record<string, unknown> instead.
3768
+ * DEPRECATED: Use `Record<string, unknown>` instead. Will be removed in a future version.
3769
+ * @deprecated Use `Record<string, unknown>` instead.
3477
3770
  */
3478
3771
  type JSONSchema = Record<string, unknown>;
3479
3772
  /**
3480
- * @deprecated Use `highlights` or `text` instead. The `context` option is deprecated and will be removed in a future version.
3773
+ * DEPRECATED: Use `text` or `highlights` instead. Will be removed in a future version.
3774
+ * @deprecated Use `text` or `highlights` instead. The `context` option will be removed in a future version.
3481
3775
  *
3482
3776
  * Options for retrieving the context from a list of search results. The context is a string
3483
3777
  * representation of all the search results.
@@ -3694,7 +3988,7 @@ type DeepSearchOutput = {
3694
3988
  * Represents a search response object.
3695
3989
  * @typedef {Object} SearchResponse
3696
3990
  * @property {Result[]} results - The list of search results.
3697
- * @property {string} [context] - Deprecated. The context for the search.
3991
+ * @property {string} [context] - DEPRECATED: Use `text` or `highlights` on individual results instead. Will be removed in a future version.
3698
3992
  * @property {DeepSearchOutput} [output] - Search synthesized output object returned when `outputSchema` is provided.
3699
3993
  * @property {string} [autoDate] - The autoprompt date, if applicable.
3700
3994
  * @property {string} requestId - The request ID for the search.
@@ -3704,7 +3998,10 @@ type DeepSearchOutput = {
3704
3998
  */
3705
3999
  type SearchResponse<T extends ContentsOptions> = {
3706
4000
  results: SearchResult<T>[];
3707
- /** @deprecated Use `highlights` or `text` on individual results instead. Will be removed in a future version. */
4001
+ /**
4002
+ * DEPRECATED: Use `text` or `highlights` on individual results instead. Will be removed in a future version.
4003
+ * @deprecated Use `text` or `highlights` on individual results instead. This legacy `context` field will be removed in a future version.
4004
+ */
3708
4005
  context?: string;
3709
4006
  output?: DeepSearchOutput;
3710
4007
  autoDate?: string;
@@ -3814,6 +4111,14 @@ declare class Exa {
3814
4111
  * Search Monitors API client
3815
4112
  */
3816
4113
  monitors: SearchMonitorsClient;
4114
+ /**
4115
+ * Agent API client
4116
+ */
4117
+ agent: AgentClient;
4118
+ /**
4119
+ * Beta API clients
4120
+ */
4121
+ beta: BetaClient;
3817
4122
  /**
3818
4123
  * Helper method to separate out the contents-specific options from the rest.
3819
4124
  */
@@ -3835,7 +4140,7 @@ declare class Exa {
3835
4140
  * @throws {ExaError} When any API request fails with structured error information
3836
4141
  */
3837
4142
  request<T = unknown>(endpoint: string, method: string, body?: any, params?: Record<string, any>, headers?: Record<string, string>): Promise<T>;
3838
- rawRequest(endpoint: string, method?: string, body?: Record<string, unknown>, queryParams?: Record<string, string | number | boolean | string[] | undefined>): Promise<Response>;
4143
+ rawRequest(endpoint: string, method?: string, body?: Record<string, unknown>, queryParams?: Record<string, string | number | boolean | string[] | undefined>, headers?: Record<string, string>): Promise<Response>;
3839
4144
  /**
3840
4145
  * Performs a search with an Exa prompt-engineered query.
3841
4146
  * By default, returns text contents. Use contents: false to opt-out.
@@ -3889,6 +4194,7 @@ declare class Exa {
3889
4194
  contents?: ContentsOptions | false | null | undefined;
3890
4195
  }): AsyncGenerator<SearchStreamChunk>;
3891
4196
  /**
4197
+ * DEPRECATED: Use `search()` instead. This legacy wrapper will be removed in a future version.
3892
4198
  * @deprecated Use `search()` instead. The search method now returns text contents by default.
3893
4199
  *
3894
4200
  * Migration examples:
@@ -3896,7 +4202,7 @@ declare class Exa {
3896
4202
  * - `searchAndContents(query, { text: true })` → `search(query, { contents: { text: true } })`
3897
4203
  * - `searchAndContents(query, { summary: true })` → `search(query, { contents: { summary: true } })`
3898
4204
  *
3899
- * Performs a search with an Exa prompt-engineered query and returns the contents of the documents.
4205
+ * Compatibility wrapper for the legacy top-level contents options shape.
3900
4206
  *
3901
4207
  * @param {string} query - The query string.
3902
4208
  * @param {RegularSearchOptions & T} [options] - Additional search + contents options
@@ -3904,6 +4210,9 @@ declare class Exa {
3904
4210
  */
3905
4211
  searchAndContents<T extends ContentsOptions>(query: string, options?: RegularSearchOptions & T): Promise<SearchResponse<T>>;
3906
4212
  /**
4213
+ * DEPRECATED: Use `search()` for new discovery flows. There is no direct replacement for URL-based similarity.
4214
+ * @deprecated Use `search()` for new discovery flows. This legacy URL-similarity method will be removed in a future version.
4215
+ *
3907
4216
  * Finds similar links to the provided URL.
3908
4217
  * By default, returns text contents. Use contents: false to opt-out.
3909
4218
  *
@@ -3916,6 +4225,9 @@ declare class Exa {
3916
4225
  };
3917
4226
  }>>;
3918
4227
  /**
4228
+ * DEPRECATED: Use `search()` for new discovery flows. There is no direct replacement for URL-based similarity.
4229
+ * @deprecated Use `search()` for new discovery flows. This legacy URL-similarity method will be removed in a future version.
4230
+ *
3919
4231
  * Finds similar links to the provided URL without contents.
3920
4232
  *
3921
4233
  * @param {string} url - The URL for which to find similar links.
@@ -3926,6 +4238,9 @@ declare class Exa {
3926
4238
  contents: false | null | undefined;
3927
4239
  }): Promise<SearchResponse<{}>>;
3928
4240
  /**
4241
+ * DEPRECATED: Use `search()` with `contents` for new discovery flows. There is no direct replacement for URL-based similarity.
4242
+ * @deprecated Use `search()` with `contents` for new discovery flows. This legacy URL-similarity method will be removed in a future version.
4243
+ *
3929
4244
  * Finds similar links to the provided URL with specific contents.
3930
4245
  *
3931
4246
  * @param {string} url - The URL for which to find similar links.
@@ -3936,6 +4251,9 @@ declare class Exa {
3936
4251
  contents: T;
3937
4252
  }): Promise<SearchResponse<T>>;
3938
4253
  /**
4254
+ * DEPRECATED: Use `search()` for new discovery flows. There is no direct replacement for URL-based similarity.
4255
+ * @deprecated Use `search()` for new discovery flows. This legacy URL-similarity method will be removed in a future version.
4256
+ *
3939
4257
  * Finds similar links to the provided URL.
3940
4258
  * When no contents option is specified, returns text contents by default.
3941
4259
  *
@@ -3947,14 +4265,15 @@ declare class Exa {
3947
4265
  text: true;
3948
4266
  }>>;
3949
4267
  /**
3950
- * @deprecated Use `findSimilar()` instead. The findSimilar method now returns text contents by default.
4268
+ * DEPRECATED: Use `search()` for new discovery flows instead. This legacy wrapper will be removed in a future version.
4269
+ * @deprecated Use `search()` for new discovery flows instead. There is no direct replacement for URL-based similarity.
3951
4270
  *
3952
4271
  * Migration examples:
3953
- * - `findSimilarAndContents(url)` → `findSimilar(url)`
3954
- * - `findSimilarAndContents(url, { text: true })` → `findSimilar(url, { contents: { text: true } })`
3955
- * - `findSimilarAndContents(url, { summary: true })` → `findSimilar(url, { contents: { summary: true } })`
4272
+ * - `findSimilarAndContents(url)` → `search(query)`
4273
+ * - `findSimilarAndContents(url, { text: true })` → `search(query, { contents: { text: true } })`
4274
+ * - `findSimilarAndContents(url, { summary: true })` → `search(query, { contents: { summary: true } })`
3956
4275
  *
3957
- * Finds similar links to the provided URL and returns the contents of the documents.
4276
+ * Compatibility wrapper for the legacy top-level contents options shape.
3958
4277
  * @param {string} url - The URL for which to find similar links.
3959
4278
  * @param {FindSimilarOptions & T} [options] - Additional options for finding similar links + contents.
3960
4279
  * @returns {Promise<SearchResponse<T>>} A list of similar search results, including requested contents.
@@ -4036,4 +4355,4 @@ declare class Exa {
4036
4355
  private parseSSEStream;
4037
4356
  }
4038
4357
 
4039
- export { type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type ArticleEntity, type BaseSearchOptions, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, 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, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, 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 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 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, 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 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 TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type VerbosityOptions, type WaitUntilCompletedOptions, 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, Exa as default };
4358
+ export { AGENT_BETA_HEADER, AgentBetaClient, type AgentBetaOptions, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentEffort, type AgentError, type AgentEvent, type AgentGroundingCitation, type AgentGroundingEntry, type AgentInput, type AgentOutput, type AgentRun, AgentRunEventsClient, type AgentRunStatus, type AgentRunTyped, AgentRunsClient, type AgentStopReason, type AgentUsage, type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type ArticleEntity, type BaseSearchOptions, BetaClient, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, 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, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, 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 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 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, 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 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 TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type VerbosityOptions, type WaitUntilCompletedOptions, 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, Exa as default };