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

Get Started

Core Endpoints

More

Quickstarts

Agent Quickstarts

Developer Guides

Webhooks

Use Cases

Other

Contributing

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