Java Agent Quickstart

Canonical Firecrawl Java quickstart for external agents. Aligned with firecrawl-java v1.12.1 (firecrawl/apps/java-sdk) and the v2 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(System.getenv("FIRECRAWL_API_KEY"))
    .build();

// Or from environment/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 clicks, forms, or post-scrape browser actions.

Search

Why use it

Use search to discover relevant pages from a query, then pick URLs to scrape or interact with. You can 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 java.util.List;
import java.util.Map;

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

Parameters

Parameter	Type	Description
`query`	`String`	The search query. Use `site:example.com` to limit results to a domain.
`options.sources`	`List<Object>`	Sources to search. Values: `"web"`, `"news"`, `"images"`.
`options.categories`	`List<Object>`	Filter by category. Values: `"github"`, `"research"`, `"pdf"`.
`options.includeDomains`	`List<String>`	Restrict results to these domains.
`options.excludeDomains`	`List<String>`	Exclude these domains.
`options.limit`	`Integer`	Cap 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).

Return value: SearchData with getWeb(), getNews(), getImages() (each List<Map<String, Object>>, may be null). Do not treat SearchData as a directly iterable list.

Scrape

Why use it

Use scrape when you already have a URL and want structured content in one or more formats.

Preferred SDK method

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

Example

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

Document doc = client.scrape(
    "https://docs.firecrawl.dev",
    ScrapeOptions.builder().formats(List.of("markdown")).build()
);
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("...").build()`, `QuestionFormat`, `HighlightsFormat`.
`options.headers`	`Map<String, String>`	Custom request headers.
`options.includeTags`	`List<String>`	Include only specific HTML tags.
`options.excludeTags`	`List<String>`	Exclude specific HTML tags.
`options.onlyMainContent`	`Boolean`	Strip nav, footer, and other boilerplate.
`options.timeout`	`Integer`	Timeout in milliseconds.
`options.waitFor`	`Integer`	Wait for the page to render (milliseconds).
`options.mobile`	`Boolean`	Use a mobile viewport.
`options.parsers`	`List<Object>`	File parsing controls. Values: `"pdf"`, `Map.of("type", "pdf", "maxPages", 10)`.
`options.actions`	`List<Map<String, Object>>`	Pre-scrape browser actions. Types: `wait`, `screenshot`, `click`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `pdf`.
`options.location`	`LocationConfig`	Geo or language-aware scraping. Fields: `country`, `languages`.
`options.skipTlsVerification`	`Boolean`	Skip TLS verification.
`options.removeBase64Images`	`Boolean`	Drop base64 images from markdown output.
`options.blockAds`	`Boolean`	Block ads and cookie popups.
`options.proxy`	`String`	Proxy mode. Values: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`.
`options.maxAge`	`Long`	Use cached data up to this age (milliseconds).
`options.storeInCache`	`Boolean`	Cache the result.
`options.lockdown`	`Boolean`	Only serve cached results, never make an outbound request.
`options.redactPII`	`Boolean`	Redact personally identifiable information.
`options.auditMetadata`	`AuditMetadata`	User attribution for SIEM logging. Constructor arg: `username`.

Interact

Why use it

Use interact when a page requires browser actions or code execution after a scrape starts.

Preferred SDK method

client.interact(jobId, code) — uses default language node
client.interact(jobId, code, language, timeout) — timeout in seconds (1–300), null for API default (30s)

Example

import com.firecrawl.models.BrowserExecuteResponse;

BrowserExecuteResponse result = client.interact(
    "<scrapeJobId>",
    "console.log(await page.title());",
    "node",
    60
);

Parameters

Parameter	Type	Description
`jobId`	`String`	Scrape job ID.
`code`	`String`	Code to run in the browser session.
`language`	`String`	Runtime. Values: `"python"`, `"node"`, `"bash"`. Default: `"node"`.
`timeout`	`Integer`	Execution timeout in seconds (1–300). Null for API default.
`origin`	`String`	Optional origin label for request attribution.

Stop session

client.stopInteractiveBrowser(jobId) → BrowserDeleteResponse Ends the scrape-bound browser session. Response includes isSuccess(), getSessionDurationMs(), getCreditsBilled().

Notes

The Java SDK exposes code-based interactions only: there is no prompt parameter on interact (unlike JS, Python, and Rust SDKs).
Deprecated aliases: scrapeExecute → interact; deleteScrapeBrowser → stopInteractiveBrowser.
Async variants are available: scrapeAsync, searchAsync, interactAsync, stopInteractiveBrowserAsync — all return CompletableFuture.
Uses camelCase parameter names matching the 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/Document.java
firecrawl-docs/api-reference/v2-openapi.json

Getting Started

AI Tools

Agent Harnesses

LLM SDKs and Frameworks

Agent Endpoint

Agentic Debugging

Agent Quickstarts

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

Stop session

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

​Stop session

​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

Stop session

Notes

Source Of Truth