exa-js 2.25.0 → 2.26.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
@@ -4,7 +4,7 @@
4
4
 
5
5
  The official JavaScript SDK for [Exa](https://exa.ai), the web search API built for AI.
6
6
 
7
- [Documentation](https://docs.exa.ai)  |  [Dashboard](https://dashboard.exa.ai)
7
+ [Documentation](https://exa.ai/docs)  |  [Dashboard](https://dashboard.exa.ai)
8
8
 
9
9
  ## Install
10
10
 
@@ -95,7 +95,7 @@ Deep search variants that also support `additionalQueries`:
95
95
 
96
96
  ### Raw body fields
97
97
 
98
- Pass `requestOptions.body` as the third argument for per-call search body overrides.
98
+ Pass `requestOptions.body` as the third argument for per-call search body overrides. Every other method takes it too; see [Request options](#request-options).
99
99
 
100
100
  ```typescript
101
101
  const result = await exa.search("AI research", undefined, { body: { futureField: true } });
@@ -106,7 +106,7 @@ const result = await exa.search("AI research", undefined, { body: { futureField:
106
106
  Get clean text, highlights, or summaries from any URL.
107
107
 
108
108
  ```ts
109
- const { results } = await exa.getContents(["https://docs.exa.ai"], {
109
+ const { results } = await exa.getContents(["https://exa.ai/docs"], {
110
110
  text: true,
111
111
  highlights: true,
112
112
  summary: true,
@@ -246,7 +246,7 @@ const ultraRun = await exa.agent.runs.create({
246
246
 
247
247
  Agent Monitors use the beta namespace and require the `AGENT_MONITORS_BETA_HEADER` beta identifier (`agent-monitors-2026-08-04`).
248
248
 
249
- An Agent Monitor keeps a table of entities × fields fresh on a cadence: static fields are answered once per entity over the live web, dynamic fields are tracked from news on every refresh.
249
+ An Agent Monitor keeps a table of entities × fields fresh on a cadence.
250
250
 
251
251
  ```ts
252
252
  import { AGENT_MONITORS_BETA_HEADER } from "exa-js";
@@ -264,8 +264,8 @@ const monitor = await exa.beta.agent.monitors.create(
264
264
  { name: "Globex", domain: "globex.com" },
265
265
  ],
266
266
  fields: [
267
- { name: "funding", description: "New funding rounds" }, // dynamic by default
268
- { name: "ceo", description: "The company's current CEO", mode: "static" },
267
+ { name: "funding", description: "New funding rounds" },
268
+ { name: "ceo", description: "The company's current CEO" },
269
269
  ],
270
270
  },
271
271
  { idempotencyKey: "my-monitor-1" } // safe retries: same key returns the same monitor
@@ -305,6 +305,122 @@ console.log(current.status, current.refresh, current.usage);
305
305
  await exa.beta.agent.monitors.delete(monitor.id, { betas });
306
306
  ```
307
307
 
308
+ ## Request options
309
+
310
+ Every API method takes a request options object as its last argument. It comes after a method's existing arguments, so pass `undefined` for any you skip.
311
+
312
+ | Option | Effect |
313
+ | ------------------- | ----------------------------------------------------------- |
314
+ | `body` | Extra fields merged over the JSON request body |
315
+ | `headers` | Extra request headers |
316
+ | `query` | Extra query parameters |
317
+ | `signal`, `timeout` | See [Cancellation and timeouts](#cancellation-and-timeouts) |
318
+
319
+ ```ts
320
+ // Send a field the SDK does not type yet.
321
+ await exa.getContents(
322
+ "https://example.com",
323
+ { text: true },
324
+ { body: { futureField: true } }
325
+ );
326
+
327
+ await exa.websets.list(
328
+ { limit: 10 },
329
+ {
330
+ query: { futureParam: "value" },
331
+ headers: { "X-Request-Source": "nightly" },
332
+ }
333
+ );
334
+ ```
335
+
336
+ `body`, `headers` and `query` add to the request the method builds. On a name the method also sets, your value wins.
337
+
338
+ - `body` is sent with `POST`, `PUT` and `PATCH` requests. Other requests ignore it; use `query` there.
339
+ - A header the SDK sets, such as `User-Agent`, is replaced whatever its case. A header set to `null` is removed.
340
+ - The method you call decides whether the response streams. `stream` is never taken from `body` or `query`, and a streaming method keeps its `Accept: text/event-stream`: call the streaming method instead.
341
+ - Helpers that make several requests (`listAll`, `getAll`, `pollUntilFinished`, `createAndWait`, `waitUntilIdle`) apply the options to each one, so `createAndWait` sends `body` with the create request and not with its polls. A `cursor` in `query` picks the first page of `listAll` and `getAll`; the helper advances from there.
342
+ - A CSV import's upload goes to a presigned URL and receives none of the three.
343
+ - The LLM tool helpers (`exa.tools`, `exa.openai`, `exa.anthropic`) take no request options argument. A `webSearch` tool passes the `signal` and `timeout` in its config to every search it runs; a `getContents` tool takes neither, and neither tool takes `body`, `headers` or `query`. `run`, `execute` and `handleToolCalls` / `handleToolUse` take no per-call options.
344
+
345
+ The deprecated `exa.beta.agent.runs` `get`, `cancel`, `stop`, and `delete` take request options in their options object, next to `betas`.
346
+
347
+ ## Cancellation and timeouts
348
+
349
+ The request options take `signal` to cancel the request and `timeout` in milliseconds. They are never sent in the request body.
350
+
351
+ ```ts
352
+ const controller = new AbortController();
353
+ const pending = exa.search("latest AI developments", undefined, {
354
+ signal: controller.signal,
355
+ });
356
+ controller.abort();
357
+ await pending; // rejects with ExaAbortError
358
+
359
+ await exa.getContents(
360
+ "https://example.com",
361
+ { text: true },
362
+ { timeout: 10_000 }
363
+ );
364
+ await exa.websets.get("ws_123", undefined, { timeout: 10_000 });
365
+ await exa.agent.runs.get("run_123", { timeout: 10_000 });
366
+ ```
367
+
368
+ Search, contents, and answer also accept `signal` and `timeout` inside their options object; the trailing argument wins when both set the same field.
369
+
370
+ Set a default timeout for every request on the client; a per-call `timeout` overrides it. Without one, the SDK applies no timeout of its own.
371
+
372
+ ```ts
373
+ const exa = new Exa(process.env.EXA_API_KEY, undefined, { timeout: 30_000 });
374
+ ```
375
+
376
+ `timeout` is a positive integer up to 2,147,483,647 ms and applies to each HTTP request:
377
+
378
+ - A regular call must finish, response body included, within the timeout.
379
+ - A streaming call (`streamSearch`, `streamAnswer`, `stream: true`) must start within the timeout. Once the stream is flowing the timeout no longer applies; use `signal` to stop it.
380
+ - Helpers that make several requests (`listAll`, `getAll`, `pollUntilFinished`, `createAndWait`, `waitUntilIdle`) apply it to each one. Aborting the signal also ends the wait between polls.
381
+
382
+ Both failures have their own error class: `ExaTimeoutError` (`name` `"TimeoutError"`) when `timeout` expires, and `ExaAbortError` (`name` `"AbortError"`) when your `signal` aborts, whatever its reason, `AbortSignal.timeout()` included.
383
+
384
+ ```ts
385
+ import { ExaAbortError, ExaTimeoutError } from "exa-js";
386
+
387
+ try {
388
+ await exa.search("latest AI developments", undefined, { timeout: 5_000 });
389
+ } catch (error) {
390
+ if (error instanceof ExaTimeoutError) {
391
+ // An ExaError with statusCode 408; error.timeout is the limit in ms.
392
+ } else if (error instanceof ExaAbortError) {
393
+ // The caller's signal aborted; error.cause is the underlying reason.
394
+ }
395
+ }
396
+ ```
397
+
398
+ `request` / `rawRequest` take the same options as their sixth argument. With `rawRequest`, the timeout keeps running until the response body is consumed or cancelled, so do one or the other when finished. Keeping only a body reader or a cloned response does not end cancellation or timeout coverage, and an interrupted body read rejects with the platform's own error. Request timers and signal listeners are released when the body settles.
399
+
400
+ ## Warnings
401
+
402
+ The API can return `warnings` about a request, such as a field it ignores. At the time of writing, search responses carry them, including `streamSearch`. A warning never changes the status code or the results. It is for whoever maintains the code that builds the request. Fix the request, and don't pass the warning to a model. The response keeps them in `warnings`.
403
+
404
+ By default the client prints each one with `console.warn`, once per process for each endpoint, code and path:
405
+
406
+ ```text
407
+ [exa] POST /search IGNORED_FIELD at /startCrawlDate: startCrawlDate is no longer supported and is ignored. Remove it from the request.
408
+ ```
409
+
410
+ The client's `warnings` option changes that. `"silent"` prints nothing. A function receives every warning, with the request it is about, instead of printing:
411
+
412
+ ```ts
413
+ const quiet = new Exa(process.env.EXA_API_KEY, undefined, { warnings: "silent" });
414
+
415
+ const routed = new Exa(process.env.EXA_API_KEY, undefined, {
416
+ warnings: (warning, { endpoint, method, requestId }) => {
417
+ logger.warn({ ...warning, endpoint, method, requestId }, "Exa API warning");
418
+ },
419
+ });
420
+ ```
421
+
422
+ The handler's types are `ApiWarning` (`code`, `path` and `message`) and `ApiWarningContext`. Options the API ignores are marked `@deprecated` in the types, so editors flag them before the request is sent. At the time of writing, `useAutoprompt` is one of them.
423
+
308
424
  ## TypeScript
309
425
 
310
426
  Full TypeScript support with types for all methods.
@@ -316,8 +432,8 @@ import type { SearchResponse, RegularSearchOptions } from "exa-js";
316
432
 
317
433
  ## Links
318
434
 
319
- - [Documentation](https://docs.exa.ai)
320
- - [API Reference](https://docs.exa.ai/reference)
435
+ - [Documentation](https://exa.ai/docs)
436
+ - [API Reference](https://exa.ai/docs/reference/search)
321
437
  - [Examples](./examples)
322
438
 
323
439
  ## Contributing