Firecrawl Java Agent Quickstart

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

Install

Gradle (Kotlin DSL):

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 use the FIRECRAWL_API_KEY environment variable:

FirecrawlClient client = FirecrawlClient.fromEnv();

Builder options:

Option	Type	Default	Description
`apiKey`	`String`	`null`	API key. Falls back to `FIRECRAWL_API_KEY` env var, then `firecrawl.apiKey` system property, then keyless free tier.
`apiUrl`	`String`	`"https://api.firecrawl.dev"`	Base API URL. Falls back to `FIRECRAWL_API_URL` env var.
`timeoutMs`	`long`	`300000` (5 min)	HTTP request timeout in milliseconds.
`maxRetries`	`int`	`3`	Max retries for failed requests.
`backoffFactor`	`double`	`0.5`	Exponential backoff factor.
`asyncExecutor`	`Executor`	`ForkJoinPool.commonPool()`	Executor for async methods.
`httpClient`	`OkHttpClient`	auto-configured	Fully custom HTTP client.

When To Use What

search: Start with a query and discover relevant pages. Returns URLs, titles, descriptions, and optionally scraped content.
scrape: You already have a URL and want structured page content — markdown, HTML, screenshots, JSON extraction, etc.
interact: The page needs post-scrape browser actions — clicking, typing, or executing code in a live browser session.

Search

Why use it

Discover web pages matching a query. Optionally scrape each result for full content in one call.

Preferred SDK method

client.search(query, options)

Example

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

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

SearchData results = client.search("firecrawl web scraping", SearchOptions.builder()
    .limit(5)
    .build());

for (Map<String, Object> result : results.getWeb()) {
    System.out.println(result.get("title") + " " + result.get("url"));
}

Parameters

SearchOptions.builder() fields:

Parameter	Type	Description
`limit`	`Integer`	Max results per source type.
`sources`	`List<Object>`	Result sources: `"web"`, `"news"`, `"images"` as strings.
`categories`	`List<Object>`	Narrow results: `"github"`, `"research"`, `"pdf"`.
`includeDomains`	`List<String>`	Restrict to these domains.
`excludeDomains`	`List<String>`	Exclude these domains.
`tbs`	`String`	Time-based filter (e.g. `"qdr:d"` for past day).
`location`	`String`	Location string for geo-targeted results.
`ignoreInvalidURLs`	`Boolean`	Skip invalid URLs in results.
`timeout`	`Integer`	Timeout in milliseconds.
`highlights`	`Boolean`	Generate query-relevant highlights. Defaults to `true`.
`scrapeOptions`	`ScrapeOptions`	Scrape each result page. Same builder as the scrape parameters below.
`integration`	`String`	Integration identifier.

Results are accessed via results.getWeb(), results.getNews(), results.getImages(). Each entry is a Map<String, Object>.

Scrape

Why use it

Extract structured content from a single URL — markdown, HTML, screenshots, JSON extraction, audio, video, and more.

Preferred SDK method

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"))
    .build());

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

Parameters

ScrapeOptions.builder() fields:

Parameter	Type	Description
`formats`	`List<Object>`	Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"screenshot"`, `"json"`, `"audio"`, `"video"`, or format objects like `JsonFormat`, `QuestionFormat`, `HighlightsFormat`.
`headers`	`Map<String, String>`	Custom HTTP headers.
`includeTags`	`List<String>`	Only include content from these HTML tags.
`excludeTags`	`List<String>`	Exclude content from these HTML tags.
`onlyMainContent`	`Boolean`	Extract only main content, excluding headers/navs/footers.
`timeout`	`Integer`	Timeout in milliseconds.
`waitFor`	`Integer`	Additional wait in ms before scraping.
`mobile`	`Boolean`	Emulate a mobile device.
`parsers`	`List<Object>`	Parser config: `"pdf"` or `{"type":"pdf","maxPages":10}`.
`actions`	`List<Map<String, Object>>`	Browser actions before scraping.
`location`	`LocationConfig`	Location settings: `.country("US").languages(List.of("en-US"))`.
`skipTlsVerification`	`Boolean`	Skip TLS certificate verification.
`removeBase64Images`	`Boolean`	Remove base64 images from markdown.
`blockAds`	`Boolean`	Block ads and cookie popups.
`proxy`	`String`	Proxy tier: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`.
`maxAge`	`Long`	Max age in ms of cached content.
`storeInCache`	`Boolean`	Store result in Firecrawl cache.
`lockdown`	`Boolean`	Serve only cached results.
`redactPII`	`Boolean`	Redact PII from content.
`auditMetadata`	`AuditMetadata`	User attribution for SIEM logging.
`integration`	`String`	Integration identifier.

Interact

Why use it

Continue interacting with a live browser session after scraping. Execute code in the browser 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';"
    + "document.querySelector('form[role=search]').submit();");

System.out.println(response.getStdout());

client.stopInteractiveBrowser(scrapeId);

Parameters

Parameter	Type	Description
`jobId`	`String`	Scrape job ID. Required. Obtained from `result.getMetadata().get("scrapeId")` of a previous scrape.
`code`	`String`	Code to execute in the browser session. Required.
`language`	`String`	Language for code execution: `"python"`, `"node"`, `"bash"`. Defaults to `"node"`.
`timeout`	`Integer`	Execution timeout in seconds (1-300).
`origin`	`String`	Origin identifier. Auto-set to `"java-sdk@{version}"`.

Call client.stopInteractiveBrowser(jobId) to end the browser session when done. Every sync method has an async variant returning CompletableFuture: interactAsync(...), scrapeAsync(...), searchAsync(...).

Notes

Builder pattern: FirecrawlClient, ScrapeOptions, SearchOptions, and LocationConfig all use Builder classes. Construct via .builder()...build().
camelCase parameters: All options use camelCase (e.g. onlyMainContent, includeTags).
List<Object> for polymorphic fields: formats, sources, and categories accept both strings and structured config objects.
Search results are generic Maps: SearchData.getWeb() returns List<Map<String, Object>> rather than typed model objects. Cast or use Jackson to deserialize individual results.
No prompt for interact: Unlike the Node.js and Python SDKs, the Java SDK’s interact method only supports code, not natural-language prompt.
Deprecated aliases: scrapeExecute -> interact, deleteScrapeBrowser -> stopInteractiveBrowser.

Source Of Truth

SDK source: firecrawl/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java
OpenAPI spec: firecrawl-docs/api-reference/v2-openapi.json

Getting Started

Agent Quickstarts

AI Tools

Agent Harnesses

LLM SDKs and Frameworks

Agent Endpoint

Agentic Debugging

Cookbooks

Java Agent Quickstart

Firecrawl Java Agent Quickstart

Install

Authenticate

When To Use What

Search

Why use it

Preferred SDK method

Example

Parameters

Scrape

Why use it

Preferred SDK method

Example

Parameters

Interact

Why use it

Preferred SDK method

Example

Parameters

Notes

Source Of Truth

​Firecrawl Java Agent Quickstart

​Install

​Authenticate

​When To Use What

​Search

​Why use it

​Preferred SDK method

​Example

​Parameters

​Scrape

​Why use it

​Preferred SDK method

​Example

​Parameters

​Interact

​Why use it

​Preferred SDK method

​Example

​Parameters

​Notes

​Source Of Truth

Firecrawl Java Agent Quickstart

Install

Authenticate

When To Use What

Search

Why use it

Preferred SDK method

Example

Parameters

Scrape

Why use it

Preferred SDK method

Example

Parameters

Interact

Why use it

Preferred SDK method

Example

Parameters

Notes

Source Of Truth