> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-fcql78.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` hex package **1.9.1**) and the v2 OpenAPI spec. Function names are auto-generated from the OpenAPI spec and match the SDK exactly.

## Install

```elixir theme={null}
# mix.exs
defp deps do
  [
    {:firecrawl, "~> 1.9"}
  ]
end
```

## Authenticate

```elixir theme={null}
# Option 1: Application config
config :firecrawl, api_key: "fc-your-api-key"

# Option 2: Per-request in opts
Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-...")
```

All functions accept `api_key` and `base_url` (default `"https://api.firecrawl.dev/v2"`) in the trailing `opts` keyword list.

## When To Use What

* `search_and_scrape`: use when you start with a query and need discovery.
* `scrape_and_extract_from_url`: use when you already have a URL and want page content.
* `interact_with_scrape_browser_session`: 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:`, for example `site:docs.firecrawl.dev crawl webhooks`.

### Preferred SDK function

`Firecrawl.search_and_scrape(params, opts \\ [])` → `{:ok, Req.Response.t()} | {:error, Exception.t()}`

Bang variant: `Firecrawl.search_and_scrape!(params, opts)` raises on error.

### Example

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

results = response.body
for hit <- results["web"] || [] do
  IO.puts("#{hit["url"]}: #{String.slice(hit["markdown"] || "", 0..199)}")
end
```

### Parameters

| Parameter             | Type                 | JSON key            | Description                                                |
| --------------------- | -------------------- | ------------------- | ---------------------------------------------------------- |
| `query`               | `:string` (required) | `query`             | Search query. Use `site:example.com` to limit to a domain. |
| `sources`             | `{:list, :any}`      | `sources`           | Which sources: `"web"`, `"news"`, `"images"`.              |
| `categories`          | `{:list, :any}`      | `categories`        | Filter by category: `"github"`, `"research"`, `"pdf"`.     |
| `include_domains`     | `{:list, :string}`   | `includeDomains`    | Only include these domains.                                |
| `exclude_domains`     | `{:list, :string}`   | `excludeDomains`    | Exclude these domains.                                     |
| `limit`               | `:integer`           | `limit`             | Max number of results.                                     |
| `tbs`                 | `:string`            | `tbs`               | Time-based filter (e.g. `qdr:d`).                          |
| `location`            | `:string`            | `location`          | Localized results.                                         |
| `ignore_invalid_urls` | `:boolean`           | `ignoreInvalidURLs` | Drop invalid URLs.                                         |
| `timeout`             | `:integer`           | `timeout`           | Timeout in milliseconds.                                   |
| `highlights`          | `:boolean`           | `highlights`        | Generate highlights.                                       |
| `scrape_options`      | `:keyword_list`      | `scrapeOptions`     | Scrape each 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 function

`Firecrawl.scrape_and_extract_from_url(params, opts \\ [])` → `{:ok, Req.Response.t()} | {:error, Exception.t()}`

Bang variant: `Firecrawl.scrape_and_extract_from_url!(params, opts)` raises on error.

### Example

```elixir theme={null}
{:ok, response} = Firecrawl.scrape_and_extract_from_url(
  url: "https://docs.firecrawl.dev",
  formats: ["markdown"],
  only_main_content: true
)

doc = response.body["data"]
IO.puts(doc["markdown"])
```

### Parameters

| Parameter               | Type                           | JSON key              | Description                                                                                      |
| ----------------------- | ------------------------------ | --------------------- | ------------------------------------------------------------------------------------------------ |
| `url`                   | `:string` (required)           | `url`                 | Target URL.                                                                                      |
| `formats`               | `{:list, :any}`                | `formats`             | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, etc. |
| `headers`               | `:any`                         | `headers`             | Custom HTTP headers.                                                                             |
| `include_tags`          | `{:list, :string}`             | `includeTags`         | Only include these HTML tags.                                                                    |
| `exclude_tags`          | `{:list, :string}`             | `excludeTags`         | Exclude these HTML tags.                                                                         |
| `only_main_content`     | `:boolean`                     | `onlyMainContent`     | Strip nav, footer, and boilerplate.                                                              |
| `timeout`               | `:integer`                     | `timeout`             | Timeout in milliseconds.                                                                         |
| `wait_for`              | `:integer`                     | `waitFor`             | Wait for page to render (milliseconds).                                                          |
| `mobile`                | `:boolean`                     | `mobile`              | Use a mobile viewport.                                                                           |
| `parsers`               | `{:list, :any}`                | `parsers`             | File parsing controls.                                                                           |
| `actions`               | `{:list, :any}`                | `actions`             | Pre-scrape browser actions.                                                                      |
| `location`              | `:keyword_list`                | `location`            | `[country: ..., languages: [...]]` for geo-aware scraping.                                       |
| `skip_tls_verification` | `:boolean`                     | `skipTlsVerification` | Skip TLS verification.                                                                           |
| `remove_base64_images`  | `:boolean`                     | `removeBase64Images`  | Drop base64 images from markdown output.                                                         |
| `block_ads`             | `:boolean`                     | `blockAds`            | Block ads and cookie popups.                                                                     |
| `proxy`                 | `:basic \| :enhanced \| :auto` | `proxy`               | Proxy control.                                                                                   |
| `max_age`               | `:integer`                     | `maxAge`              | Use cached data up to this age (milliseconds).                                                   |
| `min_age`               | `:integer`                     | `minAge`              | Use cached data only if at least this old (milliseconds).                                        |
| `store_in_cache`        | `:boolean`                     | `storeInCache`        | Cache the result.                                                                                |
| `lockdown`              | `:boolean`                     | `lockdown`            | Serve from cache only.                                                                           |
| `profile`               | `:keyword_list`                | `profile`             | Persistent browser profile.                                                                      |

## Interact

### Why use it

Use `interact` to run code in the browser session tied to a scrape job. The Elixir SDK accepts `code` (required) and does not support `prompt` — use code-based interaction.

### Preferred SDK function

`Firecrawl.interact_with_scrape_browser_session(job_id, params, opts \\ [])` → `{:ok, Req.Response.t()} | {:error, Exception.t()}`

Bang variant: `Firecrawl.interact_with_scrape_browser_session!(job_id, params, opts)` raises on error.

### Example

```elixir theme={null}
{:ok, scrape_response} = Firecrawl.scrape_and_extract_from_url(
  url: "https://example.com",
  formats: ["markdown"]
)

job_id = get_in(scrape_response.body, ["data", "metadata", "scrapeId"])

{:ok, result} = Firecrawl.interact_with_scrape_browser_session(job_id,
  code: "console.log(await page.title());"
)

IO.puts(result.body["stdout"])
```

### Parameters

| Parameter  | Type                        | JSON key   | Description                                         |
| ---------- | --------------------------- | ---------- | --------------------------------------------------- |
| `job_id`   | `String.t()` (path)         | —          | Scrape job ID from scrape response metadata.        |
| `code`     | `:string` (required)        | `code`     | Code to execute in the browser session.             |
| `language` | `:python \| :node \| :bash` | `language` | Execution runtime. Default: `"node"` (server-side). |
| `timeout`  | `:integer`                  | `timeout`  | Execution timeout in seconds.                       |

### Stop session

`Firecrawl.stop_interactive_scrape_browser_session(job_id, opts \\ [])` → `{:ok, Req.Response.t()} | {:error, Exception.t()}`

## Notes

* The Elixir SDK is **auto-generated from the OpenAPI spec** (`generate.exs`). Function names are long and OpenAPI-derived — do not rename them.
* No deprecated aliases exist in the Elixir SDK.
* `interact` does not support `prompt` — only code-based interaction is available.
* The SDK uses `Req` under the hood. Extra `opts` are passed through to `Req`.
* The proxy parameter accepts atoms (`:basic`, `:enhanced`, `:auto`), not strings.
* Errors return `{:error, Firecrawl.Error.t()}` with `status` and `body` fields.

## Source Of Truth

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