Firecrawl API SOP

Appearance

Spring Boot ​

Use Firecrawl with Spring Boot to search, scrape, and interact with web data using the official Java SDK.

Prerequisites ​

  • Java 17+ and Spring Boot 3+
  • A Firecrawl API key, get one free

Add the dependency ​

kotlin
  dependencies {
      implementation("com.firecrawl:firecrawl-java:1.2.0")
  }
xml
  <dependency>
      <groupId>com.firecrawl</groupId>
      <artifactId>firecrawl-java</artifactId>
      <version>1.2.0</version>
  </dependency>

Configuration ​

Add your API key to application.properties:

properties
firecrawl.api-key=${FIRECRAWL_API_KEY}

Or set it as an environment variable:

bash
export FIRECRAWL_API_KEY=fc-YOUR-API-KEY

Create a configuration bean ​

Create FirecrawlConfig.java:

java
import com.firecrawl.client.FirecrawlClient;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class FirecrawlConfig {

  @Bean
  public FirecrawlClient firecrawlClient(
          @Value("${firecrawl.api-key}") String apiKey) {
      return FirecrawlClient.builder()
          .apiKey(apiKey)
          .build();
  }
}

Create a REST controller ​

Create FirecrawlController.java:

java
import com.firecrawl.client.FirecrawlClient;
import com.firecrawl.models.Document;
import com.firecrawl.models.SearchData;
import com.firecrawl.models.SearchOptions;
import com.firecrawl.models.ScrapeOptions;
import com.firecrawl.models.BrowserExecuteResponse;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.Map;

@RestController
@RequestMapping("/api")
public class FirecrawlController {

  private final FirecrawlClient firecrawl;

  public FirecrawlController(FirecrawlClient firecrawl) {
      this.firecrawl = firecrawl;
  }

  @PostMapping("/search")
  public SearchData search(@RequestBody Map<String, Object> body) {
      return firecrawl.search(
          (String) body.get("query"),
          SearchOptions.builder()
              .limit((int) body.getOrDefault("limit", 5))
              .build()
      );
  }

  @PostMapping("/scrape")
  public Map<String, Object> scrape(@RequestBody Map<String, String> body) {
      Document doc = firecrawl.scrape(body.get("url"));
      return Map.of(
          "markdown", doc.getMarkdown(),
          "metadata", doc.getMetadata()
      );
  }

  @PostMapping("/interact")
  public Map<String, Object> interact(@RequestBody Map<String, String> body) {
      Document doc = firecrawl.scrape(body.get("url"),
          ScrapeOptions.builder().formats(List.of((Object) "markdown")).build());
      String scrapeId = (String) doc.getMetadata().get("scrapeId");

      BrowserExecuteResponse response = firecrawl.interact(scrapeId,
          body.getOrDefault("code", "const title = await page.title(); console.log(title);"));

      firecrawl.stopInteractiveBrowser(scrapeId);

      return Map.of("result", response.getStdout());
  }
}

Run it ​

bash
./gradlew bootRun

Test it ​

bash
# Search the web
curl -X POST http://localhost:8080/api/search \
-H "Content-Type: application/json" \
-d '{"query": "firecrawl web scraping"}'

# Scrape a page
curl -X POST http://localhost:8080/api/scrape \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com"}'

# Interact with a page
curl -X POST http://localhost:8080/api/interact \
-H "Content-Type: application/json" \
-d '{"url": "https://www.amazon.com", "code": "const title = await page.title(); console.log(title);"}'

Next steps ​

Search docs

Search the web and get full page content

Scrape docs

All scrape options including formats, actions, and proxies

Interact docs

Click, fill forms, and extract dynamic content

Java SDK reference

Full SDK reference with crawl, map, batch scrape, and more