> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-1rj1nh.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Node Agent Quickstart > Canonical Firecrawl Node/TypeScript quickstart for external agents using search, scrape, and interact. # Firecrawl Node Agent Quickstart Canonical quickstart for external agents. Generated from SDK source (`@mendable/firecrawl-js`) and the OpenAPI spec. Use this file to get an agent calling Firecrawl correctly in one pass. ## Install ```bash theme={null} npm install @mendable/firecrawl-js ``` Requires Node >= 22. ## Authenticate ```typescript theme={null} import Firecrawl from "@mendable/firecrawl-js"; const app = new Firecrawl("fc-YOUR_API_KEY"); // or read from env automatically: const app = new Firecrawl(); // uses FIRECRAWL_API_KEY env var ``` Constructor accepts a string (API key) or an options object: ```typescript theme={null} const app = new Firecrawl({ apiKey: "fc-...", // optional; falls back to FIRECRAWL_API_KEY apiUrl: "https://...", // optional; falls back to FIRECRAWL_API_URL, then https://api.firecrawl.dev timeoutMs: 30000, // optional; per-request timeout in ms maxRetries: 3, // optional backoffFactor: 0.5, // optional }); ``` No API key is required for `scrape`, `search`, and `interact` — they fall back to a keyless free tier (rate-limited per IP). ## When To Use What * **`search`**: Start with a text query and need to discover relevant URLs and content across the web. * **`scrape`**: Already have a URL and want page content (markdown, HTML, structured JSON, screenshots, etc.). * **`interact`**: The page needs clicks, form fills, or post-scrape browser actions — run code or a prompt against the live browser session. ## Search ### Why use it Search the web and optionally scrape each result. Returns categorized results (web, news, images) with optional content scraping. ### Preferred SDK method ```typescript theme={null} app.search(query, options?) ``` ### Example ```typescript theme={null} const results = await app.search("firecrawl web scraping API", { limit: 5, scrapeOptions: { formats: ["markdown"] }, }); for (const item of results.web ?? []) { console.log(item.url, item.title); } ``` ### Parameters | Parameter | Type | Description | | ------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------- | | `query` | `string` | **Required.** The search query. | | `limit` | `number` | Max number of results. Must be > 0. | | `sources` | `("web" \| "news" \| "images")[]` | Which result sources to include. | | `categories` | `("github" \| "research" \| "pdf" \| "developer")[]` | Narrow web results by category. | | `includeDomains` | `string[]` | Only include results from these domains. Mutually exclusive with `excludeDomains`. | | `excludeDomains` | `string[]` | Exclude results from these domains. | | `tbs` | `string` | Time-based search filter (e.g. `"qdr:d"` for past day, `"qdr:w"` for past week). | | `location` | `string` | Location string for geo-targeting. | | `country` | `string` | ISO 3166-1 alpha-2 country code. | | `ignoreInvalidURLs` | `boolean` | Ignore invalid URLs in results. | | `timeout` | `number` | Timeout in milliseconds. Must be > 0. | | `highlights` | `boolean` | Generate query-relevant highlights. Defaults to `true`. | | `scrapeOptions` | `ScrapeOptions` | Full scrape options applied to each result page. | | `enterprise` | `("default" \| "anon" \| "zdr")[]` | Enterprise options (zero data retention, anonymized search). | | `threatProtection` | `ThreatProtectionOptions` | Enterprise per-request threat protection config. | | `integration` | `string` | Integration identifier. | **Return type**: `SearchData` with properties `.web`, `.news`, `.images`. Accessing `.data` throws with guidance to use the named properties instead. ## Scrape ### Why use it Fetch a single URL and extract content in various formats: markdown, HTML, structured JSON, screenshots, audio, video, and more. Handles JavaScript rendering, ad blocking, proxies, and caching. ### Preferred SDK method ```typescript theme={null} app.scrape(url, options?) ``` ### Example ```typescript theme={null} const doc = await app.scrape("https://example.com", { formats: ["markdown", "links"], onlyMainContent: true, }); console.log(doc.markdown); console.log(doc.links); ``` ### Parameters | Parameter | Type | Description | | --------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `string` | **Required.** The URL to scrape. | | `formats` | `FormatOption[]` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"attributes"`, `"audio"`, `"video"`, `"branding"`, `"product"`, `"menu"`, `"changeTracking"`. Also accepts object forms for `json`, `screenshot`, `changeTracking`, `attributes`, `question`, `highlights`. | | `headers` | `Record` | Custom HTTP headers for the request. | | `includeTags` | `string[]` | HTML tags to include in extraction. | | `excludeTags` | `string[]` | HTML tags to exclude from extraction. | | `onlyMainContent` | `boolean` | Strip boilerplate (nav, footer, etc.). | | `timeout` | `number` | Server-side timeout in milliseconds. | | `waitFor` | `number` | Wait before scraping in milliseconds (for JS rendering). | | `mobile` | `boolean` | Emulate a mobile viewport. | | `parsers` | `(string \| PDFParser)[]` | Parser config (e.g. PDF mode, maxPages, blocks). | | `actions` | `ActionOption[]` | Browser actions: `wait`, `click`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `screenshot`, `pdf`. | | `location` | `LocationConfig` | `{ country?: string, languages?: string[] }` for geo-targeting. | | `skipTlsVerification` | `boolean` | Skip TLS certificate checks. | | `removeBase64Images` | `boolean` | Strip base64-encoded images from output. | | `fastMode` | `boolean` | Enable fast mode (less rendering, faster response). | | `blockAds` | `boolean` | Block ads and cookie popups. | | `proxy` | `string` | Proxy tier: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`, or a custom string. | | `maxAge` | `number` | Max age in ms of cached content. `0` bypasses the cache. | | `storeInCache` | `boolean` | Store the result in Firecrawl's cache. | | `lockdown` | `boolean` | Only serve cached results; never make an outbound request. | | `redactPII` | `boolean \| RedactPIIOptions` | Redact personally identifiable information. | | `threatProtection` | `ThreatProtectionOptions` | Enterprise per-request threat config. | | `auditMetadata` | `{ username: string }` | SIEM logging attribution. | | `profile` | `{ name: string, saveChanges?: boolean }` | Persistent browser profile across sessions. | | `integration` | `string` | Integration identifier. | | `autoResume` | `boolean` | SDK-only. Auto-resume large docs that outlive the request window. Default: `true`. | ## Interact ### Why use it Execute code or a natural-language prompt against the live browser session from a previous scrape. Use it to click buttons, fill forms, navigate, or extract dynamic content that only appears after user interaction. ### Preferred SDK method ```typescript theme={null} app.interact(jobId, options) ``` ### Example ```typescript theme={null} const doc = await app.scrape("https://example.com", { formats: ["markdown"], }); const jobId = doc.metadata?.jobId; const result = await app.interact(jobId, { code: "document.querySelector('button.load-more').click();", language: "node", timeout: 30, }); console.log(result.output); // When done, stop the session: await app.stopInteraction(jobId); ``` ### Parameters | Parameter | Type | Description | | ---------- | ------------------------------ | --------------------------------------------------------------------------------------- | | `jobId` | `string` | **Required.** The scrape job ID from a previous `scrape` call. | | `code` | `string` | Code to execute in the browser sandbox. At least one of `code` or `prompt` is required. | | `prompt` | `string` | Natural-language prompt to execute. At least one of `code` or `prompt` is required. | | `language` | `"python" \| "node" \| "bash"` | Language of the code. Defaults to `"node"`. | | `timeout` | `number` | Execution timeout in seconds. | **Stop the session** when done: ```typescript theme={null} await app.stopInteraction(jobId); ``` ## Notes * All parameter names use **camelCase** (e.g. `onlyMainContent`, `skipTlsVerification`). * `SearchData` uses `.web`, `.news`, `.images` — accessing `.data` throws an error with migration guidance. * **Deprecated aliases** (use the preferred names above): * `scrapeUrl` → `scrape` * `scrapeExecute` → `interact` * `stopInteractiveBrowser` / `deleteScrapeBrowser` → `stopInteraction` * The `QueryFormat` (`{ type: "query", prompt, mode }`) is deprecated in favor of `QuestionFormat` or `HighlightsFormat`. ## Source Of Truth * `firecrawl/apps/js-sdk/firecrawl/src/v2/client.ts` * `firecrawl/apps/js-sdk/firecrawl/src/v2/types.ts` * `firecrawl/apps/js-sdk/firecrawl/src/index.ts` * `firecrawl-docs/api-reference/v2-openapi.json`