Node.js SDK - WhizoAI API Documentation

Overview

The WhizoAI Node.js SDK provides a complete TypeScript-first interface for accessing WhizoAI’s web scraping, crawling, and AI-powered data extraction capabilities.

TypeScript Support

Full type definitions and IntelliSense for better developer experience

Modern ESM

ES Module support with tree-shaking for optimal bundle sizes

Zero Dependencies

Minimal footprint with only essential dependencies

Installation

npm install whizoai

Quick Start

import { WhizoAI } from 'whizoai';

// Initialize the client
const whizoai = new WhizoAI({
  apiKey: process.env.WHIZOAI_API_KEY, // Get from https://whizo.ai/app/api-keys
});

// Scrape a webpage
const result = await whizoai.scrape('https://example.com', {
  format: 'markdown',
  onlyMainContent: true,
});

console.log(result.data.content);
console.log(`Credits used: ${result.creditsUsed}`);

Authentication

Get your API key from the WhizoAI Dashboard.

Environment Variable (Recommended)

export WHIZOAI_API_KEY="whizo_your_api_key_here"

import { WhizoAI } from 'whizoai';

const whizoai = new WhizoAI({
  apiKey: process.env.WHIZOAI_API_KEY,
});

Direct Initialization

const whizoai = new WhizoAI({
  apiKey: 'whizo_your_api_key_here',
});

Core Features

Single Page Scraping

Extract content from any webpage in multiple formats:

const result = await whizoai.scrape('https://example.com', {
  format: 'markdown', // 'markdown' | 'html' | 'text' | 'json'
  onlyMainContent: true,
  includeScreenshot: false,
  includePDF: false,
  waitFor: 0, // milliseconds to wait before scraping
  headers: {
    'User-Agent': 'Custom User Agent',
  },
});

console.log(result.data.content);
console.log(result.data.metadata.title);
console.log(`Credits used: ${result.creditsUsed}`);

Multi-Page Crawling

Crawl entire websites with depth and page limits:

const result = await whizoai.crawl('https://example.com', {
  maxPages: 10,
  maxDepth: 2,
  allowedDomains: ['example.com'],
  excludePaths: ['/admin', '/private'],
  format: 'markdown',
  onlyMainContent: true,
});

console.log(`Crawled ${result.data.pages.length} pages`);
result.data.pages.forEach(page => {
  console.log(`${page.url}: ${page.content.substring(0, 100)}...`);
});

AI-Powered Extraction

Extract structured data from webpages using AI:

const result = await whizoai.extract('https://github.com/anthropics', {
  schema: {
    companyName: 'string',
    description: 'string',
    mainProducts: ['string'],
    teamSize: 'number',
  },
  prompt: 'Extract information about this company',
});

console.log(result.data.extractedData);
// {
//   companyName: "Anthropic",
//   description: "AI safety company...",
//   mainProducts: ["Claude", "Constitutional AI"],
//   teamSize: 150
// }

Web Search

Search the web with optional content scraping:

const result = await whizoai.search('best web scraping tools 2025', {
  maxResults: 10,
  scrapeResults: true, // Scrape each search result
  searchEngine: 'google', // 'google' | 'bing' | 'duckduckgo'
  country: 'us',
  language: 'en',
});

console.log(`Found ${result.data.results.length} results`);
result.data.results.forEach(item => {
  console.log(`${item.title}: ${item.url}`);
  if (item.content) {
    console.log(`Content: ${item.content.substring(0, 200)}...`);
  }
});

Batch Operations

Process multiple URLs in parallel:

const result = await whizoai.batch({
  urls: [
    'https://example.com',
    'https://example.com/about',
    'https://example.com/contact',
  ],
  scrapeType: 'scrape',
  options: {
    format: 'markdown',
    onlyMainContent: true,
  },
});

console.log(`Total credits used: ${result.totalCreditsUsed}`);
result.data.results.forEach((item, i) => {
  console.log(`Result ${i + 1}: ${item.status}`);
  if (item.data) {
    console.log(item.data.content.substring(0, 100));
  }
});

Job Management

List Jobs

const jobs = await whizoai.listJobs({
  limit: 20,
  offset: 0,
  status: 'completed', // 'pending' | 'running' | 'completed' | 'failed'
  scrapeType: 'scrape', // Filter by type
});

console.log(`Found ${jobs.data.total} jobs`);
jobs.data.jobs.forEach(job => {
  console.log(`${job.id}: ${job.url} - ${job.status}`);
});

Get Job Details

const job = await whizoai.getJob('job-id-here');

console.log(`Status: ${job.data.status}`);
console.log(`Progress: ${job.data.progress}%`);
console.log(`Credits used: ${job.data.creditsUsed}`);

Cancel Job

await whizoai.cancelJob('job-id-here');
console.log('Job cancelled successfully');

Account Management

Check Credit Balance

const credits = await whizoai.getCreditBalance();

console.log(`Plan: ${credits.data.plan}`);
console.log(`Monthly credits: ${credits.data.monthlyCredits}`);
console.log(`Used this month: ${credits.data.creditsUsedThisMonth}`);
console.log(`Remaining: ${credits.data.creditsRemaining}`);

Get User Profile

const profile = await whizoai.getUserProfile();

console.log(`Email: ${profile.data.email}`);
console.log(`Name: ${profile.data.fullName}`);
console.log(`Plan: ${profile.data.plan}`);

API Key Management

List API Keys

const keys = await whizoai.listApiKeys();

keys.data.forEach(key => {
  console.log(`${key.name}: ${key.maskedKey} (${key.isActive ? 'Active' : 'Inactive'})`);
  console.log(`  Last used: ${key.lastUsedAt}`);
  console.log(`  Usage: ${key.usageCount} requests`);
});

Create API Key

const newKey = await whizoai.createApiKey({
  name: 'Production API Key',
  scopes: ['scrape', 'crawl', 'extract'],
  rateLimitPerHour: 100,
  expiresAt: '2025-12-31T23:59:59Z', // Optional
});

console.log(`New API key: ${newKey.data.apiKey}`);
console.log('⚠️ Save this key - you won\'t see it again!');

Error Handling

The SDK provides structured error types for better error handling:

import {
  WhizoAI,
  WhizoAIError,
  AuthenticationError,
  ValidationError,
  InsufficientCreditsError,
  RateLimitError,
  NetworkError
} from 'whizoai';

try {
  const result = await whizoai.scrape('https://example.com');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Invalid input:', error.details);
  } else if (error instanceof InsufficientCreditsError) {
    console.error('Out of credits:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof WhizoAIError) {
    console.error('WhizoAI error:', error.message, error.code);
  } else {
    console.error('Unexpected error:', error);
  }
}

Advanced Configuration

Custom API URL

For self-hosted or testing environments:

const whizoai = new WhizoAI({
  apiKey: process.env.WHIZOAI_API_KEY,
  apiUrl: 'http://localhost:8080', // Default: https://api.whizo.ai
});

Custom Timeout

const whizoai = new WhizoAI({
  apiKey: process.env.WHIZOAI_API_KEY,
  timeout: 60000, // 60 seconds (default: 30000)
});

Retry Configuration

const whizoai = new WhizoAI({
  apiKey: process.env.WHIZOAI_API_KEY,
  maxRetries: 5, // Default: 3
  retryDelay: 2000, // Initial delay in ms (default: 1000)
});

TypeScript Support

The SDK is written in TypeScript and provides complete type definitions:

import type {
  ScrapeOptions,
  ScrapeResponse,
  CrawlOptions,
  CrawlResponse,
  ExtractOptions,
  ExtractResponse,
  JobStatus,
  UserPlan,
} from 'whizoai';

const options: ScrapeOptions = {
  format: 'markdown',
  onlyMainContent: true,
  includeScreenshot: false,
};

const result: ScrapeResponse = await whizoai.scrape('https://example.com', options);

Credit Costs

Operation	Base Cost	Additional
Basic scraping	1 credit	-
Screenshot	+1 credit	Per page
PDF generation	+1 credit	Per page
AI extraction	3-6 credits	Per page
Web search	1 credit	Per search
Stealth mode	+4 credits	Per page

Rate Limits

Rate limits vary by subscription plan:

Plan	Requests/Hour	Requests/Day
Free	10	100
Hobby	50	500
Standard	200	2,000
Growth	500	5,000
Enterprise	Custom	Custom

Links & Resources

npm Package

View on npm registry

GitHub Repository

View source code and contribute

API Reference

Explore all available endpoints

Get API Key

Generate your API key

Support

Documentation: docs.whizo.ai
Dashboard: whizo.ai/app
Email: [email protected]
GitHub Issues: github.com/whizoai/whizoai-sdks/issues

Client Libraries

AI Tools Integration

​Overview

TypeScript Support

Modern ESM

Zero Dependencies

​Installation

​Quick Start

​Authentication

​Environment Variable (Recommended)

​Direct Initialization

​Core Features

​Single Page Scraping

​Multi-Page Crawling

​AI-Powered Extraction

​Web Search

​Batch Operations

​Job Management

​List Jobs

​Get Job Details

​Cancel Job

​Account Management

​Check Credit Balance

​Get User Profile

​API Key Management

​List API Keys

​Create API Key

​Error Handling

​Advanced Configuration

​Custom API URL

​Custom Timeout

​Retry Configuration

​TypeScript Support

​Credit Costs

​Rate Limits

​Links & Resources

npm Package

GitHub Repository

API Reference

Get API Key

​Support

Overview

Installation

Quick Start

Authentication

Environment Variable (Recommended)

Direct Initialization

Core Features

Single Page Scraping

Multi-Page Crawling

AI-Powered Extraction

Web Search

Batch Operations

Job Management

List Jobs

Get Job Details

Cancel Job

Account Management

Check Credit Balance

Get User Profile

API Key Management

List API Keys

Create API Key

Error Handling

Advanced Configuration

Custom API URL

Custom Timeout

Retry Configuration

TypeScript Support

Credit Costs

Rate Limits

Links & Resources

Support