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

# Elixir Source of Truth

> Canonical Firecrawl Elixir source of truth for agents using key endpoints like search, scrape, and interact.

Canonical Firecrawl Elixir source of truth for agents. Generated from SDK source (`:firecrawl` **v1.11.0**) and the v2 OpenAPI spec.

## Install

Add to `mix.exs`:

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

## 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")
```

## 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. You can constrain results to a site with `site:`, for example `site:docs.firecrawl.dev crawl webhooks`.

### Preferred SDK method

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

### Simple Example

```elixir theme={null}
{:ok, res} = Firecrawl.search_and_scrape(query: "site:docs.firecrawl.dev webhook retries")
```

### Complex Example

```elixir theme={null}
{:ok, res} = Firecrawl.search_and_scrape(
  query: "site:docs.firecrawl.dev crawl webhooks",
  sources: [:web, :news],
  categories: [:research],
  limit: 10,
  tbs: "qdr:m",
  location: "San Francisco,California,United States",
  country: "US",
  ignore_invalid_urls: true,
  timeout: 60000,
  scrape_options: [
    formats: [
      "markdown",
      "links",
      %{type: "json", prompt: "Extract title and key endpoints."}
    ],
    only_main_content: true,
    include_tags: ["main", "article"],
    exclude_tags: ["nav", "footer"],
    wait_for: 1000
  ]
)
```

### Parameters

* `query`
  * Type: string
  * Use when: you need a search query.
  * Notes: use `site:example.com` to limit results to a domain.

* `sources`
  * Type: list of atoms, strings, or maps
  * Use when: you want to control which sources are searched.
  * Confirmed values:
    * `"web"` or `:web`
    * `"news"` or `:news`
    * `"images"` or `:images`
    * `%{type: "web" | "news" | "images"}`

* `categories`
  * Type: list of atoms, strings, or maps
  * Use when: you want to filter results by category.
  * Confirmed values:
    * `"developer"` or `:developer`
    * `"research"` or `:research`
    * `"pdf"` or `:pdf`
    * `%{type: "developer" | "research" | "pdf"}`

* `include_domains`
  * Type: list of strings
  * Use when: you want to restrict results to specific domains.

* `exclude_domains`
  * Type: list of strings
  * Use when: you want to exclude results from specific domains.

* `limit`
  * Type: integer
  * Use when: you want to cap results.

* `tbs`
  * Type: string
  * Use when: you need a time-based filter (for example `qdr:d`, `qdr:w`, `sbd:1,qdr:m`).

* `location`
  * Type: string
  * Use when: you want localized results.

* `country`
  * Type: string
  * Use when: you want ISO 3166-1 alpha-2 targeting (for example `"US"`).

* `ignore_invalid_urls`
  * Type: boolean
  * Use when: you want to drop URLs that cannot be scraped by other endpoints.

* `highlights`
  * Type: boolean
  * Use when: you want query-relevant highlights for search results. Defaults to true.

* `timeout`
  * Type: integer
  * Use when: you need a request timeout in milliseconds.

* `enterprise`
  * Type: list of strings
  * Use when: you need enterprise search controls.
  * Confirmed values:
    * `"zdr"`: end-to-end zero data retention
    * `"anon"`: anonymized zero data retention

* `scrape_options`
  * Type: keyword list
  * Use when: you want to scrape each search result (see Scrape parameters for fields).

## 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 \\ [])`

### Simple Example

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

### Complex 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."},
    %{type: "screenshot", fullPage: true, quality: 80, viewport: %{width: 1280, height: 720}},
    %{type: "changeTracking", modes: ["git-diff"], tag: "pricing"}
  ],
  headers: %{"User-Agent" => "FirecrawlDocsBot/1.0"},
  only_main_content: true,
  wait_for: 1000,
  parsers: [%{type: "pdf", mode: "auto", maxPages: 5}],
  actions: [
    %{type: "click", selector: "#accept"},
    %{type: "wait", milliseconds: 750},
    %{type: "scrape"}
  ],
  location: [country: "US", languages: ["en-US"]],
  remove_base64_images: true,
  block_ads: true,
  proxy: :auto,
  max_age: 86400000,
  min_age: 1,
  store_in_cache: true,
  profile: [name: "docs-session", save_changes: true],
  zero_data_retention: false
)
```

### Parameters

* `url`
  * Type: string
  * Use when: you want to scrape a specific page.

* `formats`
  * Type: list of format strings or format maps
  * Use when: you want multiple output formats.
  * Confirmed format strings:
    * `"markdown"`: markdown content
    * `"html"`: cleaned HTML
    * `"rawHtml"`: raw HTML
    * `"links"`: page links
    * `"images"`: image URLs
    * `"screenshot"`: screenshot output
    * `"summary"`: summary output
    * `"changeTracking"`: change tracking output
    * `"json"`: JSON extraction
    * `"branding"`: branding profile output
    * `"audio"`: audio extraction
    * `"video"`: video extraction
  * Format map fields:
    * `type`: one of the format strings above
    * `prompt`, `schema`: JSON extraction options for `type: "json"`
    * `check_prompt_injection`: boolean for `type: "json"` to enable prompt-injection safety check
    * `question`: for `type: "question"`
    * `query`: for `type: "highlights"`
    * `modes`, `schema`, `prompt`, `tag`: change tracking options for `type: "changeTracking"`
    * `fullPage`, `quality`, `viewport`: screenshot options for `type: "screenshot"`

* `headers`
  * Type: map
  * Use when: you need custom request headers.

* `include_tags`
  * Type: list of strings
  * Use when: you want to include only specific HTML tags.

* `exclude_tags`
  * Type: list of strings
  * Use when: you want to exclude specific HTML tags.

* `only_main_content`
  * Type: boolean
  * Use when: you want to strip nav, footer, and other boilerplate.

* `timeout`
  * Type: integer
  * Use when: you need a timeout in milliseconds. Min 1000, default 60000, max 300000.

* `wait_for`
  * Type: integer
  * Use when: you need to wait for the page to render (milliseconds).

* `mobile`
  * Type: boolean
  * Use when: you want a mobile viewport.

* `parsers`
  * Type: list of parser strings or maps
  * Use when: you need file parsing controls.
  * Confirmed values:
    * `"pdf"`
    * `%{type: "pdf", mode: "fast" | "auto" | "ocr", maxPages: integer}`

* `actions`
  * Type: list of action maps
  * Use when: you need lightweight pre-scrape actions.
  * Confirmed action types:
    * `wait`: `milliseconds` or `selector` required
    * `screenshot`: `fullPage`, `quality`, `viewport` optional
    * `click`: `selector` required, `all` optional
    * `write`: `text` required (click to focus the input first)
    * `press`: `key` required
    * `scroll`: `direction` (`up` or `down`) required, `selector` optional
    * `scrape`: no additional fields
    * `executeJavascript`: `script` required
    * `pdf`: `format` (A0, A1, A2, A3, A4, A5, A6, Letter, Legal, Tabloid, Ledger), `landscape`, `scale` optional

* `location`
  * Type: keyword list (for example `country:` and `languages:`)
  * Use when: you need geo or language-aware scraping.

* `skip_tls_verification`
  * Type: boolean
  * Use when: you need to skip TLS verification.

* `remove_base64_images`
  * Type: boolean
  * Use when: you want to drop base64 images from markdown output.

* `block_ads`
  * Type: boolean
  * Use when: you want ad and cookie popup blocking.

* `proxy`
  * Type: atom or string
  * Use when: you need proxy control.
  * Confirmed values: `:basic`, `:enhanced`, `:auto`

* `max_age`
  * Type: integer
  * Use when: you want cached data up to a maximum age (milliseconds).

* `min_age`
  * Type: integer
  * Use when: you want cached data only if it is at least this old (milliseconds).

* `store_in_cache`
  * Type: boolean
  * Use when: you want Firecrawl to cache the result.

* `lockdown`
  * Type: boolean
  * Use when: you want to serve only previously cached results with no outbound requests.

* `redact_pii`
  * Type: boolean
  * Use when: you want to redact personally identifiable information from returned content.

* `audit_metadata`
  * Type: keyword list with `username:` (string, required)
  * Use when: you need user attribution for SIEM logging events.

* `profile`
  * Type: keyword list with `name:` and optional `save_changes:` (or `saveChanges:`)
  * Use when: you want a persistent browser profile shared across scrapes and interactions.

* `zero_data_retention`
  * Type: boolean
  * Use when: you want 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 \\ [])`

### Simple Example

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

### Complex Example

```elixir theme={null}
{:ok, res} = Firecrawl.interact_with_scrape_browser_session(
  "<scrapeJobId>",
  code: "// Use Playwright page methods here",
  language: :node,
  timeout: 120
)
```

### Parameters

* `job_id`
  * Type: string
  * Use when: you have a scrape job ID.

* `code`
  * Type: string
  * Use when: you want to run code in the browser session.

* `language`
  * Type: atom or string
  * Use when: you need a specific runtime.
  * Confirmed values: `:python`, `:node`, `:bash` (or the string equivalents)

* `timeout`
  * Type: integer
  * Use when: you need an execution timeout in seconds.

* `origin`
  * Type: string
  * Use when: you want an optional origin label for execution telemetry.

### Stop interactive session

`Firecrawl.stop_interactive_scrape_browser_session(job_id, opts \\ [])` issues `DELETE /scrape/{jobId}/interact` and tears down the browser session for that scrape job. A bang variant `stop_interactive_scrape_browser_session!/2` is also available.

```elixir theme={null}
{:ok, res} = Firecrawl.stop_interactive_scrape_browser_session("<scrapeJobId>")
```

## 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_with_scrape_browser_session`).

## Source Of Truth

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