desearch.js

Official JavaScript and TypeScript SDK for the Desearch public API.

This repo publishes the npm package desearch-js. In the current source tree, the package version is 1.5.1.

Related docs:

• docs/features.md
• docs/architecture.md
• docs/known-issues.md
• docs/decisions/0001-thin-node-sdk-transport.md

Package purpose

desearch.js is a thin, Node-oriented SDK for the Desearch API. It wraps the public read-side endpoints implemented in src/index.ts behind one Desearch client class and ships a typed surface from src/types.ts.

What it covers today:

• AI multi-source search
• AI web-links search
• AI X-links search
• X search and lookup endpoints
• web search
• page extraction

What it does not try to be:

• a browser-first SDK
• a configurable transport layer
• a write or mutation client
• a framework with retries, pagination helpers, or runtime validation

Quick Start

Install

npm install desearch-js

Requires Node.js ≥ 20.18.1

ESM usage

Desearch is both the default export and a named export.

import Desearch from 'desearch-js';
// or: import { Desearch } from 'desearch-js';

const client = new Desearch(process.env.DESEARCH_API_KEY!);

const result = await client.aiSearch({
  prompt: 'latest Bittensor developments',
  tools: ['web'],
  start_date: '2025-05-01T00:00:00Z',
  end_date: '2025-05-08T00:00:00Z',
  include_domains: ['bbc.com', 'reuters.com'],
  result_type: 'LINKS_WITH_FINAL_SUMMARY',
  count: 10,
});

console.log(result);

CommonJS usage

const { Desearch } = require('desearch-js');
// or: const Desearch = require('desearch-js').default;

const client = new Desearch(process.env.DESEARCH_API_KEY);

Authentication

The constructor accepts a single argument, your API key:

const client = new Desearch('your-api-key');

The SDK sends that value as the Authorization header on every request.

API overview

AI search methods

• aiSearch(payload) → POST /desearch/ai/search
• aiWebLinksSearch(payload) → POST /desearch/ai/search/links/web
• aiXLinksSearch(payload) → POST /desearch/ai/search/links/twitter

X methods

• xSearch(params) → GET /twitter
• xPostsByUrls(params) → GET /twitter/urls
• xPostById(params) → GET /twitter/post
• xPostsByUser(params) → GET /twitter/post/user
• xPostRetweeters(params) → GET /twitter/post/retweeters
• xUserPosts(params) → GET /twitter/user/posts
• xUserReplies(params) → GET /twitter/replies
• xPostReplies(params) → GET /twitter/replies/post
• xTrends(params) → GET /twitter/trends

Web methods

• webSearch(params) → GET /web
• extract(params) → GET /web/extract
• webCrawl(params) → GET /web/crawl (deprecated compatibility method)

Usage examples

AI search

const result = await client.aiSearch({
  prompt: 'recent AI chip announcements',
  tools: ['web'],
  exclude_domains: ['pinterest.com'],
  result_type: 'LINKS_WITH_FINAL_SUMMARY',
  count: 20,
});

Notes:

• tools accepts the source names defined in src/types.ts: web, hackernews, reddit, wikipedia, youtube, twitter, arxiv
• aiSearch always sends streaming: false, even if a caller tries to add a streaming field manually

AI web links search

const links = await client.aiWebLinksSearch({
  prompt: 'open source browser automation tools',
  tools: ['web', 'hackernews', 'reddit', 'youtube'],
  count: 20,
});

AI X links search

const xLinks = await client.aiXLinksSearch({
  prompt: 'Bittensor subnet updates',
  count: 20,
});

X search

const tweets = await client.xSearch({
  query: 'bittensor',
  sort: 'Top',
  lang: 'en',
  min_likes: 50,
  count: 20,
});

X posts by URL

const tweets = await client.xPostsByUrls({
  urls: ['https://x.com/DesearchAI/status/1234567890123456789'],
});

Web search

const results = await client.webSearch({
  query: 'site:desearch.ai sdk docs',
  start: 0,
});

Extract

const page = await client.extract({
  url: 'https://desearch.ai',
  format: 'text',
});

Existing webCrawl() integrations continue to use the deprecated GET /web/crawl compatibility route. Use extract() for new integrations.

Optional response cost metadata

SDK methods return the same raw payload shape by default:

const results = await client.webSearch({ query: 'desearch sdk' });
console.log(results.data);

If you want per-request cost visibility, pass { includeMetadata: true } as the second argument. The SDK reads metadata from the same API response headers; it does not make an extra billing or pricing request.

const response = await client.webSearch(
  { query: 'desearch sdk' },
  { includeMetadata: true },
);

console.log(response.data);
console.log(response.metadata.costUsd);
console.log(response.metadata.usageCount);
console.log(response.metadata.service);
console.log(response.metadata.currency);

The metadata wrapper works for JSON object, JSON array, and text endpoints such as extract() and webCrawl(). Missing or malformed metadata headers are ignored, so successful API calls still resolve normally.

Tech stack

• TypeScript ^5.9.3
• undici ^6.28.1 || ^7.29.1 for HTTP transport
• dotenv ^17.3.1 as a runtime dependency in package.json
• tsup ^8.5.1 for bundling
• vitest ^4.0.18 for tests
• typedoc ^0.28.17
• typedoc-plugin-markdown ^4.10.0
• output targets: CommonJS, ESM, and bundled declaration files

Commands

Command	Purpose
npm run build	Build dist/ with tsup using the config in tsup.config.ts
npm run build-fast	Build src/index.ts directly into CJS and ESM without the full default tsup command
npm test	Run the Vitest test suite
npm run generate-docs	Generate markdown API docs from src/index.ts using TypeDoc
npm run build:beta	Build for beta publishing
npm run version:beta	Bump a beta prerelease version
npm run version:stable	Bump a stable patch version
npm run publish:beta	Version, build, and publish with the beta npm tag
npm run publish:stable	Version, build, and publish as the default release
npm run prepublishOnly	Automatic npm hook that runs npm run build before publish

Architecture overview

Source layout:

• src/index.ts, the Desearch client plus the shared handleRequest<T>() transport helper
• src/types.ts, request/response contracts and X entity models
• tsup.config.ts, build output configuration
• package.json, scripts, exports, dependency versions, and package metadata

Key design decisions in the current source:

• one shared request helper powers every public method
• GET payloads are serialized through URLSearchParams
• POST payloads are serialized as JSON
• response parsing switches between JSON and text based on content-type
• default calls return the parsed payload directly, preserving the existing SDK response shape
• callers can opt into { data, metadata } wrappers with { includeMetadata: true }
• extract() and the legacy webCrawl() method return text while most other methods return JSON-shaped data
• the base URL is fixed to https://api.desearch.ai
• aiSearch() forcibly disables streaming

See docs/architecture.md for the detailed flow and ADR 0001 for the reasoning behind the current transport design.

Error handling

HTTP failures are thrown as plain Error instances in this format:

HTTP <status>: <response body>

Non-HTTP failures are wrapped as:

Unexpected Error: <message>

Example:

try {
  await client.webSearch({ query: 'desearch' });
} catch (error) {
  console.error(error);
}

Package outputs

package.json exports:

• ./dist/index.js for CommonJS
• ./dist/index.mjs for ESM
• ./dist/index.d.ts for TypeScript declarations

Known limitations

Current limitations include:

• no configurable base URL
• no timeout, retry, or abort controls in the public API
• aiSearch always disables streaming
• runtime failures surface as plain Error strings rather than typed SDK errors

Full details: docs/known-issues.md