Java Agent Quickstart

Canonical Firecrawl Java quickstart for external agents using search, scrape, and interact.

Firecrawl Java Agent Quickstart

Canonical quickstart for external agents. Generated from SDK source (firecrawl-java v1.17.0) and the v2 OpenAPI spec. Method names, parameters, and types match the SDK public API.

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:
// 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 post-scrape browser session. Requires a scrape job ID.

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:, for example site:docs.firecrawl.dev crawl webhooks.

Preferred SDK method

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

Example

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

SearchOptions options = SearchOptions.builder()
    .sources(List.of("web"))
    .limit(5)
    .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();

Parameters

Parameter	Type	Description
query	String	Search query. Use site:example.com to limit to a domain.
options.sources	List<Object>	Which sources: "web", "news", "images".
options.categories	List<Object>	Filter by category: "developer", "research", "pdf", "github".
options.includeDomains	List<String>	Only include these domains.
options.excludeDomains	List<String>	Exclude these domains.
options.limit	Integer	Max results to return.
options.tbs	String	Time-based filter (e.g. qdr:d, qdr:w).
options.location	String	Location for localized results.
options.ignoreInvalidURLs	Boolean	Drop unscrappable URLs.
options.highlights	Boolean	Return query-relevant text highlights. Server default: true.
options.timeout	Integer	Request timeout in milliseconds.
options.scrapeOptions	ScrapeOptions	Scrape each search result (see Scrape parameters).

Scrape

Why use it

Fetch structured content from a URL in one or more formats. Use when you already have the URL.

Preferred SDK method

client.scrape(url) or 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",
        JsonFormat.builder().prompt("Extract plan names and prices.").build()
    ))
    .onlyMainContent(true)
    .build();

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

Parameters

Parameter	Type	Description
url	String	URL to scrape.
options.formats	List<Object>	Output formats: strings ("markdown", "html", "rawHtml", "links", "screenshot", "json", "audio", "video") or typed objects (JsonFormat, QuestionFormat, HighlightsFormat).
options.headers	Map<String, String>	Custom request headers.
options.includeTags	List<String>	Include only these HTML tags.
options.excludeTags	List<String>	Exclude these HTML tags.
options.onlyMainContent	Boolean	Strip nav, footer, 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 parsing controls (e.g. "pdf" or Map.of("type", "pdf", "maxPages", 5)).
options.actions	List<Map<String,Object>>	Pre-scrape browser actions.
options.location	LocationConfig	Geo/language-aware scraping via builder: .country("US").languages(List.of("en-US")).
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".
options.maxAge	Long	Use cached data up to this age (milliseconds).
options.storeInCache	Boolean	Cache the result.
options.lockdown	Boolean	Serve only cached results.

Format helper types:

• JsonFormat.builder().prompt("...").schema(Map.of(...)).build() — JSON extraction.
• QuestionFormat.builder().question("...").build() — question-answer extraction.
• HighlightsFormat.builder().query("...").build() — relevant source-text extraction.

Interact

Why use it

Execute code in the browser session tied to a scrape job. Use for Playwright-style page manipulation after a scrape creates a session.

Preferred SDK method

client.interact(jobId, code) or client.interact(jobId, code, language, timeout) → BrowserExecuteResponse

Example

import com.firecrawl.models.BrowserExecuteResponse;
import com.firecrawl.models.BrowserDeleteResponse;

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

// Code-based interaction
BrowserExecuteResponse result = client.interact(
    jobId,
    "console.log(await page.title());",
    "node",
    60
);

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

// Clean up
BrowserDeleteResponse stopped = 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". Default: "node".
timeout	Integer	Execution timeout in seconds (1-300). null uses API default (30s).

The Java SDK exposes code-based interactions only. There is no prompt parameter (unlike the JS and Python SDKs).

Stop session: client.stopInteractiveBrowser(jobId) ends the browser session.

Notes

• Deprecated aliases: scrapeExecute → interact; deleteScrapeBrowser → stopInteractiveBrowser.
• Every sync method has an async variant returning CompletableFuture<T> (e.g. scrapeAsync, searchAsync, interactAsync).
• All option classes use the builder pattern: ScrapeOptions.builder()...build().
• ScrapeOptions supports toBuilder() for cloning and modifying.
• The client supports a keyless free tier (rate-limited per IP) when no API key is provided.

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