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

Getting Started

Agent Quickstarts

AI Tools

Agent Harnesses

LLM SDKs and Frameworks

Agent Endpoint

Agentic Debugging

Cookbooks

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