exa-js

exa-js is the official JavaScript and TypeScript client for Exa, a web search API purpose-built for AI applications and retrieval-augmented generation. It wraps Exa’s REST endpoints — neural and keyword search, content extraction, cited answers, streaming answers, and longer-running research and agent runs — behind a typed client that works the same way in Node.js and the browser.

Beyond basic search, the SDK exposes Exa’s higher-level surfaces: structured output schemas (via Zod or raw JSON Schema) for search and answer results, streaming variants for both search and answers, a Websets API for building and monitoring curated result sets over time, and an Agent Runs API for kicking off multi-step autonomous research tasks with polling helpers. It ships full TypeScript types for every method and response shape, making it a common building block in LLM tool-calling and RAG pipelines that need live web grounding.

What You Get

• A single Exa client class covering search, findSimilar, getContents, answer, and streaming variants of search/answer
• Structured output support on search and answer via Zod schemas or raw JSON Schema, so results come back as typed objects instead of free text
• A Websets client for creating, monitoring, and enriching persistent, curated collections of search results over time
• An Agent Runs API for launching and polling longer, multi-step autonomous research tasks with optional Exa Connect data-provider integrations
• Full TypeScript definitions for every request option and response shape, plus isomorphic fetch handling so the client works in Node.js and browser environments alike

Common Use Cases

• Giving an LLM agent or chatbot live web-search grounding instead of relying on stale training data
• Building RAG pipelines that need semantic (neural) search plus clean extracted page text/highlights in one call
• Generating cited, sourced answers to natural-language questions for research or Q&A features
• Running scheduled or monitored Websets to keep a curated set of search results fresh (e.g. lead lists, competitor tracking)
• Kicking off autonomous multi-step research agent runs that return structured JSON output against a caller-defined schema

Under The Hood

Architecture — The SDK centers on a single Exa class (src/index.ts, ~1,660 lines) constructed with an API key, which owns all core methods (search, findSimilar, getContents, answer, streamSearch, streamAnswer) plus sub-clients attached as properties: exa.websets (src/websets/, client + resource files for items, searches, enrichments, imports, monitors, webhooks, events), exa.research (src/research/), exa.agent/exa.beta (src/agent/), and exa.monitors (src/monitors/). Each sub-domain follows the same base-client pattern (base.ts handles auth headers and request plumbing, client.ts exposes the public methods, types.ts/openapi.ts hold generated or hand-written types), so new API surfaces are added as new sub-clients rather than by growing the root class indefinitely — the Websets openapi.ts (3,729 lines) is explicitly generated from Exa’s published OpenAPI spec via a generate:types:websets script.

Tech Stack — Pure TypeScript targeting both CJS and ESM output via tsup, built to dist/ with .d.ts types included. Runtime dependencies are deliberately minimal: cross-fetch (isomorphic fetch for Node/browser parity), zod and zod-to-json-schema (optional structured-output schema support), and dotenv for local API-key loading in examples/tests. openai appears as a dependency, used for typing/compatibility with OpenAI-style streaming chunk shapes rather than as an active client. Tooling is modern and consistent: tsup for bundling, vitest for tests (split into unit and integration configs), prettier for formatting, and ts-morph/tsx used in a docs-generation script.

Code Quality — Tests live under test/unit (search, websets — including validation/structure/error/imports/monitors variants, agent, research, monitors, request error handling) and test/integration (live-network tests for search, findSimilar, livecrawl), separated by dedicated Vitest configs so unit tests can run without network access. Error handling is centralized in a small ExaError class (src/errors.ts) carrying HTTP status code, timestamp, and request path, with readResponseBody/truncateResponseBody helpers in index.ts specifically guarding against API gateways returning HTML/text error pages instead of JSON — a detail that shows the maintainers hardened against real production failure modes rather than just the happy path. JSDoc comments are dense throughout the public API surface.

API Design — The client is deliberately low-ceremony: new Exa(apiKey) then exa.search(query, options) covers the common case in two lines, with optional fields (contents, filters, structured output schema) layered on rather than required upfront. Method names map directly to product concepts (search, findSimilar, getContents, answer), streaming variants are named consistently (streamSearch, streamAnswer) and yield OpenAI-style chunks so they slot into existing streaming UI code with little adaptation. TypeScript types are exported for every request/response shape, and the README leads with copy-pasteable quick-start snippets for each major feature (search, contents, answer, agent runs) rather than a reference-only doc style.