> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-qzjftw.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 agents. Generated from SDK source (`firecrawl-java` **v1.17.0**) and the v2 OpenAPI spec. ## Install Maven: ```xml theme={null} com.firecrawl firecrawl-java 1.17.0 ``` Gradle: ```gradle theme={null} implementation("com.firecrawl:firecrawl-java:1.17.0") ``` Requires Java 11+. ## Authenticate ```java theme={null} import com.firecrawl.client.FirecrawlClient; FirecrawlClient client = FirecrawlClient.builder() .apiKey(System.getenv("FIRECRAWL_API_KEY")) .build(); // Or from environment (reads FIRECRAWL_API_KEY env var / firecrawl.apiKey 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 code execution in a scrape-bound browser session. Requires a scrape job ID from a prior scrape. ## Search ### Why use it Discover relevant pages from a query, then pick URLs to scrape or interact with. Constrain results to a site with `site:` in the query string. ### Preferred SDK method * `client.search(query)` → `SearchData` * `client.search(query, options)` → `SearchData` ### Example ```java theme={null} import com.firecrawl.models.SearchOptions; import com.firecrawl.models.ScrapeOptions; import com.firecrawl.models.SearchData; SearchOptions options = SearchOptions.builder() .sources(List.of("web", "news")) .limit(10) .scrapeOptions( ScrapeOptions.builder() .formats(List.of("markdown")) .onlyMainContent(true) .build() ) .build(); SearchData results = client.search("site:docs.firecrawl.dev webhook retries", options); List> web = results.getWeb(); ``` Results are grouped: `getWeb()`, `getNews()`, `getImages()` — each returns `List>` (may be null). ### Parameters | Parameter | Type | Description | | --------------------------- | --------------- | ---------------------------------------------------------- | | `query` | `String` | Search query. Use `site:example.com` to scope to a domain. | | `options.sources` | `List` | Sources: `"web"`, `"news"`, `"images"`. | | `options.categories` | `List` | Filter results: `"github"`, `"research"`, `"pdf"`. | | `options.includeDomains` | `List` | Restrict results to these domains. | | `options.excludeDomains` | `List` | Exclude results from these domains. | | `options.limit` | `Integer` | Max 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). | ## Scrape ### Why use it Get structured content from a URL in one or more formats. ### Preferred SDK method * `client.scrape(url)` → `Document` * `client.scrape(url, options)` → `Document` ### Example ```java theme={null} import com.firecrawl.models.ScrapeOptions; import com.firecrawl.models.JsonFormat; import com.firecrawl.models.Document; ScrapeOptions options = ScrapeOptions.builder() .formats(List.of( "markdown", "links", JsonFormat.builder().prompt("Extract plan names and prices.").build() )) .onlyMainContent(true) .waitFor(1000) .build(); Document doc = client.scrape("https://example.com/pricing", options); 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(...).schema(...).build()`, or `Map.of("type", "screenshot", "fullPage", true)`. | | `options.headers` | `Map` | Custom HTTP headers. | | `options.includeTags` | `List` | Only include content from these HTML tags. | | `options.excludeTags` | `List` | Exclude content from these HTML tags. | | `options.onlyMainContent` | `Boolean` | Strip nav, footer, and boilerplate. | | `options.timeout` | `Integer` | Timeout in milliseconds. | | `options.waitFor` | `Integer` | Wait for page to render (milliseconds). | | `options.mobile` | `Boolean` | Use a mobile viewport. | | `options.parsers` | `List` | File parsers: `"pdf"` or `Map.of("type", "pdf", "maxPages", 5)`. | | `options.actions` | `List>` | Pre-scrape browser actions: `wait`, `click`, `write`, `press`, `scroll`, `screenshot`, `scrape`, `executeJavascript`, `pdf`. | | `options.location` | `LocationConfig` | `LocationConfig.builder().country("US").languages(List.of("en-US")).build()`. | | `options.skipTlsVerification` | `Boolean` | Skip TLS verification. | | `options.removeBase64Images` | `Boolean` | Drop base64 images from markdown. | | `options.blockAds` | `Boolean` | Block ads and cookie popups. | | `options.proxy` | `String` | Proxy mode: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`, or custom URL. | | `options.maxAge` | `Long` | Accept cached data up to this age (milliseconds). | | `options.storeInCache` | `Boolean` | Cache the result. | | `options.lockdown` | `Boolean` | Serve only previously cached results; never make outbound requests. | | `options.redactPII` | `Boolean` | Redact personally identifiable information. | | `options.auditMetadata` | `AuditMetadata` | User attribution for SIEM logging. Has field `username`. | ## Interact ### Why use it Execute code in the browser session tied to a scrape job. The Java SDK supports code-based interactions only (no `prompt` parameter). ### Preferred SDK method * `client.interact(jobId, code)` — uses default language `"node"` * `client.interact(jobId, code, language, timeout)` — `timeout` is seconds (1–300), or null for API default (30s) * `client.interact(jobId, code, language, timeout, origin)` — with optional origin tag ### Example ```java theme={null} import com.firecrawl.models.BrowserExecuteResponse; import com.firecrawl.models.Document; import com.firecrawl.models.ScrapeOptions; Document doc = client.scrape("https://example.com", ScrapeOptions.builder().formats(List.of("markdown")).build()); String jobId = (String) doc.getMetadata().get("scrapeId"); BrowserExecuteResponse result = client.interact( jobId, "console.log(await page.title());", "node", 60 ); System.out.println(result.getStdout()); // Stop the session when done client.stopInteractiveBrowser(jobId); ``` ### Parameters | Parameter | Type | Description | | ---------- | --------- | ------------------------------------------------------------------ | | `jobId` | `String` | Scrape job ID from `document.getMetadata().get("scrapeId")`. | | `code` | `String` | Code to execute in the browser session. | | `language` | `String` | Runtime: `"python"`, `"node"`, `"bash"`. Defaults to `"node"`. | | `timeout` | `Integer` | Execution timeout in seconds (1–300). Null uses API default (30s). | | `origin` | `String` | Optional origin label for request attribution. | `client.stopInteractiveBrowser(jobId)` ends the browser session. Returns `BrowserDeleteResponse` with `isSuccess()`, `getSessionDurationMs()`, `getCreditsBilled()`, `getError()`. ## Notes * Deprecated aliases: `scrapeExecute` → `interact`; `deleteScrapeBrowser` → `stopInteractiveBrowser`. * The Java SDK exposes **code-based interactions only** — there is no `prompt` parameter on `interact` (unlike Node.js, Python, and Rust SDKs). * All methods have async variants (e.g. `scrapeAsync`, `searchAsync`, `interactAsync`) returning `CompletableFuture`. * Uses camelCase for all parameter names (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/SearchData.java` * `firecrawl-docs/api-reference/v2-openapi.json`