> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-cu3kl3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Elixir Agent Quickstart

> Canonical Firecrawl Elixir quickstart for external agents using search, scrape, and interact.

# Firecrawl Elixir Agent Quickstart

Canonical quickstart for external agents. Generated from SDK source (`:firecrawl` v1.11.0) and the v2 OpenAPI spec. The Elixir client is OpenAPI-shaped; function names and parameter keys are generated from the spec.

## Install

Add to `mix.exs`:

```elixir theme={null}
{:firecrawl, "~> 1.11"}
```

## Authenticate

```elixir theme={null}
# config/runtime.exs
config :firecrawl, api_key: System.get_env("FIRECRAWL_API_KEY")

# Or pass api_key per call:
{:ok, res} = Firecrawl.search_and_scrape(
  [query: "site:docs.firecrawl.dev webhooks"],
  api_key: "fc-your-api-key"
)
```

No API key is required for the keyless free tier (rate-limited per IP). Every function accepts `:api_key` and `:base_url` in the trailing opts keyword list.

## 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 clicks, forms, or post-scrape browser actions.

## Search

### Why use it

Use search to discover relevant pages from a query, then pick URLs to scrape or interact with. Constrain results to a site with `site:` in the query.

### Preferred SDK method

`Firecrawl.search_and_scrape(params \\ [], opts \\ [])`

### Example

```elixir theme={null}
{:ok, res} = Firecrawl.search_and_scrape(
  query: "site:docs.firecrawl.dev webhook retries",
  limit: 10,
  scrape_options: [
    formats: ["markdown"],
    only_main_content: true
  ]
)
```

### Parameters

* `query`
  * Type: string (required)
  * The search query. Use `site:example.com` to limit results to a domain.

* `sources`
  * Type: list of atoms, strings, or maps
  * Which sources to search. Values: `:web`, `:news`, `:images` (or string equivalents, or `%{type: "web"}`).

* `categories`
  * Type: list of atoms, strings, or maps
  * Filter by category. Values: `:developer`, `:research`, `:pdf` (or string equivalents).

* `include_domains`
  * Type: list of strings
  * Restrict results to these domains. Cannot be used with `exclude_domains`.

* `exclude_domains`
  * Type: list of strings
  * Exclude results from these domains. Cannot be used with `include_domains`.

* `limit`
  * Type: integer
  * Max results per source type.

* `tbs`
  * Type: string
  * Time-based filter (e.g. `"qdr:d"` for past day).

* `location`
  * Type: string
  * Location for localized results.

* `country`
  * Type: string
  * ISO 3166-1 alpha-2 country code (e.g. `"US"`).

* `ignore_invalid_urls`
  * Type: boolean
  * Drop URLs that cannot be scraped by other endpoints.

* `timeout`
  * Type: integer
  * Request timeout in milliseconds.

* `highlights`
  * Type: boolean
  * Generate query-relevant highlights. Default: `true`.

* `enterprise`
  * Type: list of strings
  * Enterprise ZDR options. Values: `"zdr"`, `"anon"`.

* `scrape_options`
  * Type: keyword list
  * Scrape each search result. See Scrape parameters.

## Scrape

### Why use it

Use scrape when you already have a URL and want structured content in one or more formats.

### Preferred SDK method

`Firecrawl.scrape_and_extract_from_url(params \\ [], opts \\ [])`

### Example

```elixir theme={null}
{:ok, res} = Firecrawl.scrape_and_extract_from_url(
  url: "https://example.com/pricing",
  formats: [
    "markdown",
    "links",
    %{type: "json", prompt: "Extract plan names and prices."}
  ],
  only_main_content: true,
  wait_for: 1000
)
```

### Parameters

* `url`
  * Type: string (required)
  * The URL to scrape.

* `formats`
  * Type: list of format strings or maps
  * Output formats. String values: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"branding"`, `"audio"`, `"video"`.
  * Map forms: `%{type: "json", prompt: ..., schema: ...}`, `%{type: "screenshot", fullPage: true}`, `%{type: "changeTracking", modes: ["git-diff"]}`.

* `headers`
  * Type: map
  * Custom HTTP headers.

* `include_tags`
  * Type: list of strings
  * Include only specific HTML tags.

* `exclude_tags`
  * Type: list of strings
  * Exclude specific HTML tags.

* `only_main_content`
  * Type: boolean
  * Strip nav, footer, and boilerplate.

* `timeout`
  * Type: integer
  * Timeout in milliseconds. Default: 60000, max: 300000.

* `wait_for`
  * Type: integer
  * Wait time in ms before fetching content.

* `mobile`
  * Type: boolean
  * Emulate mobile viewport.

* `parsers`
  * Type: list of strings or maps
  * File parsing controls. `"pdf"` or `%{type: "pdf", mode: "fast" | "auto" | "ocr", maxPages: integer}`.

* `actions`
  * Type: list of maps
  * Browser actions. Types: `wait`, `screenshot`, `click` (selector, all?), `write` (text), `press` (key), `scroll` (direction), `scrape`, `executeJavascript` (script), `pdf`.

* `location`
  * Type: keyword list
  * Geo or language-aware scraping. Keys: `country:`, `languages:`.

* `skip_tls_verification`
  * Type: boolean
  * Skip TLS certificate verification.

* `remove_base64_images`
  * Type: boolean
  * Drop base64 images from markdown output.

* `block_ads`
  * Type: boolean
  * Ad and cookie popup blocking.

* `proxy`
  * Type: atom or string
  * Proxy control. Values: `:basic`, `:enhanced`, `:auto`.

* `max_age`
  * Type: integer
  * Use cached data if younger than this (ms).

* `min_age`
  * Type: integer
  * Only check cache, never trigger fresh scrape (ms).

* `store_in_cache`
  * Type: boolean
  * Cache the result.

* `lockdown`
  * Type: boolean
  * Serve from cache only, never make outbound requests.

* `redact_pii`
  * Type: boolean
  * Redact personally identifiable information.

* `profile`
  * Type: keyword list
  * Persistent browser profile. Keys: `name:`, `save_changes:`.

* `audit_metadata`
  * Type: keyword list
  * User attribution for SIEM logging. Required key: `username:`.

* `zero_data_retention`
  * Type: boolean
  * Enable zero data retention for this scrape.

## Interact

### Why use it

Use interact when a page requires browser actions or code execution after a scrape starts.

### Preferred SDK method

`Firecrawl.interact_with_scrape_browser_session(job_id, params \\ [], opts \\ [])`

### Example

```elixir theme={null}
{:ok, res} = Firecrawl.interact_with_scrape_browser_session(
  "<scrapeJobId>",
  code: "console.log(await page.title());",
  language: :node,
  timeout: 60
)

# Stop the session when done
{:ok, _} = Firecrawl.stop_interactive_scrape_browser_session("<scrapeJobId>")
```

### Parameters

* `job_id`
  * Type: string (required, first positional argument)
  * Scrape job ID.

* `code`
  * Type: string (required)
  * Code to execute in the browser session.

* `language`
  * Type: atom or string
  * Execution runtime. Values: `:python`, `:node`, `:bash`.

* `timeout`
  * Type: integer
  * Execution timeout in seconds.

* `origin`
  * Type: string
  * Optional origin label for execution telemetry.

### Stop session

`Firecrawl.stop_interactive_scrape_browser_session(job_id, opts \\ [])` issues `DELETE /scrape/{jobId}/interact`.

## Notes

* This SDK exposes code-based interactions only (no `prompt` parameter on `interact_with_scrape_browser_session`).
* Every function has a bang (`!`) variant that raises on error instead of returning `{:error, _}`.
* There is no client struct; the `Req` HTTP client is rebuilt per-call from opts.
* All params are snake\_case keywords, mapped to camelCase JSON at serialization time.
* Parameters are validated at call time with NimbleOptions before any HTTP request.
* Origin telemetry (`"elixir-sdk@{version}"`) is injected into every POST body automatically.

## Source Of Truth

* `firecrawl/apps/elixir-sdk/mix.exs`
* `firecrawl/apps/elixir-sdk/lib/firecrawl.ex`
* `firecrawl-docs/api-reference/v2-openapi.json`