unbrowser-core

@unbrowser/core

Official SDK for the Unbrowser cloud API - intelligent web browsing for AI agents.

What is Unbrowser?

Unbrowser is an intelligent web browsing API that learns from patterns, discovers APIs automatically, and progressively optimizes to bypass browser rendering entirely.

Key capabilities:

• Extract content from any webpage as markdown, text, or HTML
• Automatic API discovery for 10x faster subsequent requests
• Workflow recording and replay for automation
• Session management for authenticated browsing
• Self-describing API designed for LLM agents

Installation

npm install @unbrowser/core

Quick Start

import { createUnbrowser } from '@unbrowser/core';

const client = createUnbrowser({
  apiKey: process.env.UNBROWSER_API_KEY
});

// Browse a URL and extract content
const result = await client.browse('https://example.com');
console.log(result.content.markdown);

LLM-Friendly Design

This SDK is designed specifically for AI agents. Every method is self-describing and the SDK can explain its own capabilities.

Discover What the SDK Can Do

// Get a high-level overview of capabilities
const caps = client.describe();
console.log(caps.description);
// "Official SDK for the Unbrowser cloud API. Provides intelligent web
// browsing with learned patterns, API discovery, and progressive optimization."

// List all categories
for (const category of caps.categories) {
  console.log(`${category.name}: ${category.methods.join(', ')}`);
}
// Content Extraction: browse, previewBrowse, browseWithProgress, fetch, batch
// Intelligence: getDomainIntelligence, discoverApis
// Workflows: startRecording, stopRecording, replayWorkflow, ...
// Skill Packs: exportSkillPack, importSkillPack, ...
// Account: getUsage, health

Get Details About Any Method

// Get complete information about a specific method
const info = client.getMethodInfo('browse');
console.log(info.description);
// "Browse a URL and extract its content as markdown, text, or HTML."

console.log(info.parameters);
// [{ name: 'url', type: 'string', required: true, description: '...' }, ...]

console.log(info.example);
// Full code example

console.log(info.useCases);
// ['Extract article content from a news site', 'Scrape product information', ...]

Search for Methods

// Find the right method for your task
const results = client.searchMethods('extract content from webpage');
for (const { method, relevance } of results) {
  if (relevance === 'high') {
    console.log(method); // 'browse'
  }
}

Generate llms.txt

// Generate an llms.txt file for LLM consumption
const llmsTxt = client.generateLlmsTxt();
// Save to file or serve at /llms.txt

Core Methods

browse(url, options?, session?)

Extract content from a URL. Uses tiered rendering for optimal speed:

• Intelligence tier (~50-200ms): Uses learned patterns
• Lightweight tier (~200-500ms): Uses linkedom
• Playwright tier (~2-5s): Full browser for complex pages

const result = await client.browse('https://example.com', {
  contentType: 'markdown',    // 'markdown' | 'text' | 'html'
  includeTables: true,        // Extract tables as structured data
  waitForSelector: '.loaded', // Wait for element before extracting
  verify: {                   // Content verification
    enabled: true,
    mode: 'thorough'          // 'basic' | 'standard' | 'thorough'
  }
});

console.log(result.title);              // Page title
console.log(result.content.markdown);   // Extracted content
console.log(result.tables);             // Structured tables
console.log(result.metadata.tier);      // Which tier was used

batch(urls, options?, session?)

Browse multiple URLs in parallel:

const result = await client.batch([
  'https://example.com/page1',
  'https://example.com/page2',
  'https://example.com/page3'
]);

for (const item of result.results) {
  if (item.success) {
    console.log(`${item.url}: ${item.data?.title}`);
  } else {
    console.log(`${item.url} failed: ${item.error?.message}`);
  }
}

previewBrowse(url, options?)

Preview execution plan without browsing:

const preview = await client.previewBrowse('https://example.com');

console.log(`Expected time: ${preview.estimatedTime.expected}ms`);
console.log(`Confidence: ${preview.confidence.overall}`);
console.log(`Will use: ${preview.plan.tier} tier`);

getDomainIntelligence(domain)

Query learned patterns for a domain:

const intel = await client.getDomainIntelligence('github.com');

console.log(`Known patterns: ${intel.knownPatterns}`);
console.log(`Success rate: ${(intel.successRate * 100).toFixed(0)}%`);
console.log(`Should use session: ${intel.shouldUseSession}`);

discoverApis(domain, options?)

Discover API endpoints via fuzzing:

const result = await client.discoverApis('api.example.com', {
  methods: ['GET'],
  learnPatterns: true
});

console.log(`Discovered ${result.discovered.length} endpoints`);
for (const endpoint of result.discovered) {
  console.log(`  ${endpoint.method} ${endpoint.path}`);
}

Workflow Recording

Record and replay browsing workflows:

// Start recording
const session = await client.startRecording({
  name: 'Extract product pricing',
  description: 'Navigate to product page and extract price',
  domain: 'shop.example.com'
});

// Browse operations are now recorded
await client.browse('https://shop.example.com/product/123');

// Stop and save
const workflow = await client.stopRecording(session.recordingId);
console.log(`Saved workflow: ${workflow.workflowId}`);

// Replay later with different parameters
const results = await client.replayWorkflow(workflow.workflowId, {
  productId: '456'
});

Session Management

Browse with authentication:

const result = await client.browse(
  'https://example.com/dashboard',
  { contentType: 'markdown' },
  {
    cookies: [
      { name: 'session_id', value: 'your-session-token' }
    ],
    localStorage: {
      'auth_token': 'your-auth-token'
    }
  }
);

// Capture new cookies for future requests
const newCookies = result.newCookies;

Error Handling

All errors include recovery guidance:

import { UnbrowserError, isRetryableError } from '@unbrowser/core';

try {
  await client.browse(url);
} catch (error) {
  if (error instanceof UnbrowserError) {
    console.log(`Error: ${error.code} - ${error.message}`);
    console.log(`Suggestion: ${error.recovery.suggestion}`);

    if (error.isRetryable()) {
      console.log(`Retry after: ${error.getRetryDelay()}ms`);
    }

    for (const alt of error.recovery.alternatives || []) {
      console.log(`Alternative: ${alt}`);
    }
  }
}

Error Codes

Code	Description	Retryable
MISSING_API_KEY	API key not provided	No
INVALID_API_KEY	Invalid API key format	No
UNAUTHORIZED	Invalid or expired API key	No
RATE_LIMITED	Too many requests	Yes
TIMEOUT	Request timed out	Yes
CONTENT_BLOCKED	Site blocked access	Yes
CAPTCHA_DETECTED	CAPTCHA detected	Yes
BOT_DETECTED	Bot detection triggered	Yes

Configuration

const client = createUnbrowser({
  // Required
  apiKey: 'ub_live_xxxxx',

  // Optional
  baseUrl: 'https://api.unbrowser.ai',  // API base URL
  timeout: 60000,                        // Request timeout (ms)
  retry: true,                           // Retry failed requests
  maxRetries: 3                          // Max retry attempts
});

Types

All types are fully documented and exported:

import type {
  // Configuration
  UnbrowserConfig,

  // Browse
  BrowseOptions,
  BrowseResult,
  SessionData,
  Cookie,

  // Intelligence
  DomainIntelligence,
  BrowsePreview,
  FuzzDiscoveryResult,

  // Workflows
  SkillPack,
  SkillExportOptions,

  // Errors
  ErrorCode,
  ErrorRecovery,

  // Introspection
  SDKCapabilities,
  MethodInfo,
} from '@unbrowser/core';

Standalone Introspection Functions

These functions are also available without a client instance:

import {
  getCapabilities,
  getMethodInfo,
  listMethods,
  searchMethods,
  getExampleFor,
  generateLlmsTxt,
} from '@unbrowser/core';

// Get SDK capabilities
const caps = getCapabilities();

// Get method info
const info = getMethodInfo('browse');

// Search methods
const results = searchMethods('extract content');

// Get example for use case
const example = getExampleFor('scrape product pages');

// Generate llms.txt
const llmsTxt = generateLlmsTxt();

Resources

• Documentation: https://docs.unbrowser.ai
• API Reference: https://docs.unbrowser.ai/api
• Dashboard: https://unbrowser.ai/dashboard
• Status: https://status.unbrowser.ai

License

MIT