0
# Firecrawl JavaScript SDK
1

2
JavaScript/TypeScript SDK for the Firecrawl API that enables comprehensive web scraping, crawling, and data extraction with AI-ready output formats.
3

4
## Package Information
5

6
- **Package Name**: @mendable/firecrawl-js
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @mendable/firecrawl-js`
10

11
## Core Imports
12

13
```typescript
14
// Unified client (recommended)
15
import Firecrawl from '@mendable/firecrawl-js';
16

17
// Direct v2 client
18
import { FirecrawlClient } from '@mendable/firecrawl-js';
19

20
// Legacy v1 client
21
import { FirecrawlAppV1 } from '@mendable/firecrawl-js';
22
```
23

24
## Basic Usage
25

26
```typescript
27
// Initialize the client
28
const app = new Firecrawl({ apiKey: 'your-api-key' });
29

30
// Scrape a single URL
31
const scrapeResult = await app.scrape('https://example.com', {
32
  formats: ['markdown', 'html']
33
});
34

35
// Crawl a website
36
const crawlResult = await app.crawl('https://example.com', {
37
  limit: 100,
38
  scrapeOptions: { formats: ['markdown'] }
39
});
40
```
41

42
## Architecture
43

44
The SDK provides both current (v2) and legacy (v1) API access:
45

46
- **Unified Client (`Firecrawl`)**: Extends v2 client with `.v1` property for backward compatibility
47
- **Direct v2 Client (`FirecrawlClient`)**: Current API with modern async patterns
48
- **Legacy v1 Client (`FirecrawlAppV1`)**: Feature-frozen v1 API for existing integrations
49

50
All clients support real-time job monitoring via WebSocket with automatic fallback to polling.
51

52
## Core Types
53

54
```typescript { .api }
55
// Client configuration
56
interface FirecrawlClientOptions {
57
  apiKey?: string | null;
58
  apiUrl?: string | null;
59
  timeoutMs?: number;
60
  maxRetries?: number;
61
  backoffFactor?: number;
62
}
63

64
// Document structure
65
interface Document {
66
  markdown?: string;
67
  html?: string;
68
  rawHtml?: string;
69
  json?: unknown;
70
  summary?: string;
71
  metadata?: DocumentMetadata;
72
  links?: string[];
73
  images?: string[];
74
  screenshot?: string;
75
  attributes?: Array<{
76
    selector: string;
77
    attribute: string;
78
    values: string[];
79
  }>;
80
  actions?: Record<string, unknown>;
81
  warning?: string;
82
  changeTracking?: Record<string, unknown>;
83
}
84

85
// Document metadata
86
interface DocumentMetadata {
87
  title?: string;
88
  description?: string;
89
  language?: string;
90
  keywords?: string | string[];
91
  robots?: string;
92
  ogTitle?: string;
93
  ogDescription?: string;
94
  ogUrl?: string;
95
  ogImage?: string;
96
  sourceURL?: string;
97
  statusCode?: number;
98
  error?: string;
99
  [key: string]: unknown;
100
}
101
```
102

103
## Main Client Classes
104

105
```typescript { .api }
106
// Unified client class
107
class Firecrawl extends FirecrawlClient {
108
  constructor(opts?: FirecrawlClientOptions);
109
  get v1(): FirecrawlAppV1;
110
}
111

112
// Direct v2 client
113
class FirecrawlClient {
114
  constructor(options?: FirecrawlClientOptions);
115
  
116
  // Core methods available - see capability sections below
117
  scrape(url: string, options?: ScrapeOptions): Promise<Document>;
118
  search(query: string, req?: Omit<SearchRequest, "query">): Promise<SearchData>;
119
  map(url: string, options?: MapOptions): Promise<MapData>;
120
  crawl(url: string, req?: CrawlOptions): Promise<CrawlJob>;
121
  batchScrape(urls: string[], opts?: BatchScrapeOptions): Promise<BatchScrapeJob>;
122
  extract(args: any): Promise<ExtractResponse>;
123
  watcher(jobId: string, opts?: WatcherOptions): Watcher;
124
}
125
```
126

127
## Capabilities
128

129
### Web Scraping
130
Single URL scraping with multiple output formats including structured data extraction.
131

132
**Key APIs**:
133
```typescript { .api }
134
scrape(url: string, options?: ScrapeOptions): Promise<Document>;
135
```
136

137
[Web Scraping Documentation](./scraping.md)
138

139
### Web Crawling  
140
Recursive website crawling with configurable limits, path filtering, and webhook support.
141

142
**Key APIs**:
143
```typescript { .api }
144
startCrawl(url: string, req?: CrawlOptions): Promise<CrawlResponse>;
145
getCrawlStatus(jobId: string, pagination?: PaginationConfig): Promise<CrawlJob>;
146
crawl(url: string, req?: CrawlOptions): Promise<CrawlJob>;
147
```
148

149
[Web Crawling Documentation](./crawling.md)
150

151
### Batch Operations
152
Concurrent processing of multiple URLs with job monitoring and error handling.
153

154
**Key APIs**:
155
```typescript { .api }
156
startBatchScrape(urls: string[], opts?: BatchScrapeOptions): Promise<BatchScrapeResponse>;
157
getBatchScrapeStatus(jobId: string, pagination?: PaginationConfig): Promise<BatchScrapeJob>;
158
batchScrape(urls: string[], opts?: BatchScrapeOptions): Promise<BatchScrapeJob>;
159
```
160

161
[Batch Operations Documentation](./batch.md)
162

163
### Search
164
Web search with optional result scraping across different sources (web, news, images).
165

166
**Key APIs**:
167
```typescript { .api }
168
search(query: string, req?: Omit<SearchRequest, "query">): Promise<SearchData>;
169
```
170

171
[Search Documentation](./search.md)
172

173
### Site Mapping
174
Discover and map website URLs using sitemaps and crawling techniques.
175

176
**Key APIs**:
177
```typescript { .api }
178
map(url: string, options?: MapOptions): Promise<MapData>;
179
```
180

181
[Site Mapping Documentation](./mapping.md)
182

183
### Data Extraction
184
LLM-powered structured data extraction using natural language prompts or schemas.
185

186
**Key APIs**:
187
```typescript { .api }
188
startExtract(args: any): Promise<ExtractResponse>;
189
getExtractStatus(jobId: string): Promise<ExtractResponse>;
190
extract(args: any): Promise<ExtractResponse>;
191
```
192

193
[Data Extraction Documentation](./extraction.md)
194

195
### Real-time Monitoring
196
WebSocket-based job monitoring with automatic fallback to polling for long-running operations.
197

198
**Key APIs**:
199
```typescript { .api }
200
watcher(jobId: string, opts?: WatcherOptions): Watcher;
201
```
202

203
[Real-time Monitoring Documentation](./monitoring.md)
204

205
### Usage Analytics
206
Monitor API usage, credits, tokens, and queue status for billing and optimization.
207

208
**Key APIs**:
209
```typescript { .api }
210
getConcurrency(): Promise<ConcurrencyCheck>;
211
getCreditUsage(): Promise<CreditUsage>;
212
getTokenUsage(): Promise<TokenUsage>;
213
getQueueStatus(): Promise<QueueStatusResponse>;
214
```
215

216
[Usage Analytics Documentation](./usage.md)
217

218
### Legacy V1 API
219
Feature-frozen v1 API with additional capabilities like deep research and LLMs.txt generation.
220

221
**Key APIs**:
222
```typescript { .api }
223
// Access via unified client
224
const v1Client = app.v1;
225
```
226

227
[Legacy V1 API Documentation](./v1-api.md)