From 3eadff0a20488d8d42cb31e630a511a5f6038e0f Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 29 Aug 2026 13:16:44 +0000 Subject: [PATCH] Add agent quickstart docs for all SDK languages One canonical quickstart per language (Node.js, Python, Rust, Java, Elixir) covering search, scrape, and interact endpoints with full parameter tables. Generated from SDK source and OpenAPI spec as the source of truth. Co-Authored-By: Claude Opus 4.6 (1M context) Claude-Session: https://claude.ai/code/session_013jLaXhFVwjb5c5ooMEEJMQ --- agent-quickstart/elixir.mdx | 247 +++++++++++++++++++++++++++++++ agent-quickstart/java.mdx | 280 ++++++++++++++++++++++++++++++++++++ agent-quickstart/node.mdx | 243 +++++++++++++++++++++++++++++++ agent-quickstart/python.mdx | 249 ++++++++++++++++++++++++++++++++ agent-quickstart/rust.mdx | 270 ++++++++++++++++++++++++++++++++++ 5 files changed, 1289 insertions(+) create mode 100644 agent-quickstart/elixir.mdx create mode 100644 agent-quickstart/java.mdx create mode 100644 agent-quickstart/node.mdx create mode 100644 agent-quickstart/python.mdx create mode 100644 agent-quickstart/rust.mdx diff --git a/agent-quickstart/elixir.mdx b/agent-quickstart/elixir.mdx new file mode 100644 index 000000000..ccbb58c1d --- /dev/null +++ b/agent-quickstart/elixir.mdx @@ -0,0 +1,247 @@ +--- +title: "Elixir Agent Quickstart" +description: "Canonical Firecrawl Elixir quickstart for external agents using search, scrape, and interact." +--- + +# Firecrawl Elixir Agent Quickstart + +Canonical quickstart for external agents integrating with Firecrawl via the Elixir SDK. Generated from SDK source and OpenAPI spec. + +## Install + +Add to your `mix.exs` dependencies: + +```elixir +defp deps do + [ + {:firecrawl, "~> 1.10"} + ] +end +``` + +Then run: + +```bash +mix deps.get +``` + +## Authenticate + +Set the API key globally in your application config: + +```elixir +config :firecrawl, api_key: "fc-YOUR-API-KEY" +``` + +Or pass it per-request: + +```elixir +Firecrawl.scrape_and_extract_from_url( + [url: "https://example.com"], + api_key: "fc-YOUR-API-KEY" +) +``` + +No API key is required for a keyless free tier (rate-limited per IP). + +All functions accept an optional trailing keyword list for client options: + +| Option | Type | Default | Description | +|---|---|---|---| +| `:api_key` | `string` | Application config | API key | +| `:base_url` | `string` | `"https://api.firecrawl.dev/v2"` | API base URL (for self-hosted) | + +Additional keys are passed through to the underlying `Req` HTTP client. + +## When To Use What + +- **`search_and_scrape`**: Start with a query and need to discover URLs and content. Returns search results from web, news, and image sources. +- **`scrape_and_extract_from_url`**: Already have a URL and want page content as markdown, HTML, screenshots, or structured JSON. +- **`interact_with_scrape_browser_session`**: The page needs clicks, form fills, or post-scrape browser actions. Runs code in a browser session tied to a prior scrape. + +## Search + +### Why use it + +Search the web for a query and optionally scrape each result page. Returns results grouped by source type. + +### Preferred SDK function + +```elixir +Firecrawl.search_and_scrape(params, opts \\ []) +``` + +Bang variant: `Firecrawl.search_and_scrape!(params, opts)` — raises on error. + +### Example + +```elixir +{:ok, response} = Firecrawl.search_and_scrape( + query: "firecrawl web scraping", + limit: 5, + scrape_options: [formats: ["markdown"]] +) + +for result <- response.body["data"]["web"] || [] do + IO.puts("#{result["title"]} #{result["url"]}") +end +``` + +### Parameters + +First argument is a keyword list. `query` is required; all others are optional. + +| Parameter | Type | JSON key | Description | +|---|---|---|---| +| `:query` | `string` | `query` | Search query (required) | +| `:sources` | `list(any)` | `sources` | Sources: `"web"`, `"news"`, `"images"`. Default: `["web"]` | +| `:categories` | `list(any)` | `categories` | Filter results by category | +| `:limit` | `integer` | `limit` | Max results per source | +| `:include_domains` | `list(string)` | `includeDomains` | Restrict to these domains. Cannot combine with `:exclude_domains` | +| `:exclude_domains` | `list(string)` | `excludeDomains` | Exclude these domains | +| `:tbs` | `string` | `tbs` | Time-based filter. `"qdr:d"` = past day, `"qdr:w"` = past week | +| `:location` | `string` | `location` | Location for results, e.g. `"San Francisco,California,United States"` | +| `:country` | `string` | `country` | ISO country code for geo-targeting | +| `:ignore_invalid_urls` | `boolean` | `ignoreInvalidURLs` | Exclude invalid URLs | +| `:timeout` | `integer` | `timeout` | Timeout in ms | +| `:highlights` | `boolean` | `highlights` | Generate query-relevant highlights. Default: `true` | +| `:scrape_options` | `keyword` | `scrapeOptions` | Options for scraping result pages (same shape as scrape parameters below) | +| `:enterprise` | `list(string)` | `enterprise` | Enterprise ZDR options: `"zdr"`, `"anon"` | + +## Scrape + +### Why use it + +Fetch and convert a single URL to markdown, HTML, screenshots, structured JSON, or other formats. Supports browser actions, mobile emulation, caching, and PDF parsing. + +### Preferred SDK function + +```elixir +Firecrawl.scrape_and_extract_from_url(params, opts \\ []) +``` + +Bang variant: `Firecrawl.scrape_and_extract_from_url!(params, opts)` — raises on error. + +### Example + +```elixir +{:ok, response} = Firecrawl.scrape_and_extract_from_url( + url: "https://example.com", + formats: ["markdown", "links"] +) + +IO.puts(response.body["data"]["markdown"]) +``` + +Extract structured data: + +```elixir +{:ok, response} = Firecrawl.scrape_and_extract_from_url( + url: "https://example.com/pricing", + formats: [%{ + "type" => "json", + "prompt" => "Extract pricing tiers", + "schema" => %{"tiers" => [%{"name" => "string", "price" => "string"}]} + }] +) + +IO.inspect(response.body["data"]["json"]) +``` + +### Parameters + +First argument is a keyword list. `url` is required; all others are optional. + +| Parameter | Type | JSON key | Description | +|---|---|---|---| +| `:url` | `string` | `url` | URL to scrape (required) | +| `:formats` | `list(any)` | `formats` | Output formats. Default: `["markdown"]`. Options: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"changeTracking"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Object forms for `json`, `screenshot`, `question`, `highlights` | +| `:headers` | `any` | `headers` | Custom HTTP headers | +| `:include_tags` | `list(string)` | `includeTags` | Only include content from these HTML tags | +| `:exclude_tags` | `list(string)` | `excludeTags` | Exclude content from these HTML tags | +| `:only_main_content` | `boolean` | `onlyMainContent` | Only return main content. Default: `true` | +| `:timeout` | `integer` | `timeout` | Timeout in ms. Range: 1000–300000. Default: 60000 | +| `:wait_for` | `integer` | `waitFor` | Extra delay in ms before fetching | +| `:mobile` | `boolean` | `mobile` | Emulate mobile device | +| `:parsers` | `list(any)` | `parsers` | File parser config (e.g. PDF with `mode`, `max_pages`, `pages`, `blocks`, `page_markers`) | +| `:actions` | `list(any)` | `actions` | Browser actions before grabbing content | +| `:location` | `keyword` | `location` | Geo-location settings | +| `:skip_tls_verification` | `boolean` | `skipTlsVerification` | Skip TLS certificate verification | +| `:remove_base64_images` | `boolean` | `removeBase64Images` | Remove base64 images from markdown | +| `:block_ads` | `boolean` | `blockAds` | Block ads and cookie popups. Default: `true` | +| `:proxy` | `:basic \| :enhanced \| :auto` | `proxy` | Proxy mode. Default: `:auto` | +| `:max_age` | `integer` | `maxAge` | Max cache age in ms. Default: 172800000 (2 days) | +| `:min_age` | `integer` | `minAge` | Cache-only minimum age in ms | +| `:store_in_cache` | `boolean` | `storeInCache` | Store result in Firecrawl cache | +| `:lockdown` | `boolean` | `lockdown` | Serve only from cache | +| `:redact_pii` | `boolean` | `redactPII` | Redact PII from output | +| `:profile` | `keyword` | `profile` | Persistent browser profile | +| `:audit_metadata` | `keyword` | `auditMetadata` | User attribution for SIEM logging. Requires `username: string` | +| `:zero_data_retention` | `boolean` | `zeroDataRetention` | Enable zero data retention | + +## Interact + +### Why use it + +Control a live browser session tied to a prior scrape. Execute code to click buttons, fill forms, navigate, and extract dynamic content. + +### Preferred SDK function + +```elixir +Firecrawl.interact_with_scrape_browser_session(job_id, params, opts \\ []) +``` + +Stop the session: + +```elixir +Firecrawl.stop_interactive_scrape_browser_session(job_id, opts \\ []) +``` + +Bang variants available: `interact_with_scrape_browser_session!`, `stop_interactive_scrape_browser_session!`. + +### Example + +```elixir +{:ok, scrape_response} = Firecrawl.scrape_and_extract_from_url( + url: "https://www.amazon.com", + formats: ["markdown"] +) + +scrape_id = scrape_response.body["data"]["metadata"]["scrapeId"] + +# Execute code in the browser +{:ok, response} = Firecrawl.interact_with_scrape_browser_session(scrape_id, + code: "document.querySelector('h1').textContent" +) + +IO.puts(response.body["stdout"]) + +# Clean up +Firecrawl.stop_interactive_scrape_browser_session(scrape_id) +``` + +### Parameters + +First argument is the `job_id` (string). Second is a keyword list of body parameters. + +| Parameter | Type | JSON key | Description | +|---|---|---|---| +| `:code` | `string` | `code` | Code to execute in the browser sandbox (required) | +| `:language` | `:python \| :node \| :bash` | `language` | Language for code execution. Default: `:node` | +| `:timeout` | `integer` | `timeout` | Execution timeout in seconds | +| `:origin` | `string` | `origin` | Origin label for telemetry | + +## Notes + +- The Elixir SDK is **auto-generated from the OpenAPI spec** (`generate.exs`). Function names directly reflect OpenAPI operation IDs. +- Parameter keys use **snake_case atoms** (e.g. `:only_main_content`, `:include_tags`). The SDK converts them to camelCase JSON keys automatically. +- The Elixir SDK does **not** support `prompt`-based interaction — only `code` execution. To use natural-language prompts, use the Node.js or Python SDK. +- The proxy parameter accepts atoms (`:basic`, `:enhanced`, `:auto`) rather than strings. The `:stealth` proxy mode is not validated by the Elixir SDK. +- All functions return `{:ok, Req.Response.t()}` or `{:error, exception}`. Bang variants (`!` suffix) return the response directly and raise on error. +- No deprecated aliases exist in the Elixir SDK. + +## Source Of Truth + +- `firecrawl/apps/elixir-sdk/lib/firecrawl.ex` +- `firecrawl/apps/elixir-sdk/mix.exs` +- `firecrawl-docs/api-reference/v2-openapi.json` diff --git a/agent-quickstart/java.mdx b/agent-quickstart/java.mdx new file mode 100644 index 000000000..25fb442d9 --- /dev/null +++ b/agent-quickstart/java.mdx @@ -0,0 +1,280 @@ +--- +title: "Java Agent Quickstart" +description: "Canonical Firecrawl Java quickstart for external agents using search, scrape, and interact." +--- + +# Firecrawl Java Agent Quickstart + +Canonical quickstart for external agents integrating with Firecrawl via the Java SDK. Generated from SDK source and OpenAPI spec. + +## Install + +**Gradle:** + +```kotlin +implementation("com.firecrawl:firecrawl-java:1.16.0") +``` + +**Maven:** + +```xml + + com.firecrawl + firecrawl-java + 1.16.0 + +``` + +Requires Java 11+. + +## Authenticate + +```java +import com.firecrawl.client.FirecrawlClient; + +FirecrawlClient client = FirecrawlClient.builder() + .apiKey("fc-YOUR-API-KEY") + .build(); +``` + +Or read from the `FIRECRAWL_API_KEY` environment variable: + +```java +FirecrawlClient client = FirecrawlClient.fromEnv(); +``` + +No API key is required for a keyless free tier (rate-limited per IP). + +| Option | Type | Default | Description | +|---|---|---|---| +| `apiKey` | `String` | `FIRECRAWL_API_KEY` env var or `firecrawl.apiKey` system property | API key | +| `apiUrl` | `String` | `"https://api.firecrawl.dev"` | API base URL. Falls back to `FIRECRAWL_API_URL` env var | +| `timeoutMs` | `long` | `300000` (5 min) | Request timeout in ms | +| `maxRetries` | `int` | `3` | Max automatic retries | +| `backoffFactor` | `double` | `0.5` | Exponential backoff factor | +| `asyncExecutor` | `Executor` | `ForkJoinPool.commonPool()` | Executor for async methods | + +## When To Use What + +- **`search`**: Start with a query and need to discover URLs and content. Returns grouped results from web, news, and image sources. +- **`scrape`**: Already have a URL and want page content as markdown, HTML, screenshots, or structured JSON. +- **`interact`**: The page needs clicks, form fills, or post-scrape browser actions. Runs code in a browser session tied to a prior scrape. + +## Search + +### Why use it + +Search the web for a query and optionally scrape each result page. Returns results grouped by source type (web, news, images). + +### Preferred SDK method + +```java +client.search(query) +client.search(query, options) +``` + +Async: `client.searchAsync(query, options)` returns `CompletableFuture`. + +### Example + +```java +import com.firecrawl.client.FirecrawlClient; +import com.firecrawl.client.models.SearchOptions; +import com.firecrawl.client.models.SearchData; + +FirecrawlClient client = FirecrawlClient.fromEnv(); + +SearchData results = client.search("firecrawl web scraping", + SearchOptions.builder() + .limit(5) + .build() +); + +for (var result : results.getWeb()) { + System.out.println(result.get("title") + " " + result.get("url")); +} +``` + +### Parameters + +Pass `SearchOptions.builder()...build()` as the second argument. All fields are optional. + +| Parameter | Type | Description | +|---|---|---| +| `sources` | `List` | Sources: `"web"`, `"news"`, `"images"`. Default: `["web"]` | +| `categories` | `List` | Filter: `"github"`, `"research"`, `"pdf"` | +| `limit` | `Integer` | Max results per source | +| `includeDomains` | `List` | Restrict to these domains. Cannot combine with `excludeDomains` | +| `excludeDomains` | `List` | Exclude these domains | +| `tbs` | `String` | Time-based filter. `"qdr:d"` = past day, `"qdr:w"` = past week | +| `location` | `String` | Location for results | +| `ignoreInvalidURLs` | `Boolean` | Exclude invalid URLs | +| `timeout` | `Integer` | Timeout in ms | +| `highlights` | `Boolean` | Generate query-relevant highlights. Default: `true` | +| `scrapeOptions` | `ScrapeOptions` | Options applied when scraping each result page | +| `integration` | `String` | Integration identifier | + +## Scrape + +### Why use it + +Fetch and convert a single URL to markdown, HTML, screenshots, structured JSON, or other formats. Supports browser actions, mobile emulation, caching, and PDF parsing. + +### Preferred SDK method + +```java +client.scrape(url) +client.scrape(url, options) +``` + +Async: `client.scrapeAsync(url, options)` returns `CompletableFuture`. + +### Example + +```java +import com.firecrawl.client.FirecrawlClient; +import com.firecrawl.client.models.ScrapeOptions; +import com.firecrawl.client.models.Document; +import java.util.List; + +FirecrawlClient client = FirecrawlClient.fromEnv(); + +Document result = client.scrape("https://example.com", + ScrapeOptions.builder() + .formats(List.of("markdown", "links")) + .build() +); + +System.out.println(result.getMarkdown()); +System.out.println(result.getLinks()); +``` + +Extract structured data: + +```java +import com.firecrawl.client.models.JsonFormat; +import java.util.Map; + +Document result = client.scrape("https://example.com/pricing", + ScrapeOptions.builder() + .formats(List.of( + JsonFormat.builder() + .prompt("Extract pricing tiers") + .schema(Map.of("tiers", List.of(Map.of("name", "string", "price", "string")))) + .build() + )) + .build() +); + +System.out.println(result.getJson()); +``` + +### Parameters + +Pass `ScrapeOptions.builder()...build()` as the second argument. All fields are optional. + +| Parameter | Type | Description | +|---|---|---| +| `formats` | `List` | Output formats. Default: `["markdown"]`. Strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"json"`, `"audio"`, `"video"`. Object forms: `JsonFormat`, `QuestionFormat`, `HighlightsFormat` | +| `headers` | `Map` | Custom HTTP headers | +| `includeTags` | `List` | Only include content from these HTML tags | +| `excludeTags` | `List` | Exclude content from these HTML tags | +| `onlyMainContent` | `Boolean` | Only return main content. Default: `true` | +| `timeout` | `Integer` | Timeout in ms. Range: 1000–300000. Default: 60000 | +| `waitFor` | `Integer` | Extra delay in ms before fetching | +| `mobile` | `Boolean` | Emulate mobile device | +| `parsers` | `List` | File parser config. Use `"pdf"` or a `PdfParser` object with `maxPages`, `pages`, `blocks`, `pageMarkers` | +| `actions` | `List>` | Browser actions before grabbing content | +| `location` | `LocationConfig` | Geo-location: `country` (String), `languages` (List\) | +| `skipTlsVerification` | `Boolean` | Skip TLS certificate verification | +| `removeBase64Images` | `Boolean` | Remove base64 images from markdown | +| `blockAds` | `Boolean` | Block ads and cookie popups. Default: `true` | +| `proxy` | `String` | Proxy mode: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`. Default: `"auto"` | +| `maxAge` | `Long` | Use cached result if younger than this (ms). Default: 172800000 (2 days) | +| `storeInCache` | `Boolean` | Store result in Firecrawl cache | +| `lockdown` | `Boolean` | Serve only from cache | +| `redactPII` | `Boolean` | Redact PII from output | +| `auditMetadata` | `AuditMetadata` | User attribution for SIEM logging. Has `username` (String) | +| `integration` | `String` | Integration identifier | + +## Interact + +### Why use it + +Control a live browser session tied to a prior scrape. Execute code to click buttons, fill forms, navigate, and extract dynamic content. + +### Preferred SDK method + +```java +client.interact(jobId, code) +client.interact(jobId, code, language, timeout) +client.interact(jobId, code, language, timeout, origin) +``` + +Stop the session: + +```java +client.stopInteractiveBrowser(jobId) +``` + +Async variants: `interactAsync(...)`, `stopInteractiveBrowserAsync(...)`. + +### Example + +```java +import com.firecrawl.client.FirecrawlClient; +import com.firecrawl.client.models.*; +import java.util.List; +import java.util.Map; + +FirecrawlClient client = FirecrawlClient.fromEnv(); + +Document result = client.scrape("https://www.amazon.com", + ScrapeOptions.builder() + .formats(List.of("markdown")) + .build() +); + +String scrapeId = (String) ((Map) result.getMetadata()).get("scrapeId"); + +// Execute code in the browser +BrowserExecuteResponse response = client.interact( + scrapeId, + "document.querySelector('input[name=field-keywords]').value = 'iPhone 16 Pro Max'", + "node", + 60 +); +System.out.println(response.getStdout()); + +// Clean up +client.stopInteractiveBrowser(scrapeId); +``` + +### Parameters + +| Parameter | Type | Description | +|---|---|---| +| `jobId` | `String` | Scrape job ID (required) | +| `code` | `String` | Code to execute in the browser sandbox (required) | +| `language` | `String` | Language: `"python"`, `"node"`, `"bash"`. Default: `"node"` | +| `timeout` | `Integer` | Execution timeout in seconds. Range: 1–300. Default: 30 | +| `origin` | `String` | Origin label for telemetry | + +`stopInteractiveBrowser` returns `BrowserDeleteResponse` with `success`, `sessionDurationMs`, `creditsBilled`, `error`. + +## Notes + +- Parameter names use **camelCase** (e.g. `onlyMainContent`, `includeTags`, `skipTlsVerification`). +- The Java SDK does **not** support `prompt`-based interaction — only `code` execution. To use natural-language prompts, use the Node.js or Python SDK. +- The stop method is `stopInteractiveBrowser()`, not `stopInteraction()` (differs from JS/Python/Rust SDKs). +- All sync methods have async counterparts returning `CompletableFuture`. +- **Deprecated aliases** (migrate to the preferred names): + - `scrapeExecute()` → `interact()` + - `deleteScrapeBrowser()` → `stopInteractiveBrowser()` + - `QueryFormat` → use `QuestionFormat` or `HighlightsFormat` + +## Source Of Truth + +- `firecrawl/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java` +- `firecrawl/apps/java-sdk/build.gradle.kts` +- `firecrawl-docs/api-reference/v2-openapi.json` diff --git a/agent-quickstart/node.mdx b/agent-quickstart/node.mdx new file mode 100644 index 000000000..1bf41f871 --- /dev/null +++ b/agent-quickstart/node.mdx @@ -0,0 +1,243 @@ +--- +title: "Node.js Agent Quickstart" +description: "Canonical Firecrawl Node.js quickstart for external agents using search, scrape, and interact." +--- + +# Firecrawl Node.js Agent Quickstart + +Canonical quickstart for external agents integrating with Firecrawl via the Node.js/TypeScript SDK. Generated from SDK source and OpenAPI spec. + +## Install + +```bash +npm install firecrawl +``` + +Requires Node.js 22+. + +## Authenticate + +```typescript +import { Firecrawl } from 'firecrawl'; + +const app = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" }); +``` + +Or set the `FIRECRAWL_API_KEY` environment variable and omit `apiKey`: + +```typescript +const app = new Firecrawl(); +``` + +Constructor accepts an options object or a plain string (treated as the API key). No API key is required for a keyless free tier (rate-limited per IP). + +| Option | Type | Default | Description | +|---|---|---|---| +| `apiKey` | `string` | `FIRECRAWL_API_KEY` env var | API key | +| `apiUrl` | `string` | `"https://api.firecrawl.dev"` | API base URL. Falls back to `FIRECRAWL_API_URL` env var | +| `timeoutMs` | `number` | — | Per-request timeout in milliseconds | +| `maxRetries` | `number` | — | Max automatic retries for transient failures | +| `backoffFactor` | `number` | — | Exponential backoff factor | + +## When To Use What + +- **`search`**: Start with a query and need to discover URLs and content. Returns grouped results from web, news, and image sources. +- **`scrape`**: Already have a URL and want page content as markdown, HTML, screenshots, or structured JSON. +- **`interact`**: The page needs clicks, form fills, or post-scrape browser actions. Runs code or natural-language prompts in a browser session tied to a prior scrape. + +## Search + +### Why use it + +Search the web for a query and optionally scrape each result page. Returns results grouped by source type (web, news, images). + +### Preferred SDK method + +```typescript +app.search(query, options?) +``` + +### Example + +```typescript +const results = await app.search("firecrawl web scraping", { + limit: 5, + scrapeOptions: { formats: ["markdown"] }, +}); + +for (const result of results.web ?? []) { + console.log(result.title, result.url); + if ("markdown" in result) console.log(result.markdown.slice(0, 200)); +} +``` + +### Parameters + +Second argument is an options object. All fields are optional. + +| Parameter | Type | Description | +|---|---|---| +| `sources` | `Array<"web" \| "news" \| "images">` | Sources to search. Default: `["web"]` | +| `categories` | `Array<"github" \| "research" \| "pdf" \| "developer">` | Filter results by category | +| `limit` | `number` | Max results per source | +| `includeDomains` | `string[]` | Restrict to these domains. Cannot combine with `excludeDomains` | +| `excludeDomains` | `string[]` | Exclude these domains. Cannot combine with `includeDomains` | +| `tbs` | `string` | Time-based filter. `"qdr:d"` = past day, `"qdr:w"` = past week, `"qdr:m"` = past month, `"qdr:y"` = past year | +| `location` | `string` | Location for results, e.g. `"San Francisco,California,United States"` | +| `ignoreInvalidURLs` | `boolean` | Exclude URLs that are invalid for other Firecrawl endpoints | +| `timeout` | `number` | Timeout in ms | +| `highlights` | `boolean` | Generate query-relevant highlights. Default: `true` | +| `scrapeOptions` | `ScrapeOptions` | Options applied when scraping each result page (same shape as scrape options below) | +| `enterprise` | `Array<"default" \| "anon" \| "zdr">` | Enterprise zero-data-retention options | +| `threatProtection` | `object` | Per-request threat protection override (enterprise) | +| `integration` | `string` | Integration identifier | +| `origin` | `string` | Origin label for telemetry | + +## Scrape + +### Why use it + +Fetch and convert a single URL to markdown, HTML, screenshots, structured JSON, or other formats. Supports browser actions, mobile emulation, caching, and PDF parsing. + +### Preferred SDK method + +```typescript +app.scrape(url, options?) +``` + +### Example + +```typescript +const result = await app.scrape("https://example.com", { + formats: ["markdown", "links"], +}); + +console.log(result.markdown); +console.log(result.links); +``` + +Extract structured data: + +```typescript +const result = await app.scrape("https://example.com/pricing", { + formats: [{ + type: "json", + prompt: "Extract pricing tiers", + schema: { tiers: [{ name: "string", price: "string" }] }, + }], +}); + +console.log(result.json); +``` + +### Parameters + +Second argument is an options object. All fields are optional. + +| Parameter | Type | Description | +|---|---|---| +| `formats` | `FormatOption[]` | Output formats. Default: `["markdown"]`. Simple strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"changeTracking"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Object forms for `json`, `screenshot`, `changeTracking`, `attributes`, `question`, `highlights` | +| `headers` | `Record` | Custom HTTP headers | +| `includeTags` | `string[]` | Only include content from these HTML tags | +| `excludeTags` | `string[]` | Exclude content from these HTML tags | +| `onlyMainContent` | `boolean` | Only return main content, excluding navs/footers. Default: `true` | +| `timeout` | `number` | Timeout in ms. Range: 1000–300000. Default: 60000 | +| `waitFor` | `number` | Extra delay in ms before fetching content | +| `mobile` | `boolean` | Emulate mobile device | +| `parsers` | `Array` | File parser config. PDF parser supports `mode` (`"fast"`, `"auto"`, `"ocr"`), `maxPages`, `pages`, `blocks`, `pageMarkers` | +| `actions` | `ActionOption[]` | Browser actions before grabbing content. Types: `wait`, `screenshot`, `click`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `pdf` | +| `location` | `{ country?: string, languages?: string[] }` | Geo-location settings. Country default: `"US"` | +| `skipTlsVerification` | `boolean` | Skip TLS certificate verification | +| `removeBase64Images` | `boolean` | Remove base64 images from markdown output | +| `fastMode` | `boolean` | Faster but less accurate scraping | +| `blockAds` | `boolean` | Block ads and cookie popups. Default: `true` | +| `proxy` | `"basic" \| "stealth" \| "enhanced" \| "auto"` | Proxy mode. Default: `"auto"` | +| `maxAge` | `number` | Use cached result if younger than this (ms). Default: 172800000 (2 days). Set to 0 to bypass cache | +| `minAge` | `number` | Cache-only mode. Minimum accepted cache age in ms. Returns 404 on miss | +| `storeInCache` | `boolean` | Store result in Firecrawl cache. Default: `true` | +| `lockdown` | `boolean` | Serve only from cache, never make outbound request | +| `redactPII` | `boolean \| RedactPIIOptions` | Redact PII from output. Pass `true` for defaults or an object with `mode`, `entities`, `replaceStyle` | +| `threatProtection` | `object` | Per-request threat protection override (enterprise) | +| `auditMetadata` | `{ username: string }` | User attribution for SIEM logging (enterprise) | +| `profile` | `{ name: string, saveChanges?: boolean }` | Persistent browser storage profile | +| `integration` | `string` | Integration identifier | +| `origin` | `string` | Origin label for telemetry | + +SDK-only option (not sent to API): + +| Parameter | Type | Description | +|---|---|---| +| `autoResume` | `boolean` | Auto-retry on `processing_continues` for large PDFs. Default: `true`. Max 5 retries / 20 min total | + +## Interact + +### Why use it + +Control a live browser session tied to a prior scrape. Execute code or send natural-language prompts to click buttons, fill forms, navigate, and extract dynamic content. + +### Preferred SDK method + +```typescript +app.interact(jobId, options) +``` + +Stop the session: + +```typescript +app.stopInteraction(jobId) +``` + +### Example + +```typescript +const scrapeResult = await app.scrape("https://www.amazon.com", { + formats: ["markdown"], +}); +const scrapeId = scrapeResult.metadata?.scrapeId; + +// Natural-language prompt +const response = await app.interact(scrapeId, { + prompt: "Search for iPhone 16 Pro Max", +}); +console.log(response.output); + +// Execute code directly +const codeResponse = await app.interact(scrapeId, { + code: "document.querySelector('h1').textContent", + language: "node", +}); +console.log(codeResponse.stdout); + +// Clean up +await app.stopInteraction(scrapeId); +``` + +### Parameters + +| Parameter | Type | Description | +|---|---|---| +| `code` | `string` | Code to execute in the browser sandbox. At least one of `code` or `prompt` is required | +| `prompt` | `string` | Natural-language instruction for the browser agent. At least one of `code` or `prompt` is required | +| `language` | `"python" \| "node" \| "bash"` | Language for code execution. Default: `"node"` | +| `timeout` | `number` | Execution timeout in seconds. Range: 1–300. Default: 30 | +| `origin` | `string` | Origin label for telemetry | + +`stopInteraction` returns `{ success, sessionDurationMs?, creditsBilled?, error? }`. + +## Notes + +- Parameter names use **camelCase** (e.g. `onlyMainContent`, `includeTags`, `skipTlsVerification`). +- The `Firecrawl` class (default export) is the recommended entry point. It extends `FirecrawlClient` (v2) and provides a `.v1` getter for legacy access. +- A plain string can be passed to the constructor instead of an options object — it is treated as the API key. +- **Deprecated aliases** (migrate to the preferred names): + - `scrapeUrl()` → `scrape()` + - `scrapeExecute()` → `interact()` + - `stopInteractiveBrowser()` / `deleteScrapeBrowser()` → `stopInteraction()` + - `QueryFormat` → use `QuestionFormat` or `HighlightsFormat` + +## Source Of Truth + +- `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-docs/api-reference/v2-openapi.json` diff --git a/agent-quickstart/python.mdx b/agent-quickstart/python.mdx new file mode 100644 index 000000000..4d0574f94 --- /dev/null +++ b/agent-quickstart/python.mdx @@ -0,0 +1,249 @@ +--- +title: "Python Agent Quickstart" +description: "Canonical Firecrawl Python quickstart for external agents using search, scrape, and interact." +--- + +# Firecrawl Python Agent Quickstart + +Canonical quickstart for external agents integrating with Firecrawl via the Python SDK. Generated from SDK source and OpenAPI spec. + +## Install + +```bash +pip install firecrawl-py +``` + +## Authenticate + +```python +from firecrawl import Firecrawl + +app = Firecrawl(api_key="fc-YOUR-API-KEY") +``` + +Or set the `FIRECRAWL_API_KEY` environment variable and omit `api_key`: + +```python +app = Firecrawl() +``` + +No API key is required for a keyless free tier (rate-limited per IP). An async client is also available: + +```python +from firecrawl import AsyncFirecrawl + +app = AsyncFirecrawl(api_key="fc-YOUR-API-KEY") +``` + +| Option | Type | Default | Description | +|---|---|---|---| +| `api_key` | `str` | `FIRECRAWL_API_KEY` env var | API key | +| `api_url` | `str` | `"https://api.firecrawl.dev"` | API base URL | +| `timeout` | `float` | `None` | Default request timeout in seconds | +| `max_retries` | `int` | `3` | Max automatic retries | +| `backoff_factor` | `float` | `0.5` | Exponential backoff factor | + +## When To Use What + +- **`search`**: Start with a query and need to discover URLs and content. Returns grouped results from web, news, and image sources. +- **`scrape`**: Already have a URL and want page content as markdown, HTML, screenshots, or structured JSON. +- **`interact`**: The page needs clicks, form fills, or post-scrape browser actions. Runs code or natural-language prompts in a browser session tied to a prior scrape. + +## Search + +### Why use it + +Search the web for a query and optionally scrape each result page. Returns results grouped by source type (web, news, images). + +### Preferred SDK method + +```python +app.search(query, **options) +``` + +### Example + +```python +results = app.search( + "firecrawl web scraping", + limit=5, + scrape_options={"formats": ["markdown"]}, +) + +for result in results.web or []: + print(result.title, result.url) + if hasattr(result, "markdown") and result.markdown: + print(result.markdown[:200]) +``` + +### Parameters + +All parameters after `query` are keyword-only. All are optional. + +| Parameter | Type | Description | +|---|---|---| +| `query` | `str` | Search query (required, first positional argument) | +| `sources` | `list[str \| Source]` | Sources to search: `"web"`, `"news"`, `"images"`. Default: `["web"]` | +| `categories` | `list[str \| Category]` | Filter results: `"github"`, `"research"`, `"pdf"`, `"developer"` | +| `limit` | `int` | Max results per source. Default: 5 | +| `include_domains` | `list[str]` | Restrict to these domains. Cannot combine with `exclude_domains` | +| `exclude_domains` | `list[str]` | Exclude these domains. Cannot combine with `include_domains` | +| `tbs` | `str` | Time-based filter. `"qdr:d"` = past day, `"qdr:w"` = past week, `"qdr:m"` = past month | +| `location` | `str` | Location for results, e.g. `"San Francisco,California,United States"` | +| `ignore_invalid_urls` | `bool` | Exclude URLs invalid for other Firecrawl endpoints | +| `timeout` | `int` | Timeout in ms. Default: 300000 | +| `highlights` | `bool` | Generate query-relevant highlights. Default: `true` | +| `scrape_options` | `ScrapeOptions \| dict` | Options applied when scraping each result page (same shape as scrape parameters below) | +| `enterprise` | `list[str]` | Enterprise zero-data-retention options: `"zdr"`, `"anon"` | +| `threat_protection` | `ThreatProtectionOptions` | Per-request threat protection override (enterprise) | +| `integration` | `str` | Integration identifier | + +## Scrape + +### Why use it + +Fetch and convert a single URL to markdown, HTML, screenshots, structured JSON, or other formats. Supports browser actions, mobile emulation, caching, and PDF parsing. + +### Preferred SDK method + +```python +app.scrape(url, **options) +``` + +### Example + +```python +result = app.scrape( + "https://example.com", + formats=["markdown", "links"], +) + +print(result.markdown) +print(result.links) +``` + +Extract structured data: + +```python +result = app.scrape( + "https://example.com/pricing", + formats=[{ + "type": "json", + "prompt": "Extract pricing tiers", + "schema": {"tiers": [{"name": "string", "price": "string"}]}, + }], +) + +print(result.json) +``` + +### Parameters + +All parameters after `url` are keyword-only. All are optional. + +| Parameter | Type | Description | +|---|---|---| +| `url` | `str` | URL to scrape (required, first positional argument) | +| `formats` | `list[FormatOption]` | Output formats. Default: `["markdown"]`. Simple strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"changeTracking"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Object forms for `json`, `screenshot`, `changeTracking`, `attributes`, `question`, `highlights` | +| `headers` | `dict[str, str]` | Custom HTTP headers | +| `include_tags` | `list[str]` | Only include content from these HTML tags | +| `exclude_tags` | `list[str]` | Exclude content from these HTML tags | +| `only_main_content` | `bool` | Only return main content, excluding navs/footers. Default: `true` | +| `timeout` | `int` | Timeout in ms. Range: 1000–300000. Default: 60000 | +| `wait_for` | `int` | Extra delay in ms before fetching content | +| `mobile` | `bool` | Emulate mobile device | +| `parsers` | `list[str \| PDFParser]` | File parser config. PDF parser supports `mode` (`"fast"`, `"auto"`, `"ocr"`), `max_pages`, `pages`, `blocks`, `page_markers` | +| `actions` | `list[Action]` | Browser actions before grabbing content. Types: `wait`, `screenshot`, `click`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `pdf` | +| `location` | `Location` | Geo-location: `country` (str), `languages` (list[str]). Country default: `"US"` | +| `skip_tls_verification` | `bool` | Skip TLS certificate verification | +| `remove_base64_images` | `bool` | Remove base64 images from markdown output | +| `fast_mode` | `bool` | Faster but less accurate scraping | +| `block_ads` | `bool` | Block ads and cookie popups. Default: `true` | +| `proxy` | `str` | Proxy mode: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`. Default: `"auto"` | +| `max_age` | `int` | Use cached result if younger than this (ms). Default: 172800000 (2 days). Set to 0 to bypass cache | +| `store_in_cache` | `bool` | Store result in Firecrawl cache. Default: `true` | +| `lockdown` | `bool` | Serve only from cache, never make outbound request | +| `threat_protection` | `ThreatProtectionOptions` | Per-request threat protection override (enterprise) | +| `audit_metadata` | `AuditMetadata` | User attribution for SIEM logging. Has `username: str` (max 1024 chars) | +| `profile` | `dict` | Persistent browser storage profile: `name` (str), `save_changes` (bool, optional) | +| `integration` | `str` | Integration identifier | + +SDK-only option (not sent to API): + +| Parameter | Type | Description | +|---|---|---| +| `auto_resume` | `bool` | Auto-retry on `processing_continues` for large PDFs. Default: `true` | + +Additional parameters available through `ScrapeOptions` (e.g. when passed as `scrape_options` in `search`): `min_age`, `redact_pii`. + +## Interact + +### Why use it + +Control a live browser session tied to a prior scrape. Execute code or send natural-language prompts to click buttons, fill forms, navigate, and extract dynamic content. + +### Preferred SDK method + +```python +app.interact(job_id, code=None, *, prompt=None, language="node", timeout=None) +``` + +Stop the session: + +```python +app.stop_interaction(job_id) +``` + +### Example + +```python +scrape_result = app.scrape("https://www.amazon.com", formats=["markdown"]) +scrape_id = scrape_result.metadata.scrape_id + +# Natural-language prompt +response = app.interact(scrape_id, prompt="Search for iPhone 16 Pro Max") +print(response.output) + +# Execute code directly +code_response = app.interact( + scrape_id, + code="document.querySelector('h1').textContent", + language="node", +) +print(code_response.stdout) + +# Clean up +app.stop_interaction(scrape_id) +``` + +### Parameters + +| Parameter | Type | Description | +|---|---|---| +| `job_id` | `str` | Scrape job ID (required, first positional argument) | +| `code` | `str` | Code to execute in the browser sandbox. At least one of `code` or `prompt` is required | +| `prompt` | `str` | Natural-language instruction for the browser agent. At least one of `code` or `prompt` is required | +| `language` | `str` | Language for code execution: `"python"`, `"node"`, `"bash"`. Default: `"node"` | +| `timeout` | `int` | Execution timeout in seconds. Range: 1–300 | +| `origin` | `str` | Origin label for telemetry | + +`stop_interaction` returns a `BrowserDeleteResponse` with `success`, `session_duration_ms`, `credits_billed`, `error`. + +## Notes + +- Parameter names use **snake_case** (e.g. `only_main_content`, `include_tags`, `skip_tls_verification`). +- Format strings in the `formats` list use **camelCase** (e.g. `"rawHtml"`, `"changeTracking"`), matching the API. +- Both sync (`Firecrawl`) and async (`AsyncFirecrawl`) clients are available. +- `FirecrawlApp` and `AsyncFirecrawlApp` are aliases for `Firecrawl` and `AsyncFirecrawl`. +- **Deprecated aliases** (migrate to the preferred names): + - `scrape_url()` → `scrape()` + - `scrape_execute()` → `interact()` + - `stop_interactive_browser()` / `delete_scrape_browser()` → `stop_interaction()` + - `QueryFormat` → use `QuestionFormat` or `HighlightsFormat` + +## Source Of Truth + +- `firecrawl/apps/python-sdk/firecrawl/client.py` +- `firecrawl/apps/python-sdk/firecrawl/v2/client.py` +- `firecrawl/apps/python-sdk/firecrawl/v2/types.py` +- `firecrawl-docs/api-reference/v2-openapi.json` diff --git a/agent-quickstart/rust.mdx b/agent-quickstart/rust.mdx new file mode 100644 index 000000000..0d18eec19 --- /dev/null +++ b/agent-quickstart/rust.mdx @@ -0,0 +1,270 @@ +--- +title: "Rust Agent Quickstart" +description: "Canonical Firecrawl Rust quickstart for external agents using search, scrape, and interact." +--- + +# Firecrawl Rust Agent Quickstart + +Canonical quickstart for external agents integrating with Firecrawl via the Rust SDK. Generated from SDK source and OpenAPI spec. + +## Install + +```bash +cargo add firecrawl +``` + +Or add to `Cargo.toml`: + +```toml +[dependencies] +firecrawl = "2" +``` + +## Authenticate + +```rust +use firecrawl::Client; + +let client = Client::new("fc-YOUR-API-KEY")?; +``` + +For self-hosted instances: + +```rust +let client = Client::new_selfhosted( + "https://your-firecrawl.example.com", + Some("fc-YOUR-API-KEY"), +)?; +``` + +Pass `None` as the API key for keyless free tier (rate-limited per IP). All methods are async and return `Result`. + +## When To Use What + +- **`search`**: Start with a query and need to discover URLs and content. Returns grouped results from web, news, and image sources. +- **`scrape`**: Already have a URL and want page content as markdown, HTML, screenshots, or structured JSON. +- **`interact`**: The page needs clicks, form fills, or post-scrape browser actions. Runs code or natural-language prompts in a browser session tied to a prior scrape. + +## Search + +### Why use it + +Search the web for a query and optionally scrape each result page. Returns results grouped by source type (web, news, images). + +### Preferred SDK method + +```rust +client.search(query, options).await? +``` + +### Example + +```rust +use firecrawl::{Client, SearchOptions}; + +let client = Client::new("fc-YOUR-API-KEY")?; + +let response = client.search("firecrawl web scraping", SearchOptions { + limit: Some(5), + ..Default::default() +}).await?; + +if let Some(web_results) = response.data.web { + for result in web_results { + println!("{:?}", result); + } +} +``` + +Convenience method to search and scrape in one call: + +```rust +let documents = client.search_and_scrape("firecrawl", 5).await?; +for doc in documents { + println!("{}", doc.markdown.unwrap_or_default()); +} +``` + +### Parameters + +The `options` argument accepts `impl Into>`. Pass `None` for defaults. All fields on `SearchOptions` are `Option` and default to `None`. + +| Field | Type | Description | +|---|---|---| +| `limit` | `Option` | Max results per source. Default: 5, max: 20 | +| `sources` | `Option>` | Sources: `Web`, `News`, `Images`. Default: `[Web]` | +| `categories` | `Option>` | Filter: `Github`, `Research`, `Pdf` | +| `include_domains` | `Option>` | Restrict to these domains. Cannot combine with `exclude_domains` | +| `exclude_domains` | `Option>` | Exclude these domains | +| `tbs` | `Option` | Time-based filter. `"qdr:d"` = past day, `"qdr:w"` = past week | +| `location` | `Option` | Location for results | +| `ignore_invalid_urls` | `Option` | Exclude invalid URLs | +| `timeout` | `Option` | Timeout in ms | +| `highlights` | `Option` | Generate query-relevant highlights. Default: `true` | +| `scrape_options` | `Option` | Options applied when scraping each result page | +| `integration` | `Option` | Integration identifier | +| `origin` | `Option` | Auto-set to `"rust-sdk@{version}"` | + +## Scrape + +### Why use it + +Fetch and convert a single URL to markdown, HTML, screenshots, structured JSON, or other formats. Supports browser actions, mobile emulation, caching, and PDF parsing. + +### Preferred SDK method + +```rust +client.scrape(url, options).await? +``` + +### Example + +```rust +use firecrawl::{Client, ScrapeOptions, Format}; + +let client = Client::new("fc-YOUR-API-KEY")?; + +let result = client.scrape("https://example.com", ScrapeOptions { + formats: Some(vec![Format::Markdown, Format::Links]), + ..Default::default() +}).await?; + +println!("{}", result.markdown.unwrap_or_default()); +``` + +Extract structured data with a JSON schema: + +```rust +use serde_json::json; + +let json_value = client.scrape_with_schema( + "https://example.com/pricing", + json!({ "tiers": [{ "name": "string", "price": "string" }] }), + Some("Extract pricing tiers"), +).await?; + +println!("{}", json_value); +``` + +### Parameters + +The `options` argument accepts `impl Into>`. Pass `None` for defaults. All fields are `Option` and default to `None`. + +| Field | Type | Description | +|---|---|---| +| `formats` | `Option>` | Output formats. Default: `[Markdown]`. Variants: `Markdown`, `Html`, `RawHtml`, `Links`, `Images`, `Screenshot`, `Summary`, `ChangeTracking`, `Json`, `Attributes`, `Branding`, `Product`, `Menu`, `Audio`, `Video`, `Question(QuestionFormat)`, `Highlights(HighlightsFormat)` | +| `headers` | `Option>` | Custom HTTP headers | +| `include_tags` | `Option>` | Only include content from these HTML tags | +| `exclude_tags` | `Option>` | Exclude content from these HTML tags | +| `only_main_content` | `Option` | Only return main content. Default: `true` | +| `timeout` | `Option` | Timeout in ms. Range: 1000–300000. Default: 60000 | +| `wait_for` | `Option` | Extra delay in ms before fetching | +| `mobile` | `Option` | Emulate mobile device | +| `parsers` | `Option>` | File parser config (e.g. PDF with `mode`, `max_pages`, `pages`, `blocks`, `page_markers`) | +| `actions` | `Option>` | Browser actions before grabbing content | +| `location` | `Option` | Geo-location: `country`, `languages` | +| `skip_tls_verification` | `Option` | Skip TLS certificate verification | +| `remove_base64_images` | `Option` | Remove base64 images from markdown | +| `fast_mode` | `Option` | Faster but less accurate scraping | +| `block_ads` | `Option` | Block ads and cookie popups. Default: `true` | +| `proxy` | `Option` | Proxy mode: `Basic`, `Stealth`, `Enhanced`, `Auto`. Default: `Auto` | +| `max_age` | `Option` | Max cache age in seconds | +| `min_age` | `Option` | Cache-only minimum age in seconds | +| `store_in_cache` | `Option` | Store result in Firecrawl cache | +| `lockdown` | `Option` | Serve only from cache | +| `redact_pii` | `Option` | Redact PII from output | +| `audit_metadata` | `Option` | User attribution for SIEM logging | +| `profile` | `Option` | Persistent browser profile: `name` (String), `save_changes` (Option\) | +| `integration` | `Option` | Integration identifier | +| `json_options` | `Option` | JSON extraction: `schema`, `system_prompt`, `prompt`, `check_prompt_injection` | +| `screenshot_options` | `Option` | Screenshot config: `full_page`, `quality`, `viewport` | +| `change_tracking_options` | `Option` | Change tracking config | +| `attribute_selectors` | `Option>` | Attribute extraction selectors | +| `origin` | `Option` | Auto-set to `"rust-sdk@{version}"` | + +## Interact + +### Why use it + +Control a live browser session tied to a prior scrape. Execute code or send natural-language prompts to click buttons, fill forms, navigate, and extract dynamic content. + +### Preferred SDK method + +```rust +client.interact(job_id, options).await? +``` + +Stop the session: + +```rust +client.stop_interaction(job_id).await? +``` + +### Example + +```rust +use firecrawl::{Client, ScrapeOptions, ScrapeExecuteOptions, Format}; + +let client = Client::new("fc-YOUR-API-KEY")?; + +let result = client.scrape("https://www.amazon.com", ScrapeOptions { + formats: Some(vec![Format::Markdown]), + ..Default::default() +}).await?; + +let scrape_id = result.metadata + .as_ref() + .and_then(|m| m.get("scrapeId")) + .and_then(|v| v.as_str()) + .expect("scrapeId required"); + +// Natural-language prompt +let response = client.interact(scrape_id, ScrapeExecuteOptions { + prompt: Some("Search for iPhone 16 Pro Max".into()), + ..Default::default() +}).await?; +println!("{}", response.output.unwrap_or_default()); + +// Execute code directly +let code_response = client.interact(scrape_id, ScrapeExecuteOptions { + code: Some("document.querySelector('h1').textContent".into()), + ..Default::default() +}).await?; +println!("{}", code_response.stdout.unwrap_or_default()); + +// Clean up +client.stop_interaction(scrape_id).await?; +``` + +### Parameters + +`ScrapeExecuteOptions` struct. All fields are `Option` and default to `None`. + +| Field | Type | Description | +|---|---|---| +| `code` | `Option` | Code to execute in the browser sandbox. At least one of `code` or `prompt` required | +| `prompt` | `Option` | Natural-language instruction for the browser agent. At least one of `code` or `prompt` required | +| `language` | `Option` | Runtime: `Python`, `Node`, `Bash`. Default: `Node` | +| `timeout` | `Option` | Execution timeout in seconds. Range: 1–300 | +| `origin` | `Option` | Auto-set to `"rust-sdk@{version}"` | + +`stop_interaction` returns `ScrapeBrowserDeleteResponse` with `success`, `session_duration_ms`, `credits_billed`, `error`. + +## Notes + +- Field names use **snake_case** (e.g. `only_main_content`, `include_tags`, `skip_tls_verification`). +- All options structs derive `Default`, so use `..Default::default()` for fields you don't set. +- The `origin` field is automatically set to `"rust-sdk@{version}"` on `scrape`, `search`, and `interact` calls. +- JSON extraction has a convenience method: `scrape_with_schema(url, schema, prompt)`. +- **Deprecated aliases** (migrate to the preferred names): + - `scrape_execute()` → `interact()` + - `stop_interactive_browser()` / `delete_scrape_browser()` → `stop_interaction()` + - `Format::Query(QueryFormat)` → use `Format::Question` or `Format::Highlights` + +## Source Of Truth + +- `firecrawl/apps/rust-sdk/src/v2/client.rs` +- `firecrawl/apps/rust-sdk/src/v2/search.rs` +- `firecrawl/apps/rust-sdk/src/v2/scrape.rs` +- `firecrawl/apps/rust-sdk/Cargo.toml` +- `firecrawl-docs/api-reference/v2-openapi.json`