Node.js Source of Truth

​

Install

npm install @mendable/firecrawl-js

​

Authenticate

import Firecrawl from "@mendable/firecrawl-js";

const client = new Firecrawl({
  apiKey: process.env.FIRECRAWL_API_KEY,
  // apiUrl: "https://api.firecrawl.dev" // optional; falls back to FIRECRAWL_API_URL or cloud default
});

​

When To Use What

• search: use when you start with a query and need discovery.
• scrape: use when you already have a URL and want page content.
• interact: use when the page needs clicks, forms, or other browser actions after a scrape has created a session. For multi-step interactive flows, prefer interact over scrape-time actions.

​

Search

​

Why use it

​

Preferred SDK method

​

Simple Example

const results = await client.search("site:docs.firecrawl.dev webhook retries");

​

Complex Example

const results = await client.search("site:docs.firecrawl.dev crawl webhooks", {
  sources: ["web", "news"],
  categories: ["research"],
  limit: 10,
  tbs: "qdr:m",
  location: "San Francisco,California,United States",
  ignoreInvalidURLs: true,
  timeout: 60000,
  scrapeOptions: {
    formats: [
      "markdown",
      "links",
      { type: "json", prompt: "Extract title and key endpoints." }
    ],
    onlyMainContent: true,
    includeTags: ["main", "article"],
    excludeTags: ["nav", "footer"],
    waitFor: 1000
  }
});

​

Return value

• web: web index hits
• news: news hits
• images: image hits

​

Parameters

• query
  • Type: string
  • Use when: you need a search query.
  • Notes: use site:example.com to limit results to a domain.
• options (optional; second argument defaults to {})
  • Type: Omit<SearchRequest, "query">
• options.sources
  • Type: array of source names or typed source objects
  • Use when: you want to control which sources are searched.
  • Confirmed values:
    • "web": web index results
    • "news": news results
    • "images": image results
    • { type: "web" | "news" | "images" }: typed source object form
• options.categories
  • Type: array of category names or typed category objects
  • Use when: you want to filter results by category.
  • Confirmed values:
    • "github": GitHub-focused results
    • "research": research and academic results
    • "pdf": PDF-focused results
    • { type: "github" | "research" | "pdf" }: typed category object form
• options.limit
  • Type: number
  • Use when: you want to cap results.
• options.tbs
  • Type: string
  • Use when: you need a time-based filter (for example qdr:d, qdr:w, sbd:1,qdr:m).
• options.location
  • Type: string
  • Use when: you want localized results.
• options.ignoreInvalidURLs
  • Type: boolean
  • Use when: you want to drop URLs that cannot be scraped by other endpoints.
• options.timeout
  • Type: number
  • Use when: you need a request timeout in milliseconds.
• options.scrapeOptions
  • Type: ScrapeOptions
  • Use when: you want to scrape each search result (see Scrape parameters for fields). The SDK runs the same validation as for scrape (for example plain string "json" in formats is rejected).

​

Scrape

​

Why use it

​

Preferred SDK method

​

Simple Example

const doc = await client.scrape("https://docs.firecrawl.dev", {
  formats: ["markdown"]
});

​

Complex Example

const doc = await client.scrape("https://example.com/pricing", {
  formats: [
    "markdown",
    "links",
    { type: "json", prompt: "Extract plan names and prices." },
    { type: "screenshot", fullPage: true, quality: 80, viewport: { width: 1280, height: 720 } },
    { type: "changeTracking", modes: ["git-diff"], tag: "pricing" },
    { type: "attributes", selectors: [{ selector: "a", attribute: "href" }] }
  ],
  headers: {
    "User-Agent": "FirecrawlDocsBot/1.0"
  },
  onlyMainContent: true,
  waitFor: 1000,
  parsers: [{ type: "pdf", mode: "auto", maxPages: 5 }],
  actions: [
    { type: "click", selector: "#accept" },
    { type: "wait", milliseconds: 750 },
    { type: "scrape" }
  ],
  location: { country: "US", languages: ["en-US"] },
  removeBase64Images: true,
  fastMode: true,
  blockAds: true,
  proxy: "auto",
  maxAge: 86400000,
  minAge: 1,
  storeInCache: true,
  profile: { name: "docs-session", saveChanges: true }
});

​

Parameters

• url
  • Type: string
  • Use when: you want to scrape a specific page.
• options.formats
  • Type: array of format strings or format objects
  • Use when: you want multiple output formats.
  • Plain string formats (the FormatString union also includes "json", but the SDK rejects "json" as a plain string — use a json object below):
    • "markdown": markdown content
    • "html": cleaned HTML
    • "rawHtml": raw HTML
    • "links": page links
    • "images": image URLs
    • "screenshot": screenshot output
    • "summary": summary output
    • "changeTracking": change tracking output (for options like modes, use { type: "changeTracking", modes: [...] } — modes is required on that object in typings)
    • "attributes": attribute extraction (use { type: "attributes", selectors: [...] } when passing selectors)
    • "branding": branding profile output
    • "audio": audio extraction
  • Object-only format types (at minimum type as shown):
    • { type: "json", prompt?: string, schema?: JSON schema or Zod schema }: at least one of prompt or schema is required (SDK validation).
    • { type: "query", prompt: string }: question-answer style extraction.
    • { type: "screenshot", fullPage?, quality?, viewport? }: same options as the string form but as an object.
    • { type: "changeTracking", modes: ("git-diff" | "json")[], schema?, prompt?, tag? }: modes is required.
    • { type: "attributes", selectors: Array<{ selector, attribute }> }
  • Shared object fields where applicable:
    • schema: JSON schema or Zod schema for json, or for changeTracking in json mode (Zod is converted to JSON Schema by the SDK).
    • modes: for changeTracking only: "git-diff" and/or "json".
    • tag: optional change-tracking branch tag.
    • fullPage, quality, viewport: screenshot options.
• options.headers
  • Type: record of string to string
  • Use when: you need custom request headers.
• options.includeTags
  • Type: array of strings
  • Use when: you want to include only specific HTML tags.
• options.excludeTags
  • Type: array of strings
  • Use when: you want to exclude specific HTML tags.
• options.onlyMainContent
  • Type: boolean
  • Use when: you want to strip nav, footer, and other boilerplate.
• options.timeout
  • Type: number
  • Use when: you need a timeout in milliseconds.
• options.waitFor
  • Type: number
  • Use when: you need to wait for the page to render (milliseconds).
• options.mobile
  • Type: boolean
  • Use when: you want a mobile viewport.
• options.parsers
  • Type: array of parser names or parser objects
  • Use when: you need file parsing controls (for example PDF parsing).
  • Confirmed values:
    • "pdf": enable PDF parsing
    • { type: "pdf", mode?: "fast" | "auto" | "ocr", maxPages?: number }: PDF parser options
• options.actions
  • Type: array of action objects
  • Use when: you need lightweight pre-scrape actions.
  • Confirmed action types:
    • wait: milliseconds or selector required
    • screenshot: fullPage, quality, viewport optional
    • click: selector required
    • write: text required (click to focus the input first)
    • press: key required
    • scroll: direction (up or down) required, selector optional
    • scrape: no additional fields
    • executeJavascript: script required
    • pdf: format (A0, A1, A2, A3, A4, A5, A6, Letter, Legal, Tabloid, Ledger), landscape, scale optional
• options.location
  • Type: object with country and languages
  • Use when: you need geo or language-aware scraping.
• options.skipTlsVerification
  • Type: boolean
  • Use when: you need to skip TLS verification.
• options.removeBase64Images
  • Type: boolean
  • Use when: you want to drop base64 images from markdown output.
• options.fastMode
  • Type: boolean
  • Use when: you want faster scrapes with reduced fidelity.
• options.blockAds
  • Type: boolean
  • Use when: you want ad and cookie popup blocking.
• options.proxy
  • Type: string
  • Use when: you need proxy control.
  • Confirmed values:
    • "basic"
    • "stealth"
    • "enhanced"
    • "auto"
    • custom proxy URL string
• options.maxAge
  • Type: number
  • Use when: you want cached data up to a maximum age (milliseconds).
• options.minAge
  • Type: number
  • Use when: you want cached data only if it is at least this old (milliseconds).
• options.storeInCache
  • Type: boolean
  • Use when: you want Firecrawl to cache the result.
• options.profile
  • Type: object with name and optional saveChanges
  • Use when: you want a persistent browser profile shared across scrapes and interactions.

​

Interact

​

Why use it

​

Preferred SDK method

​

Simple Example

const doc = await client.scrape("https://example.com", { formats: ["markdown"] });
const jobId = doc.metadata?.scrapeId;
if (!jobId) throw new Error("Missing scrapeId from scrape response");

const result = await client.interact(jobId, {
  prompt: "Click the pricing tab and summarize the plans."
});

​

Complex Example

const result = await client.interact("<scrapeJobId>", {
  code: "console.log(await page.title());",
  language: "node",
  timeout: 60
});

​

Parameters

• jobId
  • Type: string
  • Use when: you have a scrape job ID from document.metadata.scrapeId.
• args.code
  • Type: string
  • Use when: you want to run code in the browser session (for example Playwright page usage in the node runtime).
• args.prompt
  • Type: string
  • Use when: you want the browser agent to follow a natural-language instruction.
• At least one of args.code or args.prompt must be non-empty (SDK throws otherwise).
• args.language
  • Type: string
  • Use when: you need a specific runtime.
  • Confirmed values: "python", "node", "bash"
  • Default when omitted: "node" (set by the SDK on the request body).
• args.timeout
  • Type: number
  • Use when: you need an execution timeout in seconds.

​

Return value (interact)

• success: boolean
• output: string (aggregated output when present)
• stdout: string
• result: string (alias-style field alongside stdout in typings)
• stderr: string
• exitCode: number
• killed: boolean
• liveViewUrl: string
• interactiveLiveViewUrl: string
• error: string

​

Stop session

• jobId: scrape job id (same id used for interact).
• Response fields in typings include success, sessionDurationMs, creditsBilled, error.

​

Notes

• Deprecated client aliases: scrapeExecute → interact; stopInteractiveBrowser and deleteScrapeBrowser → stopInteraction.
• The default Firecrawl export is the v2 client; v1 remains under client.v1.
• Zod schemas passed to formats (for json or changeTracking) are converted to JSON Schema by the SDK.
• The package declares Node.js >= 22 in engines.

​

Source Of Truth

• firecrawl/apps/js-sdk/firecrawl/package.json (name @mendable/firecrawl-js, version)
• firecrawl/apps/js-sdk/firecrawl/src/index.ts
• firecrawl/apps/js-sdk/firecrawl/src/v2/client.ts
• firecrawl/apps/js-sdk/firecrawl/src/v2/types.ts
• firecrawl/apps/js-sdk/firecrawl/src/v2/utils/validation.ts
• firecrawl/apps/js-sdk/firecrawl/src/v2/methods/search.ts
• firecrawl/apps/js-sdk/firecrawl/src/v2/methods/scrape.ts
• firecrawl-docs/api-reference/v2-openapi.json