firecrawl · ericciarla · Sep 24, 2026
diff --git a/agent-quickstart/elixir.mdx b/agent-quickstart/elixir.mdx
@@ -0,0 +1,199 @@
+---
+title: "Elixir Agent Quickstart"
+description: "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.11.0**) and the v2 OpenAPI spec.
+
+## Install
+
+Add to `mix.exs`:
+
+```elixir
+{:firecrawl, "~> 1.11.0"}
+```
+
+## Authenticate
+
+```elixir
+# 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"
+)
+```
+
+Every function accepts a trailing `opts` keyword list supporting `:api_key` (override the global key) and `:base_url` (override the default `https://api.firecrawl.dev/v2`). Omitting `api_key` uses the keyless free tier.
+
+## When To Use What
+
+- **search** — start with a query and need discovery. Returns ranked results you can then scrape.
+- **scrape** — you already have a URL and want page content in one or more formats.
+- **interact** — the page needs clicks, forms, or post-scrape browser actions. Requires a scrape job ID from a prior scrape.
+
+## Search
+
+### Why use it
+
+Discover relevant pages from a query. Constrain to a site with `site:` in the query string (e.g. `site:docs.firecrawl.dev crawl webhooks`).
+
+### Preferred SDK method
+
+`Firecrawl.search_and_scrape(params \\ [], opts \\ [])` → `{:ok, Req.Response.t()} | {:error, Exception.t()}`
+
+### Example
+
+```elixir
+{:ok, res} = Firecrawl.search_and_scrape(
+  query: "site:docs.firecrawl.dev webhook retries",
+  limit: 5,
+  scrape_options: [
+    formats: ["markdown"],
+    only_main_content: true
+  ]
+)
+
+web_results = res.body["data"]["web"]
+```
+
+### Parameters
+
+All parameters are keyword list entries. The SDK validates them at compile time via NimbleOptions and converts snake_case keys to camelCase JSON.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `query` | `string` | The search query (required). Use `site:example.com` to scope to a domain. |
+| `sources` | `list(atom \| string \| map)` | Which sources: `:web`, `:news`, `:images` (or string/map equivalents). |
+| `categories` | `list(any)` | Filter by category: `:developer`, `:research`, `:pdf`. |
+| `include_domains` | `list(string)` | Only include results from these domains. |
+| `exclude_domains` | `list(string)` | Exclude results from these domains. |
+| `limit` | `integer` | Cap on number of results. |
+| `tbs` | `string` | Time-based filter (e.g. `"qdr:d"`, `"qdr:w"`). |
+| `location` | `string` | Location string for localized results. |
+| `country` | `string` | ISO country code for geo-targeting. |
+| `ignore_invalid_urls` | `boolean` | Drop URLs that cannot be scraped. |
+| `timeout` | `integer` | Request timeout in milliseconds. |
+| `highlights` | `boolean` | Generate query-relevant highlights. |
+| `scrape_options` | `keyword` | Scrape each search result (see Scrape parameters). |
+| `enterprise` | `list(string)` | Enterprise options: `"zdr"`, `"anon"`. |
+
+## Scrape
+
+### Why use it
+
+Get structured content from a URL in one or more formats — markdown, HTML, JSON extraction, screenshots, and more.
+
+### Preferred SDK method
+
+`Firecrawl.scrape_and_extract_from_url(params \\ [], opts \\ [])` → `{:ok, Req.Response.t()} | {:error, Exception.t()}`
+
+### Example
+
+```elixir
+{:ok, res} = Firecrawl.scrape_and_extract_from_url(
+  url: "https://example.com/pricing",
+  formats: [
+    "markdown",
+    %{type: "json", prompt: "Extract plan names and prices."}
+  ],
+  only_main_content: true
+)
+
+markdown = res.body["data"]["markdown"]
+json_data = res.body["data"]["json"]
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `url` | `string` | The URL to scrape (required). |
+| `formats` | `list(string \| map)` | Output formats. Strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"branding"`, `"audio"`, `"video"`. Maps: `%{type: "json", prompt: ..., schema: ...}`, `%{type: "question", question: ...}`, `%{type: "highlights", query: ...}`, `%{type: "screenshot", fullPage: ..., quality: ..., viewport: ...}`, `%{type: "changeTracking", modes: [...]}`, `%{type: "attributes", selectors: [...]}`. |
+| `headers` | `map` | Custom request headers. |
+| `include_tags` | `list(string)` | Only include content from these HTML tags. |
+| `exclude_tags` | `list(string)` | Exclude content from these 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` | Emulate a mobile device. |
+| `parsers` | `list(string \| map)` | File parsing controls (e.g. `"pdf"` or `%{type: "pdf", mode: "auto", maxPages: 5}`). |
+| `actions` | `list(map)` | Pre-scrape browser actions. Types: `wait`, `click`, `write`, `press`, `scroll`, `screenshot`, `scrape`, `executeJavascript`, `pdf`. |
+| `location` | `keyword` | Geo-aware scraping (e.g. `[country: "US", languages: ["en-US"]]`). |
+| `skip_tls_verification` | `boolean` | Skip TLS verification. |
+| `remove_base64_images` | `boolean` | Drop base64 images from markdown. |
+| `block_ads` | `boolean` | Block ads and cookie popups. |
+| `proxy` | `atom \| string` | Proxy control: `:basic`, `:enhanced`, `:auto`. |
+| `max_age` | `integer` | Use cached data up to this age (milliseconds). |
+| `min_age` | `integer` | Use cached data only if at least this old (milliseconds). |
+| `store_in_cache` | `boolean` | Cache the result in Firecrawl. |
+| `lockdown` | `boolean` | Only serve cached results, never make outbound requests. |
+| `redact_pii` | `boolean` | Redact personally identifiable information. |
+| `profile` | `keyword` | Persistent browser profile (`[name: "...", save_changes: true]`). |
+| `zero_data_retention` | `boolean` | Enable zero data retention. |
+| `audit_metadata` | `keyword` | User attribution for SIEM logging (`[username: "..."]`). |
+
+## Interact
+
+### Why use it
+
+Run code in the browser session tied to a scrape job. The Elixir SDK exposes code-based interactions only (no `prompt` parameter — use the Node.js, Python, or Rust SDK for natural-language browser control).
+
+### Preferred SDK method
+
+`Firecrawl.interact_with_scrape_browser_session(job_id, params \\ [], opts \\ [])` → `{:ok, Req.Response.t()} | {:error, Exception.t()}`
+
+### Example
+
+```elixir
+{:ok, scrape_res} = Firecrawl.scrape_and_extract_from_url(
+  url: "https://example.com",
+  formats: ["markdown"]
+)
+
+job_id = 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
+)
+
+IO.inspect(res.body)
+
+# Stop the session when done:
+{:ok, _} = Firecrawl.stop_interactive_scrape_browser_session(job_id)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `job_id` | `String.t()` | Scrape job ID from `data.metadata.scrapeId` (first positional argument). |
+| `code` | `string` | Code to execute in the browser session (required). |
+| `language` | `atom \| string` | Runtime: `:python`, `:node`, `:bash`. |
+| `timeout` | `integer` | Execution timeout in seconds. |
+| `origin` | `string` | Optional origin label for telemetry. |
+
+Stop session: `Firecrawl.stop_interactive_scrape_browser_session(job_id, opts \\ [])` — issues `DELETE /scrape/{jobId}/interact`.
+
+## Notes
+
+- The Elixir client is **auto-generated from the OpenAPI spec**. Function names and parameter keys are generated, not hand-written.
+- All parameters use **snake_case keyword lists**. The SDK converts to camelCase JSON automatically.
+- Every function has a **bang (`!`) variant** that raises on error instead of returning `{:error, _}` (e.g. `Firecrawl.scrape_and_extract_from_url!`).
+- No struct-based client — a fresh `Req` HTTP client is built per request.
+- SDK auto-injects `"origin": "elixir-sdk@1.11.0"` into all request bodies.
+- Atom values (like `:node`, `:basic`) are automatically converted to strings before JSON serialization.
+- Nested keyword lists are recursively converted to camelCased maps.
+
+## Source Of Truth
+
+- `firecrawl/apps/elixir-sdk/mix.exs`
+- `firecrawl/apps/elixir-sdk/lib/firecrawl.ex`
+- `firecrawl-docs/api-reference/v2-openapi.json`