> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-eiyh7n.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Java Agent Quickstart > Canonical Firecrawl Java quickstart for external agents using search, scrape, and interact. # Firecrawl Java Agent Quickstart This is the canonical quickstart for external agents integrating with Firecrawl using the official Java SDK. Generated from SDK source and OpenAPI spec. ## Install Maven: ```xml theme={null} com.firecrawl firecrawl-java 1.12.1 ``` Gradle: ```groovy theme={null} implementation 'com.firecrawl:firecrawl-java:1.12.1' ``` ## Authenticate ```java theme={null} import com.firecrawl.client.FirecrawlClient; FirecrawlClient client = FirecrawlClient.builder() .apiKey("fc-YOUR_API_KEY") .build(); ``` Builder options: | Option | Type | Default | Description | | --------------- | -------------- | ----------------------------------------------------------------- | ---------------------------------------------------------- | | `apiKey` | `String` | `FIRECRAWL_API_KEY` env var or `firecrawl.apiKey` system property | API key. Omit for keyless free tier (rate-limited per IP). | | `apiUrl` | `String` | `"https://api.firecrawl.dev"` | Base URL. Falls back to `FIRECRAWL_API_URL` env var. | | `timeoutMs` | `long` | `300000` (5 min) | Per-request timeout in milliseconds. | | `maxRetries` | `int` | `3` | Max automatic retries for transient failures. | | `backoffFactor` | `double` | `0.5` | Exponential backoff factor for retries. | | `asyncExecutor` | `Executor` | `ForkJoinPool.commonPool()` | Executor for async methods. | | `httpClient` | `OkHttpClient` | — | Custom HTTP client. Overrides `timeoutMs`. | A convenience factory `FirecrawlClient.fromEnv()` reads the API key from the `FIRECRAWL_API_KEY` env var or `firecrawl.apiKey` system property. ## When To Use What * **`search`** — Use when you start with a query and need to discover relevant pages. Returns search results grouped by source type, optionally with scraped content. * **`scrape`** — Use when you already have a URL and want its content. Returns markdown, HTML, structured data, screenshots, or other formats. * **`interact`** — Use when the page needs post-scrape browser actions like clicking, filling forms, or executing code in the browser sandbox. ## Search ### Why use it Search the web and optionally scrape each result in one call. Start here when you have a question or topic but not a specific URL. ### Preferred SDK method ```java theme={null} client.search(query, options) ``` ### Example ```java theme={null} import com.firecrawl.models.SearchOptions; import com.firecrawl.models.SearchData; SearchData results = client.search("firecrawl web scraping API", SearchOptions.builder() .limit(5) .highlights(true) .build() ); for (var item : results.getWeb()) { System.out.println(item.get("url")); } ``` ### Parameters All fields on `SearchOptions` are nullable and optional. | Field | Type | Description | | ------------------- | --------------- | ---------------------------------------------------------------------------- | | `sources` | `List` | Source types: `"web"`, `"news"`, `"images"`, or config maps. | | `categories` | `List` | Filter categories: `"github"`, `"research"`, `"pdf"`. | | `includeDomains` | `List` | Restrict results to these domains. Mutually exclusive with `excludeDomains`. | | `excludeDomains` | `List` | Exclude results from these domains. | | `limit` | `Integer` | Max results to return. | | `tbs` | `String` | Time-based search filter (e.g. `"qdr:d"` for past day). | | `location` | `String` | Geographic location for results. | | `ignoreInvalidURLs` | `Boolean` | Exclude URLs invalid for other Firecrawl endpoints. | | `timeout` | `Integer` | Timeout in milliseconds. | | `highlights` | `Boolean` | Generate query-relevant highlights. Defaults to true. | | `scrapeOptions` | `ScrapeOptions` | Options applied when scraping each result. See Scrape parameters. | | `integration` | `String` | Integration identifier. | An async variant is available: `client.searchAsync(query, options)` returns `CompletableFuture`. ## Scrape ### Why use it Fetch and extract content from a single URL. Use when you have a specific page to read. ### Preferred SDK method ```java theme={null} client.scrape(url, options) ``` ### Example ```java theme={null} import com.firecrawl.models.ScrapeOptions; import com.firecrawl.models.Document; import java.util.List; Document doc = client.scrape("https://example.com", ScrapeOptions.builder() .formats(List.of("markdown", "links")) .onlyMainContent(true) .build() ); System.out.println(doc.getMarkdown()); ``` ### Parameters All fields on `ScrapeOptions` are nullable and optional. | Field | Type | Description | | --------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `formats` | `List` | Output formats. String values: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"screenshot"`, `"json"`, `"audio"`, `"video"`. Object variants also supported for JSON extraction (`JsonFormat`), questions (`QuestionFormat`), highlights (`HighlightsFormat`). | | `headers` | `Map` | Custom HTTP headers. | | `includeTags` | `List` | HTML tags to include exclusively. | | `excludeTags` | `List` | HTML tags to exclude. | | `onlyMainContent` | `Boolean` | Only return main content, excluding navbars/footers. | | `timeout` | `Integer` | Timeout in milliseconds. | | `waitFor` | `Integer` | Delay in ms before fetching content. | | `mobile` | `Boolean` | Emulate a mobile device. | | `parsers` | `List` | File processing parsers (e.g. `"pdf"` or config maps). | | `actions` | `List>` | Browser actions before scraping. Action types: `wait`, `screenshot`, `click`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `pdf`. | | `location` | `LocationConfig` | Geolocation with `country` and `languages`. | | `skipTlsVerification` | `Boolean` | Skip TLS certificate verification. | | `removeBase64Images` | `Boolean` | Remove base64 images from output. | | `blockAds` | `Boolean` | Block ads and cookie popups. | | `proxy` | `String` | Proxy mode: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`. | | `maxAge` | `Long` | Use cached result if younger than this (ms). | | `storeInCache` | `Boolean` | Whether to cache the result. | | `lockdown` | `Boolean` | Serve only cached results. | | `redactPII` | `Boolean` | Redact personally identifiable information. | | `auditMetadata` | `AuditMetadata` | User attribution for SIEM logging with `username`. | | `integration` | `String` | Integration identifier. | An async variant is available: `client.scrapeAsync(url, options)` returns `CompletableFuture`. ## Interact ### Why use it Execute code in the browser sandbox associated with a scrape job. Use after a scrape to click buttons, fill forms, navigate, or extract additional data. ### Preferred SDK method ```java theme={null} client.interact(jobId, code) client.interact(jobId, code, language, timeout) client.interact(jobId, code, language, timeout, origin) ``` ### Example ```java theme={null} import com.firecrawl.models.BrowserExecuteResponse; Document doc = client.scrape("https://example.com", ScrapeOptions.builder().formats(List.of("markdown")).build()); String jobId = (String) doc.getMetadata().get("jobId"); BrowserExecuteResponse result = client.interact( jobId, "document.querySelector('button.load-more')?.click();", "node", 30 ); System.out.println(result.getStdout()); ``` ### Parameters | Parameter | Type | Default | Description | | ---------- | --------- | -------- | -------------------------------------------------------------- | | `jobId` | `String` | — | **Required.** The scrape job ID from a prior scrape. | | `code` | `String` | — | **Required.** Code to execute in the browser sandbox. | | `language` | `String` | `"node"` | Runtime language: `"python"`, `"node"`, or `"bash"`. | | `timeout` | `Integer` | `null` | Execution timeout in seconds (1-300). Default: 30 server-side. | | `origin` | `String` | `null` | Request origin tag. | Async variants are available: `client.interactAsync(...)` returns `CompletableFuture`. ### Related method ```java theme={null} client.stopInteractiveBrowser(jobId) ``` Stops the interactive browser session and returns billing info as `BrowserDeleteResponse`. ## Notes * **Naming style:** All parameters use camelCase. * **Builder pattern:** `ScrapeOptions` and `SearchOptions` use builder pattern (`ScrapeOptions.builder()...build()`). * **Deprecated aliases:** * `scrapeExecute()` → use `interact()` instead. * `deleteScrapeBrowser()` → use `stopInteractiveBrowser()` instead. * **Async methods:** Every sync method has an async counterpart suffixed with `Async` that returns `CompletableFuture`. * **Interact limitations:** The Java SDK's `interact` method requires `code` as a string parameter. Unlike the JS and Python SDKs, it does not support a `prompt` parameter for natural-language browser instructions. ## Source Of Truth * `firecrawl/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java` * `firecrawl/apps/java-sdk/src/main/java/com/firecrawl/models/ScrapeOptions.java` * `firecrawl/apps/java-sdk/src/main/java/com/firecrawl/models/SearchOptions.java` * `firecrawl/apps/java-sdk/build.gradle.kts` * `firecrawl-docs/api-reference/v2-openapi.json`