klawsearch

JavaScript / TypeScript SDK for KlawSearch — a search API built for AI agents: one call returns ranked, cleaned results plus a grounded, source-cited answer.

npm install klawsearch

Get a free API key at klawsearch.com — 1,000 requests/month, no card required.

• Zero dependencies — uses the runtime's native fetch
• Fully typed — TypeScript definitions included
• ESM + CommonJS — import and require both work
• Runs on Node 18+, Deno, Bun, Cloudflare Workers, and browsers

Quick start

import { KlawSearch } from "klawsearch";

const klaw = new KlawSearch("ks-live-..."); // or set KLAWSEARCH_API_KEY

const r = await klaw.search("latest LLM agent benchmarks", { maxResults: 5 });

console.log(r.answer);
for (const hit of r.results) {
  console.log(hit.score, hit.url, hit.title);
}

CommonJS works too:

const { KlawSearch } = require("klawsearch");

SEC / EDGAR filings

Financial filings the general-purpose search APIs don't index:

const r = await klaw.searchFilings("AAPL supply chain risk factors", {
  ticker: "AAPL",
  formTypes: ["10-K"],
  maxResults: 5,
});

for (const f of r.results) {
  console.log(f.form_type, f.filing_date, f.company_name, f.url);
}

Extract page content

const r = await klaw.extract(["https://example.com/article"]);
console.log(r.results[0]?.content); // cleaned, LLM-ready text

Options

await klaw.search("query", {
  maxResults: 5,               // default 5
  searchDepth: "advanced",     // "basic" | "advanced"
  includeDomains: ["arxiv.org"],
  excludeDomains: ["pinterest.com"],
  includeAnswer: true,         // synthesized answer, default true
  includeRawContent: false,    // full page text per result
});

Errors

Typed error classes let you handle each failure mode precisely:

import {
  KlawSearch,
  AuthError,
  QuotaExceededError,
  RateLimitError,
} from "klawsearch";

try {
  await klaw.search("...");
} catch (err) {
  if (err instanceof QuotaExceededError) {
    // monthly quota used up — upgrade the plan
  } else if (err instanceof RateLimitError) {
    // per-minute burst — back off and retry
  } else if (err instanceof AuthError) {
    // bad or missing key
  }
}

Every error carries statusCode. The hierarchy is KlawSearchError → AuthError (401), QuotaExceededError / RateLimitError (429), ServerError (5xx).

Configuration

| Option | Default | Notes | |---|---|---| | apiKey (1st arg) | KLAWSEARCH_API_KEY env var | required | | baseUrl | https://api.klawsearch.com | or KLAWSEARCH_BASE_URL | | timeout | 60000 ms | per request | | fetch | global fetch | inject your own for tests/proxies |

Self-hosting KlawSearch? Point baseUrl at your own instance:

const klaw = new KlawSearch("...", { baseUrl: "https://klaw.your-domain.com" });

Also available

• Python SDK: pip install klawsearch
• MCP server (Claude Desktop, Goose, Cursor): pip install klawsearch-mcp

MIT licensed.