> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-dne9il.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.9.1**) and the v2 OpenAPI spec. The Elixir client is auto-generated from the OpenAPI spec; function names and parameter keys match the spec.

## 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 per call:
{:ok, res} = Firecrawl.search_and_scrape([query: "example"], api_key: "fc-your-api-key")
```

## 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 webhook retries",
  limit: 5,
  scrape_options: [
    formats: ["markdown"],
    only_main_content: true
  ]
)
```

### Parameters

All parameters are keyword list entries. Only `query` is required.

* `query` — string (required). The search query. Use `site:example.com` to limit results.
* `sources` — list of atoms, strings, or maps. Controls which sources are searched. Values: `:web`, `:news`, `:images` (or `"web"`, etc.), or `%{type: "web"}`.
* `categories` — list of atoms, strings, or maps. Category filters. Values: `:github`, `:research`, `:pdf` (or strings, or `%{type: "github"}`).
* `include_domains` — list of strings. Restrict results to these domains.
* `exclude_domains` — list of strings. Exclude results from these domains.
* `limit` — integer. Maximum number of results.
* `tbs` — string. Time-based filter (e.g. `"qdr:d"`, `"qdr:w"`).
* `location` — string. Localized results (e.g. `"San Francisco,California,United States"`).
* `country` — string. ISO 3166-1 alpha-2 country code (e.g. `"US"`).
* `highlights` — boolean. Generate query-relevant highlights. Default: `true`.
* `ignore_invalid_urls` — boolean. Drop URLs that cannot be scraped.
* `timeout` — integer. Request timeout in milliseconds.
* `enterprise` — list of strings. `["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://docs.firecrawl.dev",
  formats: ["markdown"],
  only_main_content: true
)
```

### Parameters

All parameters are keyword list entries. Only `url` is required.

* `url` — string (required). The URL to scrape.
* `formats` — list of format strings or format maps. Output formats.
  * Plain strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"branding"`, `"audio"`, `"video"`.
  * Format maps:
    * `%{type: "json", prompt: "...", schema: %{...}}` — JSON extraction.
    * `%{type: "question", question: "..."}` — question-answer extraction.
    * `%{type: "highlights", query: "..."}` — relevant source-text extraction.
    * `%{type: "screenshot", fullPage: true, quality: 80, viewport: %{width: 1280, height: 720}}`.
    * `%{type: "changeTracking", modes: ["git-diff"], tag: "..."}`.
    * `%{type: "attributes", selectors: [%{selector: "a", attribute: "href"}]}`.
* `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 boilerplate.
* `timeout` — integer. Timeout in milliseconds.
* `wait_for` — integer. Wait for the page to render (milliseconds).
* `mobile` — boolean. Use a mobile viewport.
* `parsers` — list of `"pdf"` or `%{type: "pdf", mode: "fast" | "auto" | "ocr", maxPages: integer}`.
* `actions` — list of action maps. Pre-scrape browser actions.
  * `%{type: "wait", milliseconds: 750}` or `%{type: "wait", selector: "..."}`
  * `%{type: "click", selector: "...", all: false}`
  * `%{type: "write", text: "..."}` — click to focus the input first.
  * `%{type: "press", key: "..."}`
  * `%{type: "scroll", direction: "down", selector: "..."}`
  * `%{type: "scrape"}`
  * `%{type: "executeJavascript", script: "..."}`
  * `%{type: "pdf", format: "Letter", landscape: false, scale: 1}`
* `location` — keyword list `[country: "US", languages: ["en-US"]]`.
* `skip_tls_verification` — boolean. Skip TLS verification.
* `remove_base64_images` — boolean. Drop base64 images from markdown.
* `block_ads` — boolean. Ad and cookie popup blocking.
* `proxy` — atom or string. `:basic`, `:enhanced`, or `: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. Only serve cached results.
* `redact_pii` — boolean. Redact personally identifiable information.
* `audit_metadata` — keyword list `[username: "..."]`. User attribution for SIEM logging.
* `profile` — keyword list `[name: "...", save_changes: true]`. Persistent browser profile.
* `zero_data_retention` — boolean. Enable zero data retention.

## Interact

### Why use it

Use `interact` to run code in the browser session tied to a scrape job. The Elixir SDK supports code-based interactions only (no `prompt` parameter).

### Preferred SDK method

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

### Example

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

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

{:ok, res} = Firecrawl.interact_with_scrape_browser_session(
  job_id,
  code: "console.log(await page.title());",
  language: :node,
  timeout: 60
)
```

To end the session: `Firecrawl.stop_interactive_scrape_browser_session(job_id)`.

### Parameters

* `job_id` — string (required). Scrape job ID.
* `code` — string (required). Code to execute in the browser session.
* `language` — atom or string. `:python`, `:node`, or `:bash`.
* `timeout` — integer. Execution timeout in seconds.

## Notes

* Each public function has a bang (`!`) variant that raises on error instead of returning `{:error, _}`.
* The Elixir SDK is auto-generated from the OpenAPI spec; function names are spec-derived (e.g. `scrape_and_extract_from_url`, `search_and_scrape`, `interact_with_scrape_browser_session`).
* This SDK exposes code-based interactions only — there is no `prompt` parameter on `interact_with_scrape_browser_session`.
* Keyword list params are auto-converted to camelCase JSON for the API.
* Deprecated format type: `%{type: "query"}` — use `%{type: "question"}` or `%{type: "highlights"}` instead.
* No deprecated function aliases exist in this SDK (it is regenerated from the spec).

## Source Of Truth

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