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 Firecrawl via the Java SDK. It is generated from SDK source and OpenAPI spec.

Install

Gradle:

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

Maven:

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

Requires Java 11+.

Authenticate

import com.firecrawl.client.FirecrawlClient;

FirecrawlClient client = FirecrawlClient.builder()
    .apiKey("fc-YOUR_API_KEY")
    .build();

Or from environment variable (FIRECRAWL_API_KEY):

FirecrawlClient client = FirecrawlClient.fromEnv();

Builder options: apiKey (String), apiUrl (String, default "https://api.firecrawl.dev"), timeoutMs (long, default 300000), maxRetries (int, default 3), backoffFactor (double, default 0.5), asyncExecutor (Executor), httpClient (OkHttpClient).

When To Use What

• search: Use when you start with a query and need to discover relevant URLs and their content. Returns results from web, news, and image sources.
• scrape: Use when you already have a specific URL and want its page content in markdown, HTML, JSON, or other formats.
• interact: Use when the page needs post-scrape browser actions like clicking, typing, scrolling, or executing code in a live browser session.

Search

Why use it

Search the web for a query and optionally scrape the results. Returns categorized results from web, news, and image sources with optional content extraction.

Preferred SDK method

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

Example

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("title") + " " + item.get("url"));
}

Parameters

All SearchOptions fields are null by default (omitted from the request body). Use the builder pattern.

Parameter	Type	Description
query	String	The search query (first argument, required).
sources	List<Object>	Sources to search: "web", "news", "images".
categories	List<Object>	Filter by category: "github", "research", "pdf".
includeDomains	List<String>	Restrict results to these domains.
excludeDomains	List<String>	Exclude results from these domains.
limit	Integer	Maximum number of results. Server default: 10.
tbs	String	Time-based search filter (e.g. "qdr:d" for past day).
location	String	Location string for geo-targeted search.
ignoreInvalidURLs	Boolean	Ignore invalid URLs in results.
timeout	Integer	Timeout in milliseconds. Server default: 60000.
highlights	Boolean	Generate query-relevant highlights. Server default: true.
scrapeOptions	ScrapeOptions	Nested scrape configuration applied to each result.
integration	String	Integration identifier.

Return type

SearchData with: getWeb(), getNews(), getImages(). Each returns List<Map<String, Object>>.

Scrape

Why use it

Scrape a single URL and get its content in one or more formats. Supports browser automation, LLM extraction, screenshots, and more.

Preferred SDK method

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

Example

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

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

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

Parameters

All ScrapeOptions fields are null by default (omitted from the request body). Use the builder pattern.

Parameter	Type	Description
url	String	The URL to scrape (first argument, required).
formats	List<Object>	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "json", "audio", "video", or typed objects (JsonFormat, QuestionFormat, HighlightsFormat). Server default: ["markdown"].
onlyMainContent	Boolean	Strip boilerplate, keep main content only. Server default: true.
headers	Map<String, String>	Custom HTTP headers.
includeTags	List<String>	HTML tags to exclusively include.
excludeTags	List<String>	HTML tags to exclude.
timeout	Integer	Timeout in milliseconds. Server default: 60000.
waitFor	Integer	Delay in milliseconds before fetching content.
mobile	Boolean	Emulate mobile device.
parsers	List<Object>	Parser configurations (e.g. "pdf" or Map.of("type", "pdf", "maxPages", 10)).
actions	List<Map<String, Object>>	Browser automation actions as maps.
location	LocationConfig	Location settings: LocationConfig.builder().country("US").languages(List.of("en-US")).build().
skipTlsVerification	Boolean	Skip TLS certificate verification.
removeBase64Images	Boolean	Remove base64 images from markdown. Server default: true.
blockAds	Boolean	Block advertisements. Server default: true.
proxy	String	Proxy mode: "basic", "stealth", "enhanced", "auto". Server default: "auto".
maxAge	Long	Use cached result if younger than this (ms).
storeInCache	Boolean	Cache the result. Server default: true.
lockdown	Boolean	Only serve cached results.
redactPII	Boolean	Redact PII from returned content.
auditMetadata	AuditMetadata	User attribution: new AuditMetadata("username").
integration	String	Integration identifier.

Format objects

Type	Constructor	Description
JsonFormat	JsonFormat.builder().prompt("...").schema(Map.of(...)).build()	LLM-extracted structured JSON.
QuestionFormat	new QuestionFormat("your question")	Ask a question about the page.
HighlightsFormat	new HighlightsFormat("your query")	Find relevant source text.

Interact

Why use it

Execute code in a live browser session tied to a scrape job. Use for post-scrape interactions like clicking buttons, filling forms, or running scripts.

Preferred SDK method

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

Example

import com.firecrawl.models.BrowserExecuteResponse;

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

BrowserExecuteResponse result = client.interact(jobId, "document.title");
System.out.println(result.getStdout());

client.stopInteractiveBrowser(jobId);

Parameters

Parameter	Type	Description
jobId	String	The scrape job ID (required).
code	String	Code to execute in the browser sandbox (required).
language	String	Execution language: "python", "node", "bash". Default: "node".
timeout	Integer	Execution timeout in seconds. Range: 1-300. Server default: 30.
origin	String	Origin identifier. Auto-set to "java-sdk@{version}" if absent.

Use client.stopInteractiveBrowser(jobId) to end the browser session.

Async variants

All three methods have Async variants returning CompletableFuture<T>:

client.scrapeAsync(url, options)
client.searchAsync(query, options)
client.interactAsync(jobId, code, language, timeout, origin)

Notes

• Naming style: All parameters use camelCase. Options use the builder pattern.
• Deprecated aliases: scrapeExecute() is deprecated in favor of interact(). deleteScrapeBrowser() is deprecated in favor of stopInteractiveBrowser().
• No prompt support: Unlike JS/Python/Rust, the Java SDK interact() method only accepts code, not natural-language prompt. Use the code parameter with "bash" language for agent-browser CLI commands.
• Null handling: All option fields use @JsonInclude(NON_NULL), so null fields are omitted from the request body.

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