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

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

Gradle:

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

Requires Java 11+.

## Authenticate

```java theme={null}
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

```java theme={null}
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

```java theme={null}
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

```java theme={null}
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`