> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-8bz2qg.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 Firecrawl with Java. Generated from SDK source and OpenAPI spec.

## Install

Maven:

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

Gradle:

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

## Authenticate

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

FirecrawlClient client = FirecrawlClient.builder()
    .apiKey("fc-YOUR-API-KEY")
    .build();
```

Or read from the `FIRECRAWL_API_KEY` environment variable:

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

Builder options:

| Option          | Type           | Default                                                           |
| --------------- | -------------- | ----------------------------------------------------------------- |
| `apiKey`        | `String`       | `FIRECRAWL_API_KEY` env var or `firecrawl.apiKey` system property |
| `apiUrl`        | `String`       | `"https://api.firecrawl.dev"`                                     |
| `timeoutMs`     | `long`         | `300000` (5 min)                                                  |
| `maxRetries`    | `int`          | `3`                                                               |
| `backoffFactor` | `double`       | `0.5`                                                             |
| `asyncExecutor` | `Executor`     | `ForkJoinPool.commonPool()`                                       |
| `httpClient`    | `OkHttpClient` | — (overrides `timeoutMs`)                                         |

## When To Use What

* **search**: Start with a query, discover relevant URLs, and get their content in one call.
* **scrape**: You already have a URL and want its page content as markdown, HTML, JSON, or other formats.
* **interact**: The page needs clicks, form fills, or post-scrape browser actions on a live session.

## Search

### Why use it

Search the web for a query and get scraped content from the top results. Combines discovery and content extraction in one call.

### Preferred SDK method

`client.search(query)` or `client.search(query, options)`

### Example

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

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

for (var result : results.getWeb()) {
    System.out.println(result.get("title") + " " + result.get("url"));
}
```

### Parameters

All fields on `SearchOptions` are nullable and default to null (API defaults apply).

| Parameter           | Type            | Description                                                                |
| ------------------- | --------------- | -------------------------------------------------------------------------- |
| `query`             | `String`        | **Required.** First positional argument. Search query.                     |
| `limit`             | `Integer`       | Max results per source type.                                               |
| `sources`           | `List<Object>`  | Sources: `"web"`, `"news"`, `"images"` as strings or `{type: "web"}` maps. |
| `categories`        | `List<Object>`  | Categories: `"github"`, `"research"`, `"pdf"`.                             |
| `includeDomains`    | `List<String>`  | Restrict to these domains. Cannot combine with `excludeDomains`.           |
| `excludeDomains`    | `List<String>`  | Exclude these domains. Cannot combine with `includeDomains`.               |
| `tbs`               | `String`        | Time-based filter (e.g. `"qdr:d"` past day, `"qdr:w"` past week).          |
| `location`          | `String`        | Geo-targeting location string.                                             |
| `ignoreInvalidURLs` | `Boolean`       | Exclude invalid URLs.                                                      |
| `timeout`           | `Integer`       | Timeout in ms.                                                             |
| `highlights`        | `Boolean`       | Generate query-relevant highlights.                                        |
| `scrapeOptions`     | `ScrapeOptions` | Scrape options applied to each result page.                                |
| `integration`       | `String`        | Integration identifier.                                                    |

Response fields: `results.getWeb()`, `results.getNews()`, `results.getImages()` each return `List<Map<String, Object>>`.

## Scrape

### Why use it

Get the content of a single URL as markdown, HTML, JSON, screenshots, or other formats.

### Preferred SDK method

`client.scrape(url)` or `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"))
    .onlyMainContent(true)
    .build());

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

### Parameters

All fields on `ScrapeOptions` are nullable and default to null (API defaults apply).

| Parameter             | Type                        | Description                                                                                                                                                                  |
| --------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`                 | `String`                    | **Required.** First positional argument. URL to scrape.                                                                                                                      |
| `formats`             | `List<Object>`              | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"screenshot"`, `"json"`, `"audio"`, `"video"`. Also accepts format config objects. Default: `["markdown"]`. |
| `headers`             | `Map<String, String>`       | Custom HTTP headers.                                                                                                                                                         |
| `includeTags`         | `List<String>`              | HTML tags to include.                                                                                                                                                        |
| `excludeTags`         | `List<String>`              | HTML tags to exclude.                                                                                                                                                        |
| `onlyMainContent`     | `Boolean`                   | Strip navbars, footers, boilerplate. Default: `true`.                                                                                                                        |
| `timeout`             | `Integer`                   | Timeout in ms. Default: `60000`. Min: `1000`, Max: `300000`.                                                                                                                 |
| `waitFor`             | `Integer`                   | Extra delay in ms before fetching content.                                                                                                                                   |
| `mobile`              | `Boolean`                   | Emulate a mobile device.                                                                                                                                                     |
| `parsers`             | `List<Object>`              | File processing controls (e.g. `"pdf"` or `{"type":"pdf","maxPages":10}`).                                                                                                   |
| `actions`             | `List<Map<String, Object>>` | Browser actions before content capture.                                                                                                                                      |
| `location`            | `LocationConfig`            | Geo settings with `country` and `languages`.                                                                                                                                 |
| `skipTlsVerification` | `Boolean`                   | Skip TLS certificate verification.                                                                                                                                           |
| `removeBase64Images`  | `Boolean`                   | Remove base64 images from markdown.                                                                                                                                          |
| `blockAds`            | `Boolean`                   | Block ads and cookie popups. Default: `true`.                                                                                                                                |
| `proxy`               | `String`                    | Proxy type: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`. Default: `"auto"`.                                                                                               |
| `maxAge`              | `Long`                      | Cache threshold in ms. Default: 2 days.                                                                                                                                      |
| `storeInCache`        | `Boolean`                   | Store result in cache.                                                                                                                                                       |
| `lockdown`            | `Boolean`                   | Cache-only, no outbound requests.                                                                                                                                            |
| `redactPII`           | `Boolean`                   | Redact PII.                                                                                                                                                                  |
| `auditMetadata`       | `AuditMetadata`             | SIEM logging with `username` field.                                                                                                                                          |
| `integration`         | `String`                    | Integration identifier.                                                                                                                                                      |

Async variant: `client.scrapeAsync(url, options)` returns `CompletableFuture<Document>`.

## Interact

### Why use it

Control a live browser session tied to a scrape job. Execute code in the browser sandbox 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'");

client.stopInteractiveBrowser(scrapeId);
```

### Parameters

| Parameter  | Type      | Description                                                              |
| ---------- | --------- | ------------------------------------------------------------------------ |
| `jobId`    | `String`  | **Required.** Scrape job ID from `result.getMetadata().get("scrapeId")`. |
| `code`     | `String`  | **Required.** Code to execute in the browser sandbox.                    |
| `language` | `String`  | Runtime: `"python"`, `"node"`, `"bash"`. Default: `"node"`.              |
| `timeout`  | `Integer` | Execution timeout in seconds (1–300). Default: `30`.                     |
| `origin`   | `String`  | Origin label. Default: `"java-sdk@{version}"`.                           |

Stop the session when done:

```java theme={null}
client.stopInteractiveBrowser(scrapeId);
```

Async variants: `client.interactAsync(...)` and `client.stopInteractiveBrowserAsync(...)` return `CompletableFuture`.

## Notes

* Parameter names use **camelCase** (e.g. `onlyMainContent`, `includeTags`, `scrapeOptions`).
* All option classes use the **builder pattern**: `ScrapeOptions.builder().field(value).build()`.
* The Java `interact` method requires `code` — it does not support a `prompt` parameter. Use the `code` parameter with JavaScript to control the browser.
* `includeDomains` and `excludeDomains` on search are mutually exclusive.
* Deprecated aliases (do not use in new code):
  * `scrapeExecute(...)` → use `interact(...)`
  * `deleteScrapeBrowser(...)` → use `stopInteractiveBrowser(...)`

## Source Of Truth

* `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/build.gradle.kts`
* `firecrawl-docs/api-reference/v2-openapi.json`