TypeScript SDK

The serpex package is the official TypeScript SDK for the Serpex API. It works in Node.js and any TypeScript or JavaScript project.

Package: serpex on npm — v2.6.0

Installation

npm install serpex
# or
yarn add serpex
# or
pnpm add serpex

Initialize the Client

import { SerpexClient } from "serpex";

const client = new SerpexClient("sk_your_api_key");

The constructor accepts an optional second argument baseUrl if you need to point at a different host (defaults to https://api.serpex.dev).

Search

import { SerpexClient } from "serpex";

const client = new SerpexClient("sk_your_api_key");

// Auto-routing — Serpex picks the best engine
const results = await client.search({
  q: "typescript tutorial",
  engine: "auto",
});

console.log(results.results[0].title);
console.log(results.results[0].url);
console.log(results.metadata.credits_used);

// With time range filter
const recentResults = await client.search({
  q: "latest AI news",
  engine: "auto",
  time_range: "week",
  category: "web",
});

Search Parameters

interface SearchParams {
  q: string;                                                    // Required
  engine?: "auto" | "google" | "bing" | "duckduckgo"
         | "brave" | "yahoo" | "yandex";                      // Default: "auto"
  category?: "web" | "news";                                   // Default: "web"
  time_range?: "all" | "day" | "week" | "month" | "year";    // Default: "all"
}

Extract

import { SerpexClient } from "serpex";

const client = new SerpexClient("sk_your_api_key");

// Extract as Markdown — ideal for LLM processing
const result = await client.extract({
  urls: ["https://example.com", "https://httpbin.org"],
});

result.results.forEach((r) => {
  if (r.success) {
    console.log(`${r.url}: ${r.markdown?.length} characters`);
  } else {
    console.log(`${r.url}: failed — ${r.error}`);
  }
});

console.log(`Credits used: ${result.metadata.credits_used}`);

Extract with Stealth Mode

// Stealth mode for sites with bot protection — costs 5 credits per URL
const stealthResult = await client.extract({
  urls: ["https://protected-site.com/page"],
  stealth: true,
  format: "html",
});

console.log(stealthResult.results[0].html);

Extract Parameters

interface ExtractParams {
  urls: string[];               // Required. Max 10 URLs per request.
  stealth?: boolean;            // Default: false. 5 credits/URL when true.
  format?: "markdown" | "html"; // Default: "markdown"
}

Error Handling

import { SerpexClient, SerpApiException } from "serpex";

const client = new SerpexClient("sk_your_api_key");

try {
  const results = await client.search({ q: "test query" });
} catch (error) {
  if (error instanceof SerpApiException) {
    console.log("API Error:", error.message);
    console.log("Status Code:", error.statusCode);
    console.log("Details:", error.details);
  }
}