@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

``bash
npm install @unbrowser/core
`

Quick Start

`typescript
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.

$3

`typescript
// 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
`

$3

`typescript
// 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', ...]
`

$3

`typescript
// 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'
}
}
`

$3

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

Core Methods

$3

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

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

`typescript
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
`

$3

Browse multiple URLs in parallel:

`typescript
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});
}
}
`

$3

Preview execution plan without browsing:

`typescript
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);
`

$3

Query learned patterns for a domain:

`typescript
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});
`

$3

Discover API endpoints via fuzzing:

`typescript
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:

`typescript
// 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:

`typescript
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:

`typescript
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});
}
}
}
`

$3

| 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

`typescript
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:

`typescript
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:

`typescript
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