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

Getting Started

AI Tools

Agent Harnesses

Agent Quickstarts

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

Return type

Scrape

Why use it

Preferred SDK method

Example

Parameters

Format objects

Interact

Why use it

Preferred SDK method

Example

Parameters

Async variants

Notes

Source Of Truth

​Firecrawl Java Agent Quickstart

​Install

​Authenticate

​When To Use What

​Search

​Why use it

​Preferred SDK method

​Example

​Parameters

​Return type

​Scrape

​Why use it

​Preferred SDK method

​Example

​Parameters

​Format objects

​Interact

​Why use it

​Preferred SDK method

​Example

​Parameters

​Async variants

​Notes

​Source Of Truth

Firecrawl Java Agent Quickstart

Install

Authenticate

When To Use What

Search

Why use it

Preferred SDK method

Example

Parameters

Return type

Scrape

Why use it

Preferred SDK method

Example

Parameters

Format objects

Interact

Why use it

Preferred SDK method

Example

Parameters

Async variants

Notes

Source Of Truth