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

## Install

### Maven

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

### Gradle

```groovy theme={null}
implementation 'com.firecrawl:firecrawl:1.18.4'
```

## Authenticate

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

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

Or set the `FIRECRAWL_API_KEY` environment variable:

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

## When To Use What

* **`search`** — Use when you start with a query and need to discover relevant pages. Returns web results, news, images, and optionally scraped page content.
* **`scrape`** — Use when you already have a URL and want structured page content (markdown, HTML, JSON extraction, screenshots, etc.).
* **`interact`** — Use when a page needs browser automation after scraping — clicks, form fills, or post-scrape dynamic content extraction.

## Search

### Why use it

Search the web for a query and get results with titles, URLs, descriptions, and optionally full page content. Supports filtering by domain, time range, category, and source type.

### Preferred SDK method

```
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",
    SearchOptions.builder()
        .limit(5)
        .build());

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

### Parameters

`SearchOptions` builder methods (all nullable, default `null` unless noted):

| Method | Type | Description |
| - | - | - |
| `sources(List<Object>)` | `List<Object>` | Source types: `"web"`, `"news"`, `"images"`. Default: `["web"]`. |
| `categories(List<Object>)` | `List<Object>` | Filter by category: `"github"`, `"research"`, `"pdf"`. |
| `includeDomains(List<String>)` | `List<String>` | Restrict results to these domains. Cannot combine with `excludeDomains`. |
| `excludeDomains(List<String>)` | `List<String>` | Exclude results from these domains. |
| `limit(Integer)` | `Integer` | Max results to return. Default: `10` (API). Range: 1–100. |
| `tbs(String)` | `String` | Time-based filter. E.g. `"qdr:d"` for past day. |
| `location(String)` | `String` | Location for search results. |
| `country(String)` | `String` | ISO 3166-1 alpha-2 country code. |
| `highlights(Boolean)` | `Boolean` | Return query-relevant highlights. Default: `true`. |
| `timeout(Integer)` | `Integer` | Timeout in milliseconds. |
| `ignoreInvalidURLs(Boolean)` | `Boolean` | Skip invalid URLs instead of failing. |
| `scrapeOptions(ScrapeOptions)` | `ScrapeOptions` | Apply scrape options to each result page. |
| `integration(String)` | `String` | Integration identifier. |

### Overloads

* `client.search(query)` — Search with defaults.
* `client.search(query, options)` — Search with options.
* `client.searchAsync(query, options)` — Returns `CompletableFuture<SearchData>`.

## Scrape

### Why use it

Scrape a URL and get its content in your chosen format — markdown, HTML, JSON (with schema-based extraction), screenshots, and more. Supports browser actions, caching, proxies, and PDF parsing.

### Preferred SDK method

```
client.scrape(url, options)
```

### Example

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

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

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

### Parameters

`ScrapeOptions` builder methods (all nullable, default `null` unless noted):

| Method | Type | Description |
| - | - | - |
| `formats(List<Object>)` | `List<Object>` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"json"`, `"summary"`, `"audio"`, `"video"`. Also accepts config objects for `json`, `screenshot`, etc. Default: `["markdown"]`. |
| `onlyMainContent(Boolean)` | `Boolean` | Strip headers, navs, footers. Default: `true` (API). |
| `includeTags(List<String>)` | `List<String>` | Only include content from these HTML tags. |
| `excludeTags(List<String>)` | `List<String>` | Exclude content from these HTML tags. |
| `headers(Map<String, String>)` | `Map<String, String>` | Custom HTTP headers. |
| `waitFor(Integer)` | `Integer` | Extra delay in ms before fetching content. Default: `0`. |
| `timeout(Integer)` | `Integer` | Request timeout in ms. Default: 60000, max: 300000. |
| `mobile(Boolean)` | `Boolean` | Emulate a mobile device. Default: `false`. |
| `maxAge(Long)` | `Long` | Use cached result if younger than this (ms). Default: 172800000 (2 days). |
| `storeInCache(Boolean)` | `Boolean` | Cache this scrape result. |
| `actions(List<Map<String, Object>>)` | `List<Map<String, Object>>` | Browser actions before scraping (wait, click, write, scroll, etc.). |
| `location(LocationConfig)` | `LocationConfig` | Geolocation: `LocationConfig.builder().country("US").build()`. |
| `parsers(List<Object>)` | `List<Object>` | File parsers. Default: `["pdf"]`. |
| `proxy(String)` | `String` | Proxy type: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`. |
| `skipTlsVerification(Boolean)` | `Boolean` | Skip TLS verification. Default: `true` (API). |
| `removeBase64Images(Boolean)` | `Boolean` | Strip base64 images from output. |
| `blockAds(Boolean)` | `Boolean` | Block ads and cookie popups. |
| `lockdown(Boolean)` | `Boolean` | Serve only cached results. |
| `checkPromptInjection(Boolean)` | `Boolean` | Scan content for prompt injection (adds 4 credits). |
| `redactPII(Boolean)` | `Boolean` | Redact PII. |
| `auditMetadata(AuditMetadata)` | `AuditMetadata` | User attribution for SIEM logging. |
| `integration(String)` | `String` | Integration identifier. |

### Overloads

* `client.scrape(url)` — Scrape with defaults.
* `client.scrape(url, options)` — Scrape with options.
* `client.scrapeAsync(url, options)` — Returns `CompletableFuture<Document>`.

## Interact

### Why use it

After scraping a page, interact with it in a live browser session — execute code to click buttons, fill forms, navigate, and extract dynamic content.

### Preferred SDK method

```
client.interact(jobId, code)
```

### Example

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

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

BrowserExecuteResponse response = client.interact(scrapeId, "document.title");
System.out.println(response.getResult());

BrowserExecuteResponse nav = client.interact(scrapeId,
    "document.querySelector('a').click()", "node", 60);
System.out.println(nav.getStdout());

client.stopInteractiveBrowser(scrapeId);
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `jobId` | `String` | The scrape job ID from a previous scrape's `metadata.scrapeId`. **Required.** |
| `code` | `String` | Code to execute in the browser sandbox. **Required.** Max 100,000 chars. |
| `language` | `String` | Language: `"python"`, `"node"`, `"bash"`. Default: `"node"`. |
| `timeout` | `Integer` | Execution timeout in seconds. Min: 1, default: 30 (API), max: 300. |
| `origin` | `String` | Origin label (auto-set to `"java-sdk@{version}"`). |

### Overloads

* `client.interact(jobId, code)` — Execute with defaults (language: `"node"`).
* `client.interact(jobId, code, language, timeout)` — Specify language and timeout.
* `client.interact(jobId, code, language, timeout, origin)` — Full control.
* All have corresponding `interactAsync(...)` variants returning `CompletableFuture<BrowserExecuteResponse>`.

### Stopping an interaction

Call `client.stopInteractiveBrowser(jobId)` to close the browser session and stop billing.

## Notes

* **Deprecated aliases:** `scrapeExecute` → `interact`, `deleteScrapeBrowser` → `stopInteractiveBrowser`. Always use the preferred names.
* **Parameter naming:** All parameters use camelCase (Java convention).
* **Builder pattern:** `ScrapeOptions` and `SearchOptions` use the builder pattern.
* **Package coordinates:** `com.firecrawl:firecrawl` (Maven Central).
* **Constants:** Default API URL: `https://api.firecrawl.dev`, default timeout: 300,000ms, default max retries: 3.
* **Note:** The Java SDK `interact` method requires `code` as a positional parameter. Natural-language `prompt`-based interaction is not yet supported in the Java SDK — use `code` to automate browser actions.

## 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`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.