Firecrawl Java Agent Quickstart

This file is the canonical quickstart for external agents integrating with Firecrawl via the official Java SDK. It is generated from SDK source and the OpenAPI spec.

Install

Maven

<dependency>
  <groupId>com.firecrawl</groupId>
  <artifactId>firecrawl</artifactId>
  <version>1.18.4</version>
</dependency>

Gradle

implementation 'com.firecrawl:firecrawl:1.18.4'

Authenticate

import com.firecrawl.client.FirecrawlClient;

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

Or set the FIRECRAWL_API_KEY environment variable:

FirecrawlClient client = FirecrawlClient.builder().build();

When To Use What

search — Use when you start with a query and need to discover relevant pages. Returns web results, news, images, and optionally scraped page content.
scrape — Use when you already have a URL and want structured page content (markdown, HTML, JSON extraction, screenshots, etc.).
interact — Use when a page needs browser automation after scraping — clicks, form fills, or post-scrape dynamic content extraction.

Search

Why use it

Search the web for a query and get results with titles, URLs, descriptions, and optionally full page content. Supports filtering by domain, time range, category, and source type.

Preferred SDK method

client.search(query, options)

Example

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

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

SearchOptions builder methods (all nullable, default null unless noted):

Method	Type	Description
`sources(List<Object>)`	`List<Object>`	Source types: `"web"`, `"news"`, `"images"`. Default: `["web"]`.
`categories(List<Object>)`	`List<Object>`	Filter by category: `"github"`, `"research"`, `"pdf"`.
`includeDomains(List<String>)`	`List<String>`	Restrict results to these domains. Cannot combine with `excludeDomains`.
`excludeDomains(List<String>)`	`List<String>`	Exclude results from these domains.
`limit(Integer)`	`Integer`	Max results to return. Default: `10` (API). Range: 1–100.
`tbs(String)`	`String`	Time-based filter. E.g. `"qdr:d"` for past day.
`location(String)`	`String`	Location for search results.
`country(String)`	`String`	ISO 3166-1 alpha-2 country code.
`highlights(Boolean)`	`Boolean`	Return query-relevant highlights. Default: `true`.
`timeout(Integer)`	`Integer`	Timeout in milliseconds.
`ignoreInvalidURLs(Boolean)`	`Boolean`	Skip invalid URLs instead of failing.
`scrapeOptions(ScrapeOptions)`	`ScrapeOptions`	Apply scrape options to each result page.
`integration(String)`	`String`	Integration identifier.

Overloads

client.search(query) — Search with defaults.
client.search(query, options) — Search with options.
client.searchAsync(query, options) — Returns CompletableFuture<SearchData>.

Scrape

Why use it

Scrape a URL and get its content in your chosen format — markdown, HTML, JSON (with schema-based extraction), screenshots, and more. Supports browser actions, caching, proxies, and PDF parsing.

Preferred SDK method

client.scrape(url, options)

Example

import com.firecrawl.models.ScrapeOptions;
import com.firecrawl.models.Document;
import java.util.List;

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

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

Parameters

ScrapeOptions builder methods (all nullable, default null unless noted):

Method	Type	Description
`formats(List<Object>)`	`List<Object>`	Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"json"`, `"summary"`, `"audio"`, `"video"`. Also accepts config objects for `json`, `screenshot`, etc. Default: `["markdown"]`.
`onlyMainContent(Boolean)`	`Boolean`	Strip headers, navs, footers. Default: `true` (API).
`includeTags(List<String>)`	`List<String>`	Only include content from these HTML tags.
`excludeTags(List<String>)`	`List<String>`	Exclude content from these HTML tags.
`headers(Map<String, String>)`	`Map<String, String>`	Custom HTTP headers.
`waitFor(Integer)`	`Integer`	Extra delay in ms before fetching content. Default: `0`.
`timeout(Integer)`	`Integer`	Request timeout in ms. Default: 60000, max: 300000.
`mobile(Boolean)`	`Boolean`	Emulate a mobile device. Default: `false`.
`maxAge(Long)`	`Long`	Use cached result if younger than this (ms). Default: 172800000 (2 days).
`storeInCache(Boolean)`	`Boolean`	Cache this scrape result.
`actions(List<Map<String, Object>>)`	`List<Map<String, Object>>`	Browser actions before scraping (wait, click, write, scroll, etc.).
`location(LocationConfig)`	`LocationConfig`	Geolocation: `LocationConfig.builder().country("US").build()`.
`parsers(List<Object>)`	`List<Object>`	File parsers. Default: `["pdf"]`.
`proxy(String)`	`String`	Proxy type: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`.
`skipTlsVerification(Boolean)`	`Boolean`	Skip TLS verification. Default: `true` (API).
`removeBase64Images(Boolean)`	`Boolean`	Strip base64 images from output.
`blockAds(Boolean)`	`Boolean`	Block ads and cookie popups.
`lockdown(Boolean)`	`Boolean`	Serve only cached results.
`checkPromptInjection(Boolean)`	`Boolean`	Scan content for prompt injection (adds 4 credits).
`redactPII(Boolean)`	`Boolean`	Redact PII.
`auditMetadata(AuditMetadata)`	`AuditMetadata`	User attribution for SIEM logging.
`integration(String)`	`String`	Integration identifier.

Overloads

client.scrape(url) — Scrape with defaults.
client.scrape(url, options) — Scrape with options.
client.scrapeAsync(url, options) — Returns CompletableFuture<Document>.

Interact

Why use it

After scraping a page, interact with it in a live browser session — execute code to click buttons, fill forms, navigate, and extract dynamic content.

Preferred SDK method

client.interact(jobId, code)

Example

import com.firecrawl.models.BrowserExecuteResponse;

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

BrowserExecuteResponse response = client.interact(scrapeId, "document.title");
System.out.println(response.getResult());

BrowserExecuteResponse nav = client.interact(scrapeId,
    "document.querySelector('a').click()", "node", 60);
System.out.println(nav.getStdout());

client.stopInteractiveBrowser(scrapeId);

Parameters

Parameter	Type	Description
`jobId`	`String`	The scrape job ID from a previous scrape’s `metadata.scrapeId`. Required.
`code`	`String`	Code to execute in the browser sandbox. Required. Max 100,000 chars.
`language`	`String`	Language: `"python"`, `"node"`, `"bash"`. Default: `"node"`.
`timeout`	`Integer`	Execution timeout in seconds. Min: 1, default: 30 (API), max: 300.
`origin`	`String`	Origin label (auto-set to `"java-sdk@{version}"`).

Overloads

client.interact(jobId, code) — Execute with defaults (language: "node").
client.interact(jobId, code, language, timeout) — Specify language and timeout.
client.interact(jobId, code, language, timeout, origin) — Full control.
All have corresponding interactAsync(...) variants returning CompletableFuture<BrowserExecuteResponse>.

Stopping an interaction

Call client.stopInteractiveBrowser(jobId) to close the browser session and stop billing.

Notes

Deprecated aliases: scrapeExecute → interact, deleteScrapeBrowser → stopInteractiveBrowser. Always use the preferred names.
Parameter naming: All parameters use camelCase (Java convention).
Builder pattern: ScrapeOptions and SearchOptions use the builder pattern.
Package coordinates: com.firecrawl:firecrawl (Maven Central).
Constants: Default API URL: https://api.firecrawl.dev, default timeout: 300,000ms, default max retries: 3.
Note: The Java SDK interact method requires code as a positional parameter. Natural-language prompt-based interaction is not yet supported in the Java SDK — use code to automate browser actions.

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

Get Started

Core Endpoints

More

Quickstarts

Agent Quickstarts

Developer Guides

Webhooks

Use Cases

Other

Contributing

Java Agent Quickstart

Firecrawl Java Agent Quickstart

Install

Maven

Gradle

Authenticate

When To Use What

Search

Why use it

Preferred SDK method

Example

Parameters

Overloads

Scrape

Why use it

Preferred SDK method

Example

Parameters

Overloads

Interact

Why use it

Preferred SDK method

Example

Parameters

Overloads

Stopping an interaction

Notes

Source Of Truth

​Firecrawl Java Agent Quickstart

​Install

​Maven

​Gradle

​Authenticate

​When To Use What

​Search

​Why use it

​Preferred SDK method

​Example

​Parameters

​Overloads

​Scrape

​Why use it

​Preferred SDK method

​Example

​Parameters

​Overloads

​Interact

​Why use it

​Preferred SDK method

​Example

​Parameters

​Overloads

​Stopping an interaction

​Notes

​Source Of Truth

Firecrawl Java Agent Quickstart

Install

Maven

Gradle

Authenticate

When To Use What

Search

Why use it

Preferred SDK method

Example

Parameters

Overloads

Scrape

Why use it

Preferred SDK method

Example

Parameters

Overloads

Interact

Why use it

Preferred SDK method

Example

Parameters

Overloads

Stopping an interaction

Notes

Source Of Truth