firecrawl · ericciarla · Aug 10, 2026
diff --git a/agent-quickstart/elixir.mdx b/agent-quickstart/elixir.mdx
@@ -0,0 +1,211 @@
+---
+title: "Elixir Agent Quickstart"
+description: "Canonical Firecrawl Elixir quickstart for external agents using search, scrape, and interact."
+---
+
+# Firecrawl Elixir Agent Quickstart
+
+This file is the canonical quickstart for external agents integrating with Firecrawl via the Elixir SDK. It is generated from SDK source and the OpenAPI spec.
+
+## Install
+
+Add to your `mix.exs`:
+
+```elixir
+defp deps do
+  [
+    {:firecrawl, "~> 1.9"}
+  ]
+end
+```
+
+## Authenticate
+
+The Elixir SDK is a flat module of stateless functions — there is no client struct to construct. Configure the API key globally or pass it per request.
+
+**Global config** (in `config.exs`):
+
+```elixir
+config :firecrawl, api_key: "fc-YOUR_API_KEY"
+```
+
+**Per-request override:**
+
+```elixir
+Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-YOUR_API_KEY")
+```
+
+All functions accept trailing `opts` for `:api_key` and `:base_url` (defaults to `https://api.firecrawl.dev/v2`).
+
+## When To Use What
+
+- **`search_and_scrape`** — Use when you start with a query and need to discover relevant pages. Returns structured results grouped by source type. Optionally scrapes each result.
+- **`scrape_and_extract_from_url`** — Use when you already have a URL and want page content in one or more formats (markdown, HTML, JSON extraction, etc.).
+- **`interact_with_scrape_browser_session`** — Use when the page needs post-scrape browser actions: running code in a live browser session tied to a previous scrape job.
+
+## Search
+
+### Why use it
+
+Search the web for a query and optionally scrape each result. Returns results grouped by source type. Use this as the starting point when you do not yet have a specific URL.
+
+### Preferred SDK method
+
+```
+Firecrawl.search_and_scrape(params \\ [], opts \\ [])
+```
+
+Bang variant: `Firecrawl.search_and_scrape!(params, opts)` raises on error.
+
+### Example
+
+```elixir
+{:ok, response} = Firecrawl.search_and_scrape(
+  query: "firecrawl web scraping API",
+  limit: 5
+)
+
+IO.inspect(response.body)
+```
+
+### Parameters
+
+Parameters are passed as a keyword list. All are optional except `query`.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `query` | `:string` | **Required.** The search query. |
+| `limit` | `:integer` | Max number of results. |
+| `sources` | `{:list, :any}` | Sources to search. Default: `["web"]`. |
+| `categories` | `{:list, :any}` | Categories to filter results. Default: `[]`. |
+| `include_domains` | `{:list, :string}` | Restrict results to these domains. |
+| `exclude_domains` | `{:list, :string}` | Exclude results from these domains. |
+| `tbs` | `:string` | Time-based search filter (e.g. `"qdr:d"` for past day). |
+| `location` | `:string` | Location for search results. |
+| `country` | `:string` | ISO country code for geo-targeting (e.g. `"US"`). |
+| `timeout` | `:integer` | Timeout in milliseconds. |
+| `highlights` | `:boolean` | Generate query-relevant highlights. Default: `true`. |
+| `ignore_invalid_urls` | `:boolean` | Exclude URLs invalid for other Firecrawl endpoints. |
+| `scrape_options` | `:keyword_list` | Options for scraping search results. |
+| `enterprise` | `{:list, :string}` | Enterprise ZDR options: `["zdr"]` or `["anon"]`. |
+
+### Return shape
+
+`{:ok, %Req.Response{}}` — the response body contains results grouped by source type.
+
+## Scrape
+
+### Why use it
+
+Scrape a single URL and get its content in one or more formats. Use this when you have the exact URL you want content from.
+
+### Preferred SDK method
+
+```
+Firecrawl.scrape_and_extract_from_url(params \\ [], opts \\ [])
+```
+
+Bang variant: `Firecrawl.scrape_and_extract_from_url!(params, opts)` raises on error.
+
+### Example
+
+```elixir
+{:ok, response} = Firecrawl.scrape_and_extract_from_url(
+  url: "https://example.com",
+  formats: ["markdown", "html"],
+  only_main_content: true
+)
+
+IO.inspect(response.body)
+```
+
+### Parameters
+
+Parameters are passed as a keyword list. All are optional except `url`.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `url` | `:string` | **Required.** The URL to scrape. |
+| `formats` | `{:list, :any}` | Output formats (e.g. `"markdown"`, `"html"`, `"json"`, `"screenshot"`). Default: `["markdown"]`. |
+| `only_main_content` | `:boolean` | Only return main content. Default: `true`. |
+| `include_tags` | `{:list, :string}` | HTML tags to include. |
+| `exclude_tags` | `{:list, :string}` | HTML tags to exclude. |
+| `headers` | `:any` | Custom HTTP headers. |
+| `timeout` | `:integer` | Timeout in ms. Default: `60000`. Min 1000, max 300000. |
+| `wait_for` | `:integer` | Delay in ms before fetching content. |
+| `mobile` | `:boolean` | Emulate a mobile device. |
+| `parsers` | `{:list, :any}` | File parser config. Default: `["pdf"]`. |
+| `actions` | `{:list, :any}` | Browser actions to perform before grabbing content. |
+| `location` | `:keyword_list` | Location settings (proxy, language, timezone). |
+| `skip_tls_verification` | `:boolean` | Skip TLS certificate verification. |
+| `remove_base64_images` | `:boolean` | Remove base64 images from markdown. Default: `true`. |
+| `block_ads` | `:boolean` | Block ads and cookie popups. Default: `true`. |
+| `proxy` | `{:in, [:basic, :enhanced, :auto]}` | Proxy type. Default: `"auto"`. |
+| `max_age` | `:integer` | Max cache age in ms. Default: `172800000` (2 days). |
+| `min_age` | `:integer` | Cache-only mode. Min age in ms. Set to `1` for any cache. |
+| `store_in_cache` | `:boolean` | Store result in cache. Default: `true`. |
+| `lockdown` | `:boolean` | Only serve cached results. |
+| `redact_pii` | `:boolean` | Redact PII from content. |
+| `zero_data_retention` | `:boolean` | Enable zero data retention. |
+| `profile` | `:keyword_list` | Persistent browser profile. |
+| `audit_metadata` | `:keyword_list` | SIEM logging attribution (`username` required). |
+
+## Interact
+
+### Why use it
+
+Execute code in a live browser session tied to a previous scrape job. Use this for post-scrape interactions like clicking buttons, filling forms, or running scripts.
+
+### Preferred SDK method
+
+```
+Firecrawl.interact_with_scrape_browser_session(job_id, params \\ [], opts \\ [])
+```
+
+Bang variant: `Firecrawl.interact_with_scrape_browser_session!(job_id, params, opts)` raises on error.
+
+### Example
+
+```elixir
+{:ok, scrape_response} = Firecrawl.scrape_and_extract_from_url(url: "https://example.com")
+job_id = scrape_response.body["data"]["metadata"]["jobId"]
+
+{:ok, response} = Firecrawl.interact_with_scrape_browser_session(job_id,
+  code: "document.querySelector('button#submit').click();",
+  language: :node,
+  timeout: 30
+)
+
+IO.inspect(response.body)
+```
+
+### Parameters
+
+The first argument is the `job_id` (path parameter). Remaining parameters are passed as a keyword list.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `job_id` | `String.t()` | **Required** (first argument). The scrape job ID. |
+| `code` | `:string` | **Required.** Code to execute in the browser session. |
+| `language` | `{:in, [:python, :node, :bash]}` | Execution language. Use `:node` for JavaScript or `:bash` for agent-browser CLI commands. |
+| `timeout` | `:integer` | Execution timeout in seconds. |
+| `origin` | `:string` | Origin label for telemetry. |
+
+### Related methods
+
+- `Firecrawl.stop_interactive_scrape_browser_session(job_id, opts)` — Stop the browser session (`DELETE /scrape/{jobId}/interact`).
+
+## Notes
+
+- The SDK is **auto-generated from the OpenAPI spec**. Function names map 1:1 to OpenAPI operations.
+- Parameter names use **snake_case** in Elixir. They are converted to camelCase for the JSON wire format automatically.
+- All functions return `{:ok, %Req.Response{}} | {:error, Exception.t() | Firecrawl.Error.t()}`.
+- Bang variants (e.g. `search_and_scrape!`) raise on error instead of returning an error tuple.
+- There is no client struct — the module is a flat namespace of stateless functions.
+- HTTP errors (4xx/5xx) are wrapped in `Firecrawl.Error` with `:status` and `:body` fields.
+- Batch scraping is available via `Firecrawl.scrape_and_extract_from_urls/2` (`POST /batch/scrape`).
+
+## Source Of Truth
+
+- SDK: `firecrawl/apps/elixir-sdk/lib/firecrawl.ex`
+- OpenAPI: `firecrawl-docs/api-reference/v2-openapi.json`