> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-8bb4v8.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. Canonical Firecrawl Java quickstart for external agents. Aligned with `firecrawl-java` **v1.12.1** (`firecrawl/apps/java-sdk`) and the v2 OpenAPI spec. ## Install Maven: ```xml theme={null} com.firecrawl firecrawl-java 1.12.1 ``` Gradle: ```gradle theme={null} implementation("com.firecrawl:firecrawl-java:1.12.1") ``` ## Authenticate ```java theme={null} import com.firecrawl.client.FirecrawlClient; FirecrawlClient client = FirecrawlClient.builder() .apiKey(System.getenv("FIRECRAWL_API_KEY")) .build(); // Or from environment/system property: // FirecrawlClient client = FirecrawlClient.fromEnv(); ``` ## 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 post-scrape browser actions. ## Search ### Why use it Use search to discover relevant pages from a query, then pick URLs to scrape or interact with. You can constrain results to a site with `site:`, for example `site:docs.firecrawl.dev crawl webhooks`. ### Preferred SDK method `client.search(query)` or `client.search(query, options)` → `SearchData` ### Example ```java theme={null} import com.firecrawl.models.SearchData; import java.util.List; import java.util.Map; SearchData results = client.search("site:docs.firecrawl.dev webhook retries"); List> web = results.getWeb(); ``` ### Parameters | Parameter | Type | Description | | --------------------------- | --------------- | ---------------------------------------------------------------------- | | `query` | `String` | The search query. Use `site:example.com` to limit results to a domain. | | `options.sources` | `List` | Sources to search. Values: `"web"`, `"news"`, `"images"`. | | `options.categories` | `List` | Filter by category. Values: `"github"`, `"research"`, `"pdf"`. | | `options.includeDomains` | `List` | Restrict results to these domains. | | `options.excludeDomains` | `List` | Exclude these domains. | | `options.limit` | `Integer` | Cap results. | | `options.tbs` | `String` | Time-based filter (e.g. `qdr:d`, `qdr:w`). | | `options.location` | `String` | Location string for localized results. | | `options.ignoreInvalidURLs` | `Boolean` | Drop URLs that cannot be scraped. | | `options.timeout` | `Integer` | Request timeout in milliseconds. | | `options.highlights` | `Boolean` | Generate query-relevant highlights. Defaults to true. | | `options.scrapeOptions` | `ScrapeOptions` | Scrape each search result (see Scrape parameters). | **Return value:** `SearchData` with `getWeb()`, `getNews()`, `getImages()` (each `List>`, may be null). Do not treat `SearchData` as a directly iterable list. ## Scrape ### Why use it Use scrape when you already have a URL and want structured content in one or more formats. ### Preferred SDK method `client.scrape(url)` or `client.scrape(url, options)` → `Document` ### Example ```java theme={null} import com.firecrawl.models.ScrapeOptions; import com.firecrawl.models.Document; Document doc = client.scrape( "https://docs.firecrawl.dev", ScrapeOptions.builder().formats(List.of("markdown")).build() ); System.out.println(doc.getMarkdown()); ``` ### Parameters | Parameter | Type | Description | | ----------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `url` | `String` | The URL to scrape. | | `options.formats` | `List` | Output formats. Strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"audio"`, `"video"`. Objects: `JsonFormat.builder().prompt("...").build()`, `QuestionFormat`, `HighlightsFormat`. | | `options.headers` | `Map` | Custom request headers. | | `options.includeTags` | `List` | Include only specific HTML tags. | | `options.excludeTags` | `List` | Exclude specific HTML tags. | | `options.onlyMainContent` | `Boolean` | Strip nav, footer, and other boilerplate. | | `options.timeout` | `Integer` | Timeout in milliseconds. | | `options.waitFor` | `Integer` | Wait for the page to render (milliseconds). | | `options.mobile` | `Boolean` | Use a mobile viewport. | | `options.parsers` | `List` | File parsing controls. Values: `"pdf"`, `Map.of("type", "pdf", "maxPages", 10)`. | | `options.actions` | `List>` | Pre-scrape browser actions. Types: `wait`, `screenshot`, `click`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `pdf`. | | `options.location` | `LocationConfig` | Geo or language-aware scraping. Fields: `country`, `languages`. | | `options.skipTlsVerification` | `Boolean` | Skip TLS verification. | | `options.removeBase64Images` | `Boolean` | Drop base64 images from markdown output. | | `options.blockAds` | `Boolean` | Block ads and cookie popups. | | `options.proxy` | `String` | Proxy mode. Values: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`. | | `options.maxAge` | `Long` | Use cached data up to this age (milliseconds). | | `options.storeInCache` | `Boolean` | Cache the result. | | `options.lockdown` | `Boolean` | Only serve cached results, never make an outbound request. | | `options.redactPII` | `Boolean` | Redact personally identifiable information. | | `options.auditMetadata` | `AuditMetadata` | User attribution for SIEM logging. Constructor arg: `username`. | ## Interact ### Why use it Use interact when a page requires browser actions or code execution after a scrape starts. ### Preferred SDK method * `client.interact(jobId, code)` — uses default language `node` * `client.interact(jobId, code, language, timeout)` — `timeout` in seconds (1–300), null for API default (30s) ### Example ```java theme={null} import com.firecrawl.models.BrowserExecuteResponse; BrowserExecuteResponse result = client.interact( "", "console.log(await page.title());", "node", 60 ); ``` ### Parameters | Parameter | Type | Description | | ---------- | --------- | ------------------------------------------------------------------- | | `jobId` | `String` | Scrape job ID. | | `code` | `String` | Code to run in the browser session. | | `language` | `String` | Runtime. Values: `"python"`, `"node"`, `"bash"`. Default: `"node"`. | | `timeout` | `Integer` | Execution timeout in seconds (1–300). Null for API default. | | `origin` | `String` | Optional origin label for request attribution. | ### Stop session `client.stopInteractiveBrowser(jobId)` → `BrowserDeleteResponse` Ends the scrape-bound browser session. Response includes `isSuccess()`, `getSessionDurationMs()`, `getCreditsBilled()`. ## Notes * The Java SDK exposes code-based interactions only: there is no `prompt` parameter on `interact` (unlike JS, Python, and Rust SDKs). * Deprecated aliases: `scrapeExecute` → `interact`; `deleteScrapeBrowser` → `stopInteractiveBrowser`. * Async variants are available: `scrapeAsync`, `searchAsync`, `interactAsync`, `stopInteractiveBrowserAsync` — all return `CompletableFuture`. * Uses camelCase parameter names matching the Java convention. ## Source Of Truth * `firecrawl/apps/java-sdk/build.gradle.kts` * `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/src/main/java/com/firecrawl/models/Document.java` * `firecrawl-docs/api-reference/v2-openapi.json`