> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-4ti4xi.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

This file is the canonical quickstart for external agents integrating Firecrawl via the Java SDK. It is generated from SDK source and OpenAPI spec.

## Install

**Gradle:**

```groovy 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 from environment variable (`FIRECRAWL_API_KEY`):

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

Builder options: `apiKey` (String), `apiUrl` (String, default `"https://api.firecrawl.dev"`), `timeoutMs` (long, default `300000`), `maxRetries` (int, default `3`), `backoffFactor` (double, default `0.5`), `asyncExecutor` (Executor), `httpClient` (OkHttpClient).

## When To Use What

* **`search`**: Use when you start with a query and need to discover relevant URLs and their content. Returns results from web, news, and image sources.
* **`scrape`**: Use when you already have a specific URL and want its page content in markdown, HTML, JSON, or other formats.
* **`interact`**: Use when the page needs post-scrape browser actions like clicking, typing, scrolling, or executing code in a live browser session.

## Search

### Why use it

Search the web for a query and optionally scrape the results. Returns categorized results from web, news, and image sources with optional content extraction.

### Preferred SDK method

```java theme={null}
client.search(query)
client.search(query, options)
```

### Example

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

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

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

### Parameters

All `SearchOptions` fields are `null` by default (omitted from the request body). Use the builder pattern.

| Parameter           | Type            | Description                                                 |
| ------------------- | --------------- | ----------------------------------------------------------- |
| `query`             | `String`        | The search query (first argument, required).                |
| `sources`           | `List<Object>`  | Sources to search: `"web"`, `"news"`, `"images"`.           |
| `categories`        | `List<Object>`  | Filter by category: `"github"`, `"research"`, `"pdf"`.      |
| `includeDomains`    | `List<String>`  | Restrict results to these domains.                          |
| `excludeDomains`    | `List<String>`  | Exclude results from these domains.                         |
| `limit`             | `Integer`       | Maximum number of results. Server default: `10`.            |
| `tbs`               | `String`        | Time-based search filter (e.g. `"qdr:d"` for past day).     |
| `location`          | `String`        | Location string for geo-targeted search.                    |
| `ignoreInvalidURLs` | `Boolean`       | Ignore invalid URLs in results.                             |
| `timeout`           | `Integer`       | Timeout in milliseconds. Server default: `60000`.           |
| `highlights`        | `Boolean`       | Generate query-relevant highlights. Server default: `true`. |
| `scrapeOptions`     | `ScrapeOptions` | Nested scrape configuration applied to each result.         |
| `integration`       | `String`        | Integration identifier.                                     |

### Return type

`SearchData` with: `getWeb()`, `getNews()`, `getImages()`. Each returns `List<Map<String, Object>>`.

## Scrape

### Why use it

Scrape a single URL and get its content in one or more formats. Supports browser automation, LLM extraction, screenshots, and more.

### Preferred SDK method

```java theme={null}
client.scrape(url)
client.scrape(url, options)
```

### Example

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

Document doc = client.scrape("https://example.com",
    ScrapeOptions.builder()
        .formats(List.of("markdown", "html"))
        .onlyMainContent(true)
        .build());

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

### Parameters

All `ScrapeOptions` fields are `null` by default (omitted from the request body). Use the builder pattern.

| Parameter             | Type                        | Description                                                                                                                                                                                                                                     |
| --------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`                 | `String`                    | The URL to scrape (first argument, required).                                                                                                                                                                                                   |
| `formats`             | `List<Object>`              | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"audio"`, `"video"`, or typed objects (`JsonFormat`, `QuestionFormat`, `HighlightsFormat`). Server default: `["markdown"]`. |
| `onlyMainContent`     | `Boolean`                   | Strip boilerplate, keep main content only. Server default: `true`.                                                                                                                                                                              |
| `headers`             | `Map<String, String>`       | Custom HTTP headers.                                                                                                                                                                                                                            |
| `includeTags`         | `List<String>`              | HTML tags to exclusively include.                                                                                                                                                                                                               |
| `excludeTags`         | `List<String>`              | HTML tags to exclude.                                                                                                                                                                                                                           |
| `timeout`             | `Integer`                   | Timeout in milliseconds. Server default: `60000`.                                                                                                                                                                                               |
| `waitFor`             | `Integer`                   | Delay in milliseconds before fetching content.                                                                                                                                                                                                  |
| `mobile`              | `Boolean`                   | Emulate mobile device.                                                                                                                                                                                                                          |
| `parsers`             | `List<Object>`              | Parser configurations (e.g. `"pdf"` or `Map.of("type", "pdf", "maxPages", 10)`).                                                                                                                                                                |
| `actions`             | `List<Map<String, Object>>` | Browser automation actions as maps.                                                                                                                                                                                                             |
| `location`            | `LocationConfig`            | Location settings: `LocationConfig.builder().country("US").languages(List.of("en-US")).build()`.                                                                                                                                                |
| `skipTlsVerification` | `Boolean`                   | Skip TLS certificate verification.                                                                                                                                                                                                              |
| `removeBase64Images`  | `Boolean`                   | Remove base64 images from markdown. Server default: `true`.                                                                                                                                                                                     |
| `blockAds`            | `Boolean`                   | Block advertisements. Server default: `true`.                                                                                                                                                                                                   |
| `proxy`               | `String`                    | Proxy mode: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`. Server default: `"auto"`.                                                                                                                                                           |
| `maxAge`              | `Long`                      | Use cached result if younger than this (ms).                                                                                                                                                                                                    |
| `storeInCache`        | `Boolean`                   | Cache the result. Server default: `true`.                                                                                                                                                                                                       |
| `lockdown`            | `Boolean`                   | Only serve cached results.                                                                                                                                                                                                                      |
| `redactPII`           | `Boolean`                   | Redact PII from returned content.                                                                                                                                                                                                               |
| `auditMetadata`       | `AuditMetadata`             | User attribution: `new AuditMetadata("username")`.                                                                                                                                                                                              |
| `integration`         | `String`                    | Integration identifier.                                                                                                                                                                                                                         |

#### Format objects

| Type               | Constructor                                                      | Description                    |
| ------------------ | ---------------------------------------------------------------- | ------------------------------ |
| `JsonFormat`       | `JsonFormat.builder().prompt("...").schema(Map.of(...)).build()` | LLM-extracted structured JSON. |
| `QuestionFormat`   | `new QuestionFormat("your question")`                            | Ask a question about the page. |
| `HighlightsFormat` | `new HighlightsFormat("your query")`                             | Find relevant source text.     |

## Interact

### Why use it

Execute code in a live browser session tied to a scrape job. Use for post-scrape interactions like clicking buttons, filling forms, or running scripts.

### Preferred SDK method

```java theme={null}
client.interact(jobId, code)
client.interact(jobId, code, language, timeout)
client.interact(jobId, code, language, timeout, origin)
```

### Example

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

Document doc = client.scrape("https://example.com");
String jobId = (String) doc.getMetadata().get("jobId");

BrowserExecuteResponse result = client.interact(jobId, "document.title");
System.out.println(result.getStdout());

client.stopInteractiveBrowser(jobId);
```

### Parameters

| Parameter  | Type      | Description                                                            |
| ---------- | --------- | ---------------------------------------------------------------------- |
| `jobId`    | `String`  | The scrape job ID (required).                                          |
| `code`     | `String`  | Code to execute in the browser sandbox (required).                     |
| `language` | `String`  | Execution language: `"python"`, `"node"`, `"bash"`. Default: `"node"`. |
| `timeout`  | `Integer` | Execution timeout in seconds. Range: 1-300. Server default: `30`.      |
| `origin`   | `String`  | Origin identifier. Auto-set to `"java-sdk@{version}"` if absent.       |

Use `client.stopInteractiveBrowser(jobId)` to end the browser session.

### Async variants

All three methods have `Async` variants returning `CompletableFuture<T>`:

```java theme={null}
client.scrapeAsync(url, options)
client.searchAsync(query, options)
client.interactAsync(jobId, code, language, timeout, origin)
```

## Notes

* **Naming style**: All parameters use camelCase. Options use the builder pattern.
* **Deprecated aliases**: `scrapeExecute()` is deprecated in favor of `interact()`. `deleteScrapeBrowser()` is deprecated in favor of `stopInteractiveBrowser()`.
* **No `prompt` support**: Unlike JS/Python/Rust, the Java SDK `interact()` method only accepts `code`, not natural-language `prompt`. Use the `code` parameter with `"bash"` language for agent-browser CLI commands.
* **Null handling**: All option fields use `@JsonInclude(NON_NULL)`, so `null` fields are omitted from the request body.

## 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-docs/api-reference/v2-openapi.json`