> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-823qpc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Java Agent Quickstart

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

# Firecrawl Java Agent Quickstart

Canonical quickstart for external agents integrating with Firecrawl via the Java SDK. Generated from SDK source and the OpenAPI spec.

## Install

**Gradle (Kotlin DSL):**

```kotlin theme={null}
implementation("com.firecrawl:firecrawl-java:1.12.1")
```

**Maven:**

```xml theme={null}
<dependency>
    <groupId>com.firecrawl</groupId>
    <artifactId>firecrawl-java</artifactId>
    <version>1.12.1</version>
</dependency>
```

Requires Java 11+.

## Authenticate

```java theme={null}
import com.firecrawl.client.FirecrawlClient;

FirecrawlClient client = FirecrawlClient.builder()
    .apiKey("fc-YOUR_API_KEY")
    .build();
```

Or use the `FIRECRAWL_API_KEY` environment variable:

```java theme={null}
FirecrawlClient client = FirecrawlClient.fromEnv();
```

Builder options:

| Option          | Type           | Default                       | Description                                                                                                          |
| --------------- | -------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `apiKey`        | `String`       | `null`                        | API key. Falls back to `FIRECRAWL_API_KEY` env var, then `firecrawl.apiKey` system property, then keyless free tier. |
| `apiUrl`        | `String`       | `"https://api.firecrawl.dev"` | Base API URL. Falls back to `FIRECRAWL_API_URL` env var.                                                             |
| `timeoutMs`     | `long`         | `300000` (5 min)              | HTTP request timeout in milliseconds.                                                                                |
| `maxRetries`    | `int`          | `3`                           | Max retries for failed requests.                                                                                     |
| `backoffFactor` | `double`       | `0.5`                         | Exponential backoff factor.                                                                                          |
| `asyncExecutor` | `Executor`     | `ForkJoinPool.commonPool()`   | Executor for async methods.                                                                                          |
| `httpClient`    | `OkHttpClient` | auto-configured               | Fully custom HTTP client.                                                                                            |

## When To Use What

* **`search`**: Start with a query and discover relevant pages. Returns URLs, titles, descriptions, and optionally scraped content.
* **`scrape`**: You already have a URL and want structured page content — markdown, HTML, screenshots, JSON extraction, etc.
* **`interact`**: The page needs post-scrape browser actions — clicking, typing, or executing code in a live browser session.

## Search

### Why use it

Discover web pages matching a query. Optionally scrape each result for full content in one call.

### Preferred SDK method

`client.search(query, options)`

### Example

```java theme={null}
import com.firecrawl.client.FirecrawlClient;
import com.firecrawl.models.SearchData;
import com.firecrawl.models.SearchOptions;

FirecrawlClient client = FirecrawlClient.builder()
    .apiKey("fc-YOUR_API_KEY")
    .build();

SearchData results = client.search("firecrawl web scraping", SearchOptions.builder()
    .limit(5)
    .build());

for (Map<String, Object> result : results.getWeb()) {
    System.out.println(result.get("title") + " " + result.get("url"));
}
```

### Parameters

`SearchOptions.builder()` fields:

| Parameter           | Type            | Description                                                           |
| ------------------- | --------------- | --------------------------------------------------------------------- |
| `limit`             | `Integer`       | Max results per source type.                                          |
| `sources`           | `List<Object>`  | Result sources: `"web"`, `"news"`, `"images"` as strings.             |
| `categories`        | `List<Object>`  | Narrow results: `"github"`, `"research"`, `"pdf"`.                    |
| `includeDomains`    | `List<String>`  | Restrict to these domains.                                            |
| `excludeDomains`    | `List<String>`  | Exclude these domains.                                                |
| `tbs`               | `String`        | Time-based filter (e.g. `"qdr:d"` for past day).                      |
| `location`          | `String`        | Location string for geo-targeted results.                             |
| `ignoreInvalidURLs` | `Boolean`       | Skip invalid URLs in results.                                         |
| `timeout`           | `Integer`       | Timeout in milliseconds.                                              |
| `highlights`        | `Boolean`       | Generate query-relevant highlights. Defaults to `true`.               |
| `scrapeOptions`     | `ScrapeOptions` | Scrape each result page. Same builder as the scrape parameters below. |
| `integration`       | `String`        | Integration identifier.                                               |

Results are accessed via `results.getWeb()`, `results.getNews()`, `results.getImages()`. Each entry is a `Map<String, Object>`.

## Scrape

### Why use it

Extract structured content from a single URL — markdown, HTML, screenshots, JSON extraction, audio, video, and more.

### Preferred SDK method

`client.scrape(url, options)`

### Example

```java theme={null}
import com.firecrawl.models.Document;
import com.firecrawl.models.ScrapeOptions;

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

System.out.println(result.getMarkdown());
System.out.println(result.getLinks());
```

### Parameters

`ScrapeOptions.builder()` fields:

| Parameter             | Type                        | Description                                                                                                                                                                                |
| --------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `formats`             | `List<Object>`              | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"screenshot"`, `"json"`, `"audio"`, `"video"`, or format objects like `JsonFormat`, `QuestionFormat`, `HighlightsFormat`. |
| `headers`             | `Map<String, String>`       | Custom HTTP headers.                                                                                                                                                                       |
| `includeTags`         | `List<String>`              | Only include content from these HTML tags.                                                                                                                                                 |
| `excludeTags`         | `List<String>`              | Exclude content from these HTML tags.                                                                                                                                                      |
| `onlyMainContent`     | `Boolean`                   | Extract only main content, excluding headers/navs/footers.                                                                                                                                 |
| `timeout`             | `Integer`                   | Timeout in milliseconds.                                                                                                                                                                   |
| `waitFor`             | `Integer`                   | Additional wait in ms before scraping.                                                                                                                                                     |
| `mobile`              | `Boolean`                   | Emulate a mobile device.                                                                                                                                                                   |
| `parsers`             | `List<Object>`              | Parser config: `"pdf"` or `{"type":"pdf","maxPages":10}`.                                                                                                                                  |
| `actions`             | `List<Map<String, Object>>` | Browser actions before scraping.                                                                                                                                                           |
| `location`            | `LocationConfig`            | Location settings: `.country("US").languages(List.of("en-US"))`.                                                                                                                           |
| `skipTlsVerification` | `Boolean`                   | Skip TLS certificate verification.                                                                                                                                                         |
| `removeBase64Images`  | `Boolean`                   | Remove base64 images from markdown.                                                                                                                                                        |
| `blockAds`            | `Boolean`                   | Block ads and cookie popups.                                                                                                                                                               |
| `proxy`               | `String`                    | Proxy tier: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`.                                                                                                                                |
| `maxAge`              | `Long`                      | Max age in ms of cached content.                                                                                                                                                           |
| `storeInCache`        | `Boolean`                   | Store result in Firecrawl cache.                                                                                                                                                           |
| `lockdown`            | `Boolean`                   | Serve only cached results.                                                                                                                                                                 |
| `redactPII`           | `Boolean`                   | Redact PII from content.                                                                                                                                                                   |
| `auditMetadata`       | `AuditMetadata`             | User attribution for SIEM logging.                                                                                                                                                         |
| `integration`         | `String`                    | Integration identifier.                                                                                                                                                                    |

## Interact

### Why use it

Continue interacting with a live browser session after scraping. Execute code in the browser to click buttons, fill forms, navigate, and extract dynamic content.

### Preferred SDK method

`client.interact(jobId, code)` or `client.interact(jobId, code, language, timeout)`

### Example

```java theme={null}
import com.firecrawl.models.BrowserExecuteResponse;

Document result = client.scrape("https://www.amazon.com", ScrapeOptions.builder()
    .formats(List.of("markdown"))
    .build());

String scrapeId = (String) result.getMetadata().get("scrapeId");

BrowserExecuteResponse response = client.interact(scrapeId,
    "document.querySelector('input[name=field-keywords]').value = 'iPhone 16 Pro Max';"
    + "document.querySelector('form[role=search]').submit();");

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

client.stopInteractiveBrowser(scrapeId);
```

### Parameters

| Parameter  | Type      | Description                                                                                         |
| ---------- | --------- | --------------------------------------------------------------------------------------------------- |
| `jobId`    | `String`  | Scrape job ID. Required. Obtained from `result.getMetadata().get("scrapeId")` of a previous scrape. |
| `code`     | `String`  | Code to execute in the browser session. Required.                                                   |
| `language` | `String`  | Language for code execution: `"python"`, `"node"`, `"bash"`. Defaults to `"node"`.                  |
| `timeout`  | `Integer` | Execution timeout in seconds (1-300).                                                               |
| `origin`   | `String`  | Origin identifier. Auto-set to `"java-sdk@{version}"`.                                              |

Call `client.stopInteractiveBrowser(jobId)` to end the browser session when done.

Every sync method has an async variant returning `CompletableFuture`: `interactAsync(...)`, `scrapeAsync(...)`, `searchAsync(...)`.

## Notes

* **Builder pattern**: `FirecrawlClient`, `ScrapeOptions`, `SearchOptions`, and `LocationConfig` all use `Builder` classes. Construct via `.builder()...build()`.
* **camelCase parameters**: All options use camelCase (e.g. `onlyMainContent`, `includeTags`).
* **`List<Object>` for polymorphic fields**: `formats`, `sources`, and `categories` accept both strings and structured config objects.
* **Search results are generic Maps**: `SearchData.getWeb()` returns `List<Map<String, Object>>` rather than typed model objects. Cast or use Jackson to deserialize individual results.
* **No `prompt` for interact**: Unlike the Node.js and Python SDKs, the Java SDK's `interact` method only supports `code`, not natural-language `prompt`.
* **Deprecated aliases**: `scrapeExecute` -> `interact`, `deleteScrapeBrowser` -> `stopInteractiveBrowser`.

## Source Of Truth

* SDK source: `firecrawl/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java`
* OpenAPI spec: `firecrawl-docs/api-reference/v2-openapi.json`