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

Canonical Firecrawl Elixir quickstart for external agents. Generated from SDK source (`:firecrawl` **v1.9.1**, `firecrawl/apps/elixir-sdk`) and the v2 OpenAPI spec. The Elixir client is auto-generated from the OpenAPI spec; function names and parameter keys reflect the spec directly.

## Install

Add to `mix.exs`:

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

## Authenticate

```elixir theme={null}
# config/runtime.exs or config.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 webhook retries"], api_key: "fc-your-api-key")
```

The API key is optional. Scrape, search, and interact fall back to a keyless free tier (rate-limited per IP).

## 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:`, for example `site:docs.firecrawl.dev crawl webhooks`.

### Preferred SDK method

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

### Example

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

### Parameters

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

* `sources` — list of atoms, strings, or maps. Sources to search: `:web`, `:news`, `:images` or `%{type: "web" | "news" | "images"}`.

* `categories` — list of atoms, strings, or maps. Filter by category: `:github`, `:research`, `:pdf` or `%{type: ...}`.

* `include_domains` — list of strings. Domains to include.

* `exclude_domains` — list of strings. Domains to exclude.

* `limit` — integer. Max number of results.

* `tbs` — string. Time-based filter (e.g. `qdr:d`, `qdr:w`).

* `location` — string. Localized results.

* `country` — string. ISO 3166-1 alpha-2 targeting (e.g. `"US"`).

* `ignore_invalid_urls` — boolean. Drop invalid URLs.

* `timeout` — integer. Request timeout in milliseconds.

* `highlights` — boolean. Generate query-relevant highlights. Defaults to true.

* `enterprise` — list of strings. Enterprise search controls: `"zdr"` for zero data retention, `"anon"` for anonymized.

* `scrape_options` — 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,
  actions: [
    %{type: "click", selector: "#accept"},
    %{type: "wait", milliseconds: 750},
    %{type: "scrape"}
  ]
)
```

### Parameters

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

* `formats` — list of format strings or format maps. Output formats.
  * String formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"branding"`, `"audio"`, `"video"`.
  * Map formats: `%{type: "json", prompt: ..., schema: ...}`, `%{type: "screenshot", fullPage: ..., quality: ..., viewport: ...}`, `%{type: "changeTracking", modes: [...], tag: ...}`.

* `headers` — map. Custom request headers.

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

* `exclude_tags` — list of strings. Exclude specific HTML tags.

* `only_main_content` — boolean. Strip nav, footer, and other boilerplate.

* `timeout` — integer. Timeout in milliseconds. Min 1000, default 60000, max 300000.

* `wait_for` — integer. Wait for the page to render (milliseconds).

* `mobile` — boolean. Mobile viewport.

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

* `actions` — list of action maps. Pre-scrape browser actions: `wait`, `screenshot`, `click` (with optional `all`), `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `pdf`.

* `location` — keyword list with `country:` and `languages:`. Geo or language-aware scraping.

* `skip_tls_verification` — boolean. Skip TLS verification.

* `remove_base64_images` — boolean. Drop base64 images from markdown output.

* `block_ads` — boolean. Ad and cookie popup blocking.

* `proxy` — atom or string: `:basic`, `:enhanced`, `:auto`.

* `max_age` — integer. Cached data up to a maximum age (milliseconds).

* `min_age` — integer. Cached data only if at least this old (milliseconds).

* `store_in_cache` — boolean. Cache the result.

* `lockdown` — boolean. Serve only previously cached results; no outbound request.

* `redact_pii` — boolean. Redact PII from content.

* `audit_metadata` — keyword list with `username:`. User attribution for SIEM logging.

* `profile` — keyword list with `name:` and optional `save_changes:`. Persistent browser profile.

* `zero_data_retention` — boolean. 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
)
```

### Parameters

* `job_id` — string (required, first positional arg). The scrape job ID.

* `code` — string (required). Code to run in the browser session.

* `language` — atom or string: `:python`, `:node`, `:bash`. Defaults to `:node`.

* `timeout` — integer. Execution timeout in seconds.

* `origin` — string. Optional origin label for execution telemetry.

### Stop session

`Firecrawl.stop_interactive_scrape_browser_session(job_id, opts \\ [])`

Issues `DELETE /scrape/{jobId}/interact`. A bang variant `stop_interactive_scrape_browser_session!/2` is also available.

## Notes

* The Elixir client is OpenAPI-shaped; function names and parameter keys are generated from the spec.
* Each public function has a bang (`!`) variant that raises on error instead of returning `{:error, _}`.
* This SDK exposes code-based interactions only (no `prompt` parameter on interact).
* Every request body includes an `"origin"` field set to `"elixir-sdk@1.9.1"` for telemetry.

## Source Of Truth

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