Java Agent Quickstart

Canonical Firecrawl Java quickstart for agents. Generated from SDK source (firecrawl-java v1.17.0) and the v2 OpenAPI spec.

Install

Maven:

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

Gradle:

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

Requires Java 11+.

Authenticate

import com.firecrawl.client.FirecrawlClient;

FirecrawlClient client = FirecrawlClient.builder()
    .apiKey(System.getenv("FIRECRAWL_API_KEY"))
    .build();

// Or from environment (reads FIRECRAWL_API_KEY env var / firecrawl.apiKey system property):
// FirecrawlClient client = FirecrawlClient.fromEnv();

When To Use What

search: use when you start with a query and need discovery.
scrape: use when you already have a URL and want page content.
interact: use when the page needs code execution in a scrape-bound browser session. Requires a scrape job ID from a prior scrape.

Search

Why use it

Discover relevant pages from a query, then pick URLs to scrape or interact with. Constrain results to a site with site: in the query string.

Preferred SDK method

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

Example

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

SearchOptions options = SearchOptions.builder()
    .sources(List.of("web", "news"))
    .limit(10)
    .scrapeOptions(
        ScrapeOptions.builder()
            .formats(List.of("markdown"))
            .onlyMainContent(true)
            .build()
    )
    .build();

SearchData results = client.search("site:docs.firecrawl.dev webhook retries", options);
List<Map<String, Object>> web = results.getWeb();

Results are grouped: getWeb(), getNews(), getImages() — each returns List<Map<String, Object>> (may be null).

Parameters

Parameter	Type	Description
`query`	`String`	Search query. Use `site:example.com` to scope to a domain.
`options.sources`	`List<Object>`	Sources: `"web"`, `"news"`, `"images"`.
`options.categories`	`List<Object>`	Filter results: `"github"`, `"research"`, `"pdf"`.
`options.includeDomains`	`List<String>`	Restrict results to these domains.
`options.excludeDomains`	`List<String>`	Exclude results from these domains.
`options.limit`	`Integer`	Max results.
`options.tbs`	`String`	Time-based filter (e.g. `qdr:d`, `qdr:w`).
`options.location`	`String`	Location string for localized results.
`options.ignoreInvalidURLs`	`Boolean`	Drop URLs that cannot be scraped.
`options.timeout`	`Integer`	Request timeout in milliseconds.
`options.highlights`	`Boolean`	Generate query-relevant highlights. Defaults to `true`.
`options.scrapeOptions`	`ScrapeOptions`	Scrape each search result (see Scrape parameters).

Scrape

Why use it

Get structured content from a URL in one or more formats.

Preferred SDK method

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

Example

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

ScrapeOptions options = ScrapeOptions.builder()
    .formats(List.of(
        "markdown",
        "links",
        JsonFormat.builder().prompt("Extract plan names and prices.").build()
    ))
    .onlyMainContent(true)
    .waitFor(1000)
    .build();

Document doc = client.scrape("https://example.com/pricing", options);
System.out.println(doc.getMarkdown());

Parameters

Parameter	Type	Description
`url`	`String`	The URL to scrape.
`options.formats`	`List<Object>`	Output formats. Strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"audio"`, `"video"`. Objects: `JsonFormat.builder().prompt(...).schema(...).build()`, or `Map.of("type", "screenshot", "fullPage", true)`.
`options.headers`	`Map<String, String>`	Custom HTTP headers.
`options.includeTags`	`List<String>`	Only include content from these HTML tags.
`options.excludeTags`	`List<String>`	Exclude content from these HTML tags.
`options.onlyMainContent`	`Boolean`	Strip nav, footer, and boilerplate.
`options.timeout`	`Integer`	Timeout in milliseconds.
`options.waitFor`	`Integer`	Wait for page to render (milliseconds).
`options.mobile`	`Boolean`	Use a mobile viewport.
`options.parsers`	`List<Object>`	File parsers: `"pdf"` or `Map.of("type", "pdf", "maxPages", 5)`.
`options.actions`	`List<Map<String, Object>>`	Pre-scrape browser actions: `wait`, `click`, `write`, `press`, `scroll`, `screenshot`, `scrape`, `executeJavascript`, `pdf`.
`options.location`	`LocationConfig`	`LocationConfig.builder().country("US").languages(List.of("en-US")).build()`.
`options.skipTlsVerification`	`Boolean`	Skip TLS verification.
`options.removeBase64Images`	`Boolean`	Drop base64 images from markdown.
`options.blockAds`	`Boolean`	Block ads and cookie popups.
`options.proxy`	`String`	Proxy mode: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`, or custom URL.
`options.maxAge`	`Long`	Accept cached data up to this age (milliseconds).
`options.storeInCache`	`Boolean`	Cache the result.
`options.lockdown`	`Boolean`	Serve only previously cached results; never make outbound requests.
`options.redactPII`	`Boolean`	Redact personally identifiable information.
`options.auditMetadata`	`AuditMetadata`	User attribution for SIEM logging. Has field `username`.

Interact

Why use it

Execute code in the browser session tied to a scrape job. The Java SDK supports code-based interactions only (no prompt parameter).

Preferred SDK method

client.interact(jobId, code) — uses default language "node"
client.interact(jobId, code, language, timeout) — timeout is seconds (1–300), or null for API default (30s)
client.interact(jobId, code, language, timeout, origin) — with optional origin tag

Example

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

Document doc = client.scrape("https://example.com",
    ScrapeOptions.builder().formats(List.of("markdown")).build());
String jobId = (String) doc.getMetadata().get("scrapeId");

BrowserExecuteResponse result = client.interact(
    jobId,
    "console.log(await page.title());",
    "node",
    60
);
System.out.println(result.getStdout());

// Stop the session when done
client.stopInteractiveBrowser(jobId);

Parameters

Parameter	Type	Description
`jobId`	`String`	Scrape job ID from `document.getMetadata().get("scrapeId")`.
`code`	`String`	Code to execute in the browser session.
`language`	`String`	Runtime: `"python"`, `"node"`, `"bash"`. Defaults to `"node"`.
`timeout`	`Integer`	Execution timeout in seconds (1–300). Null uses API default (30s).
`origin`	`String`	Optional origin label for request attribution.

client.stopInteractiveBrowser(jobId) ends the browser session. Returns BrowserDeleteResponse with isSuccess(), getSessionDurationMs(), getCreditsBilled(), getError().

Notes

Deprecated aliases: scrapeExecute → interact; deleteScrapeBrowser → stopInteractiveBrowser.
The Java SDK exposes code-based interactions only — there is no prompt parameter on interact (unlike Node.js, Python, and Rust SDKs).
All methods have async variants (e.g. scrapeAsync, searchAsync, interactAsync) returning CompletableFuture.
Uses camelCase for all parameter names (Java convention).

Source Of Truth

firecrawl/apps/java-sdk/build.gradle.kts
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/src/main/java/com/firecrawl/models/SearchData.java
firecrawl-docs/api-reference/v2-openapi.json

Getting Started

AI Tools

Agent Harnesses

LLM SDKs and Frameworks

Agent Endpoint

Agent Quickstarts

Agentic Debugging

Cookbooks

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

​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

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