Java Agent Quickstart

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

Firecrawl Java Agent Quickstart

Canonical quickstart for external agents integrating Firecrawl with Java. Generated from SDK source and OpenAPI spec.

Install

Maven:

<dependency>
  <groupId>com.firecrawl</groupId>
  <artifactId>firecrawl-java</artifactId>
  <version>1.12.1</version>
</dependency>

Gradle:

implementation("com.firecrawl:firecrawl-java:1.12.1")

Authenticate

import com.firecrawl.client.FirecrawlClient;

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

Or read from the FIRECRAWL_API_KEY environment variable:

FirecrawlClient client = FirecrawlClient.fromEnv();

Builder options:

Option	Type	Default
apiKey	String	FIRECRAWL_API_KEY env var or firecrawl.apiKey system property
apiUrl	String	"https://api.firecrawl.dev"
timeoutMs	long	300000 (5 min)
maxRetries	int	3
backoffFactor	double	0.5
asyncExecutor	Executor	ForkJoinPool.commonPool()
httpClient	OkHttpClient	— (overrides timeoutMs)

When To Use What

• search: Start with a query, discover relevant URLs, and get their content in one call.
• scrape: You already have a URL and want its page content as markdown, HTML, JSON, or other formats.
• interact: The page needs clicks, form fills, or post-scrape browser actions on a live session.

Search

Why use it

Search the web for a query and get scraped content from the top results. Combines discovery and content extraction in one call.

Preferred SDK method

client.search(query) or client.search(query, options)

Example

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

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

All fields on SearchOptions are nullable and default to null (API defaults apply).

Parameter	Type	Description
query	String	Required. First positional argument. Search query.
limit	Integer	Max results per source type.
sources	List<Object>	Sources: "web", "news", "images" as strings or {type: "web"} maps.
categories	List<Object>	Categories: "github", "research", "pdf".
includeDomains	List<String>	Restrict to these domains. Cannot combine with excludeDomains.
excludeDomains	List<String>	Exclude these domains. Cannot combine with includeDomains.
tbs	String	Time-based filter (e.g. "qdr:d" past day, "qdr:w" past week).
location	String	Geo-targeting location string.
ignoreInvalidURLs	Boolean	Exclude invalid URLs.
timeout	Integer	Timeout in ms.
highlights	Boolean	Generate query-relevant highlights.
scrapeOptions	ScrapeOptions	Scrape options applied to each result page.
integration	String	Integration identifier.

Response fields: results.getWeb(), results.getNews(), results.getImages() each return List<Map<String, Object>>.

Scrape

Why use it

Get the content of a single URL as markdown, HTML, JSON, screenshots, or other formats.

Preferred SDK method

client.scrape(url) or client.scrape(url, options)

Example

import com.firecrawl.models.Document;
import com.firecrawl.models.ScrapeOptions;

Document result = client.scrape("https://example.com", ScrapeOptions.builder()
    .formats(List.of("markdown", "links"))
    .onlyMainContent(true)
    .build());

System.out.println(result.getMarkdown());

Parameters

All fields on ScrapeOptions are nullable and default to null (API defaults apply).

Parameter	Type	Description
url	String	Required. First positional argument. URL to scrape.
formats	List<Object>	Output formats: "markdown", "html", "rawHtml", "links", "screenshot", "json", "audio", "video". Also accepts format config objects. Default: ["markdown"].
headers	Map<String, String>	Custom HTTP headers.
includeTags	List<String>	HTML tags to include.
excludeTags	List<String>	HTML tags to exclude.
onlyMainContent	Boolean	Strip navbars, footers, boilerplate. Default: true.
timeout	Integer	Timeout in ms. Default: 60000. Min: 1000, Max: 300000.
waitFor	Integer	Extra delay in ms before fetching content.
mobile	Boolean	Emulate a mobile device.
parsers	List<Object>	File processing controls (e.g. "pdf" or {"type":"pdf","maxPages":10}).
actions	List<Map<String, Object>>	Browser actions before content capture.
location	LocationConfig	Geo settings with country and languages.
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 type: "basic", "stealth", "enhanced", "auto". Default: "auto".
maxAge	Long	Cache threshold in ms. Default: 2 days.
storeInCache	Boolean	Store result in cache.
lockdown	Boolean	Cache-only, no outbound requests.
redactPII	Boolean	Redact PII.
auditMetadata	AuditMetadata	SIEM logging with username field.
integration	String	Integration identifier.

Async variant: client.scrapeAsync(url, options) returns CompletableFuture<Document>.

Interact

Why use it

Control a live browser session tied to a scrape job. Execute code in the browser sandbox to click buttons, fill forms, navigate, and extract dynamic content.

Preferred SDK method

client.interact(jobId, code) or client.interact(jobId, code, language, timeout)

Example

import com.firecrawl.models.BrowserExecuteResponse;

Document result = client.scrape("https://www.amazon.com", ScrapeOptions.builder()
    .formats(List.of("markdown"))
    .build());

String scrapeId = (String) result.getMetadata().get("scrapeId");

BrowserExecuteResponse response = client.interact(scrapeId,
    "document.querySelector('input[name=field-keywords]').value = 'iPhone 16 Pro Max'");

client.stopInteractiveBrowser(scrapeId);

Parameters

Parameter	Type	Description
jobId	String	Required. Scrape job ID from result.getMetadata().get("scrapeId").
code	String	Required. Code to execute in the browser sandbox.
language	String	Runtime: "python", "node", "bash". Default: "node".
timeout	Integer	Execution timeout in seconds (1–300). Default: 30.
origin	String	Origin label. Default: "java-sdk@{version}".

Stop the session when done:

client.stopInteractiveBrowser(scrapeId);

Async variants: client.interactAsync(...) and client.stopInteractiveBrowserAsync(...) return CompletableFuture.

Notes

• Parameter names use camelCase (e.g. onlyMainContent, includeTags, scrapeOptions).
• All option classes use the builder pattern: ScrapeOptions.builder().field(value).build().
• The Java interact method requires code — it does not support a prompt parameter. Use the code parameter with JavaScript to control the browser.
• includeDomains and excludeDomains on search are mutually exclusive.
• Deprecated aliases (do not use in new code):
  • scrapeExecute(...) → use interact(...)
  • deleteScrapeBrowser(...) → use stopInteractiveBrowser(...)

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