Firecrawl

Auto-generated Elixir client for the Firecrawl API v2.

Built with Req — minimal, idiomatic, auto-generated from the OpenAPI spec with NimbleOptions validation.

Installation

Add firecrawl to your list of dependencies in mix.exs:

def deps do
  [
    {:firecrawl, "~> 1.0"}
  ]
end

Configuration

Set your API key in application config:

config :firecrawl, api_key: "fc-your-api-key"

Or pass it as an option to any function:

Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-your-api-key")

If no API key is found in config or options, a RuntimeError is raised with instructions.

Usage

All params are passed as keyword lists with snake_case keys. Invalid keys, missing required params, and type errors are caught immediately by NimbleOptions.

# Scrape a URL
{:ok, response} = Firecrawl.scrape_and_extract_from_url(
  url: "https://example.com",
  formats: ["markdown"]
)

# Crawl a site
{:ok, response} = Firecrawl.crawl_urls(
  url: "https://example.com",
  limit: 100,
  sitemap: :skip
)

# Map URLs
{:ok, response} = Firecrawl.map_urls(url: "https://example.com")

# Search
{:ok, response} = Firecrawl.search_and_scrape(query: "firecrawl web scraping")

# Check crawl status
{:ok, response} = Firecrawl.get_crawl_status("job-uuid")

# Self-hosted instance
{:ok, response} = Firecrawl.scrape_and_extract_from_url(
  [url: "https://example.com"],
  base_url: "https://your-instance.com/v2"
)

Bang variants

Every function has a ! variant that raises on error instead of returning {:error, _}:

response = Firecrawl.scrape_and_extract_from_url!(url: "https://example.com")

Regenerating from the OpenAPI Spec

The entire client is auto-generated from the Firecrawl OpenAPI specification. To regenerate after spec changes:

mix run generate.exs

This will:

1. Fetch the latest OpenAPI JSON from GitHub
2. Generate all API wrapper functions in lib/firecrawl.ex
3. Bump the version in mix.exs using semver (only if the generated code changed):
   • Major bump if public functions were removed (breaking change)
   • Minor bump if new public functions were added
   • Patch bump for any other changes (signatures, docs, etc.)

Re-running when nothing changed is a no-op — the version is not bumped.

License

MIT