Java Agent Quickstart

Canonical Firecrawl Java quickstart for external agents using search, scrape, and interact.

Firecrawl Java Agent Quickstart

This file is the canonical quickstart for external agents integrating with Firecrawl via the official Java SDK. It is generated from SDK source and the OpenAPI spec.

Install

Maven

<dependency>
  <groupId>com.firecrawl</groupId>
  <artifactId>firecrawl</artifactId>
  <version>1.18.4</version>
</dependency>

Gradle

implementation 'com.firecrawl:firecrawl:1.18.4'

Authenticate

import com.firecrawl.client.FirecrawlClient;

FirecrawlClient client = FirecrawlClient.builder()
    .apiKey("fc-YOUR-API-KEY")
    .build();

Or set the FIRECRAWL_API_KEY environment variable:

FirecrawlClient client = FirecrawlClient.builder().build();

When To Use What

• search — Use when you start with a query and need to discover relevant pages. Returns web results, news, images, and optionally scraped page content.
• scrape — Use when you already have a URL and want structured page content (markdown, HTML, JSON extraction, screenshots, etc.).
• interact — Use when a page needs browser automation after scraping — clicks, form fills, or post-scrape dynamic content extraction.

Search

Why use it

Search the web for a query and get results with titles, URLs, descriptions, and optionally full page content. Supports filtering by domain, time range, category, and source type.

Preferred SDK method

client.search(query, options)

Example

import com.firecrawl.models.SearchOptions;
import com.firecrawl.models.SearchData;

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

SearchOptions builder methods (all nullable, default null unless noted):

Method	Type	Description
sources(List<Object>)	List<Object>	Source types: "web", "news", "images". Default: ["web"].
categories(List<Object>)	List<Object>	Filter by category: "github", "research", "pdf".
includeDomains(List<String>)	List<String>	Restrict results to these domains. Cannot combine with excludeDomains.
excludeDomains(List<String>)	List<String>	Exclude results from these domains.
limit(Integer)	Integer	Max results to return. Default: 10 (API). Range: 1–100.
tbs(String)	String	Time-based filter. E.g. "qdr:d" for past day.
location(String)	String	Location for search results.
country(String)	String	ISO 3166-1 alpha-2 country code.
highlights(Boolean)	Boolean	Return query-relevant highlights. Default: true.
timeout(Integer)	Integer	Timeout in milliseconds.
ignoreInvalidURLs(Boolean)	Boolean	Skip invalid URLs instead of failing.
scrapeOptions(ScrapeOptions)	ScrapeOptions	Apply scrape options to each result page.
integration(String)	String	Integration identifier.

Overloads

• client.search(query) — Search with defaults.
• client.search(query, options) — Search with options.
• client.searchAsync(query, options) — Returns CompletableFuture<SearchData>.

Scrape

Why use it

Scrape a URL and get its content in your chosen format — markdown, HTML, JSON (with schema-based extraction), screenshots, and more. Supports browser actions, caching, proxies, and PDF parsing.

Preferred SDK method

client.scrape(url, options)

Example

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

ScrapeOptions builder methods (all nullable, default null unless noted):

Method	Type	Description
formats(List<Object>)	List<Object>	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "json", "summary", "audio", "video". Also accepts config objects for json, screenshot, etc. Default: ["markdown"].
onlyMainContent(Boolean)	Boolean	Strip headers, navs, footers. Default: true (API).
includeTags(List<String>)	List<String>	Only include content from these HTML tags.
excludeTags(List<String>)	List<String>	Exclude content from these HTML tags.
headers(Map<String, String>)	Map<String, String>	Custom HTTP headers.
waitFor(Integer)	Integer	Extra delay in ms before fetching content. Default: 0.
timeout(Integer)	Integer	Request timeout in ms. Default: 60000, max: 300000.
mobile(Boolean)	Boolean	Emulate a mobile device. Default: false.
maxAge(Long)	Long	Use cached result if younger than this (ms). Default: 172800000 (2 days).
storeInCache(Boolean)	Boolean	Cache this scrape result.
actions(List<Map<String, Object>>)	List<Map<String, Object>>	Browser actions before scraping (wait, click, write, scroll, etc.).
location(LocationConfig)	LocationConfig	Geolocation: LocationConfig.builder().country("US").build().
parsers(List<Object>)	List<Object>	File parsers. Default: ["pdf"].
proxy(String)	String	Proxy type: "basic", "stealth", "enhanced", "auto".
skipTlsVerification(Boolean)	Boolean	Skip TLS verification. Default: true (API).
removeBase64Images(Boolean)	Boolean	Strip base64 images from output.
blockAds(Boolean)	Boolean	Block ads and cookie popups.
lockdown(Boolean)	Boolean	Serve only cached results.
checkPromptInjection(Boolean)	Boolean	Scan content for prompt injection (adds 4 credits).
redactPII(Boolean)	Boolean	Redact PII.
auditMetadata(AuditMetadata)	AuditMetadata	User attribution for SIEM logging.
integration(String)	String	Integration identifier.

Overloads

• client.scrape(url) — Scrape with defaults.
• client.scrape(url, options) — Scrape with options.
• client.scrapeAsync(url, options) — Returns CompletableFuture<Document>.

Interact

Why use it

After scraping a page, interact with it in a live browser session — execute code to click buttons, fill forms, navigate, and extract dynamic content.

Preferred SDK method

client.interact(jobId, code)

Example

import com.firecrawl.models.BrowserExecuteResponse;

Document doc = client.scrape("https://example.com");
String scrapeId = (String) doc.getMetadata().get("scrapeId");

BrowserExecuteResponse response = client.interact(scrapeId, "document.title");
System.out.println(response.getResult());

BrowserExecuteResponse nav = client.interact(scrapeId,
    "document.querySelector('a').click()", "node", 60);
System.out.println(nav.getStdout());

client.stopInteractiveBrowser(scrapeId);

Parameters

Parameter	Type	Description
jobId	String	The scrape job ID from a previous scrape’s metadata.scrapeId. Required.
code	String	Code to execute in the browser sandbox. Required. Max 100,000 chars.
language	String	Language: "python", "node", "bash". Default: "node".
timeout	Integer	Execution timeout in seconds. Min: 1, default: 30 (API), max: 300.
origin	String	Origin label (auto-set to "java-sdk@{version}").

Overloads

• client.interact(jobId, code) — Execute with defaults (language: "node").
• client.interact(jobId, code, language, timeout) — Specify language and timeout.
• client.interact(jobId, code, language, timeout, origin) — Full control.
• All have corresponding interactAsync(...) variants returning CompletableFuture<BrowserExecuteResponse>.

Stopping an interaction

Call client.stopInteractiveBrowser(jobId) to close the browser session and stop billing.

Notes

• Deprecated aliases: scrapeExecute → interact, deleteScrapeBrowser → stopInteractiveBrowser. Always use the preferred names.
• Parameter naming: All parameters use camelCase (Java convention).
• Builder pattern: ScrapeOptions and SearchOptions use the builder pattern.
• Package coordinates: com.firecrawl:firecrawl (Maven Central).
• Constants: Default API URL: https://api.firecrawl.dev, default timeout: 300,000ms, default max retries: 3.
• Note: The Java SDK interact method requires code as a positional parameter. Natural-language prompt-based interaction is not yet supported in the Java SDK — use code to automate browser actions.

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-docs/api-reference/v2-openapi.json