firecrawl · ericciarla · Aug 19, 2026
diff --git a/agent-quickstart/elixir.mdx b/agent-quickstart/elixir.mdx
@@ -0,0 +1,208 @@
+---
+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 integrating with Firecrawl via the Elixir SDK. Generated from SDK source and the OpenAPI spec.
+
+## Install
+
+Add to your `mix.exs`:
+
+```elixir
+defp deps do
+  [
+    {:firecrawl, "~> 1.9"}
+  ]
+end
+```
+
+## Authenticate
+
+Set the API key in application config:
+
+```elixir
+# config/config.exs
+config :firecrawl, api_key: "fc-YOUR_API_KEY"
+```
+
+Or pass it per-request via the `opts` keyword list:
+
+```elixir
+Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-YOUR_API_KEY")
+```
+
+The default base URL is `https://api.firecrawl.dev/v2`. Override with:
+
+```elixir
+config :firecrawl, base_url: "https://your-instance.com/v2"
+```
+
+No API key is required — scrape, search, and interact fall back to a keyless free tier (rate-limited per IP).
+
+## When To Use What
+
+- **`search_and_scrape`**: Start with a query and discover relevant pages. Returns URLs, titles, descriptions, and optionally scraped content.
+- **`scrape_and_extract_from_url`**: You already have a URL and want structured page content — markdown, HTML, screenshots, JSON extraction, etc.
+- **`interact_with_scrape_browser_session`**: The page needs post-scrape browser actions — clicking, typing, or executing code in a live browser session.
+
+## Search
+
+### Why use it
+
+Discover web pages matching a query. Optionally scrape each result for full content in one call.
+
+### Preferred SDK method
+
+`Firecrawl.search_and_scrape(params, opts \\ [])`
+
+Bang variant: `Firecrawl.search_and_scrape!(params, opts \\ [])`
+
+### Example
+
+```elixir
+{:ok, response} = Firecrawl.search_and_scrape(
+  query: "firecrawl web scraping",
+  limit: 5
+)
+
+IO.inspect(response.body)
+```
+
+### Parameters
+
+All parameters are passed as a keyword list (first argument). Validated at runtime via NimbleOptions.
+
+| Parameter | Elixir key | JSON key | Type | Description |
+|---|---|---|---|---|
+| query | `:query` | `"query"` | `:string` | Search query. **Required**. |
+| limit | `:limit` | `"limit"` | `:integer` | Max results to return. |
+| country | `:country` | `"country"` | `:string` | ISO country code for geo-targeting (e.g. `"US"`). |
+| location | `:location` | `"location"` | `:string` | Location string (e.g. `"San Francisco,California,United States"`). |
+| tbs | `:tbs` | `"tbs"` | `:string` | Time-based filter: `"qdr:h"`, `"qdr:d"`, `"qdr:w"`, `"qdr:m"`, `"qdr:y"`, or custom date ranges. |
+| categories | `:categories` | `"categories"` | `{:list, :any}` | Category filters. |
+| sources | `:sources` | `"sources"` | `{:list, :any}` | Sources to search. Defaults to `["web"]`. |
+| include_domains | `:include_domains` | `"includeDomains"` | `{:list, :string}` | Restrict to these domains. |
+| exclude_domains | `:exclude_domains` | `"excludeDomains"` | `{:list, :string}` | Exclude these domains. |
+| highlights | `:highlights` | `"highlights"` | `:boolean` | Generate query-relevant highlights. Defaults to `true`. |
+| ignore_invalid_urls | `:ignore_invalid_urls` | `"ignoreInvalidURLs"` | `:boolean` | Skip invalid URLs in results. |
+| enterprise | `:enterprise` | `"enterprise"` | `{:list, :string}` | Enterprise ZDR options: `["zdr"]` or `["anon"]`. |
+| scrape_options | `:scrape_options` | `"scrapeOptions"` | `:keyword_list` | Options for scraping search results. |
+| timeout | `:timeout` | `"timeout"` | `:integer` | Timeout in milliseconds. |
+
+## Scrape
+
+### Why use it
+
+Extract structured content from a single URL — markdown, HTML, screenshots, JSON extraction, audio, video, and more.
+
+### Preferred SDK method
+
+`Firecrawl.scrape_and_extract_from_url(params, opts \\ [])`
+
+Bang variant: `Firecrawl.scrape_and_extract_from_url!(params, opts \\ [])`
+
+### Example
+
+```elixir
+{:ok, response} = Firecrawl.scrape_and_extract_from_url(
+  url: "https://example.com",
+  formats: ["markdown", "links"]
+)
+
+IO.inspect(response.body["data"]["markdown"])
+```
+
+### Parameters
+
+| Parameter | Elixir key | JSON key | Type | Description |
+|---|---|---|---|---|
+| url | `:url` | `"url"` | `:string` | URL to scrape. **Required**. |
+| formats | `:formats` | `"formats"` | `{:list, :any}` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`, or format objects. |
+| actions | `:actions` | `"actions"` | `{:list, :any}` | Browser actions to perform before grabbing content. |
+| headers | `:headers` | `"headers"` | `:any` | Custom HTTP headers. |
+| include_tags | `:include_tags` | `"includeTags"` | `{:list, :string}` | Only include content from these HTML tags. |
+| exclude_tags | `:exclude_tags` | `"excludeTags"` | `{:list, :string}` | Exclude content from these HTML tags. |
+| only_main_content | `:only_main_content` | `"onlyMainContent"` | `:boolean` | Extract only main content. |
+| timeout | `:timeout` | `"timeout"` | `:integer` | Timeout in ms. Min `1000`, default `60000`, max `300000`. |
+| wait_for | `:wait_for` | `"waitFor"` | `:integer` | Wait in ms before fetching content. |
+| mobile | `:mobile` | `"mobile"` | `:boolean` | Emulate a mobile device. |
+| location | `:location` | `"location"` | `:keyword_list` | Location settings for proxy/language/timezone. |
+| proxy | `:proxy` | `"proxy"` | `{:in, [:basic, :enhanced, :auto]}` | Proxy tier. |
+| block_ads | `:block_ads` | `"blockAds"` | `:boolean` | Block ads and cookie popups. |
+| max_age | `:max_age` | `"maxAge"` | `:integer` | Max cache age in ms. Default 2 days. |
+| min_age | `:min_age` | `"minAge"` | `:integer` | Cache-only mode, min age in ms. |
+| store_in_cache | `:store_in_cache` | `"storeInCache"` | `:boolean` | Store result in Firecrawl cache. |
+| lockdown | `:lockdown` | `"lockdown"` | `:boolean` | Serve only cached results. |
+| parsers | `:parsers` | `"parsers"` | `{:list, :any}` | Parser config (e.g. PDF handling). |
+| profile | `:profile` | `"profile"` | `:keyword_list` | Persistent browser profile: `[name: "my-profile", save_changes: true]`. |
+| redact_pii | `:redact_pii` | `"redactPII"` | `:boolean` | Redact PII from content. |
+| remove_base64_images | `:remove_base64_images` | `"removeBase64Images"` | `:boolean` | Remove base64 images from markdown. |
+| skip_tls_verification | `:skip_tls_verification` | `"skipTlsVerification"` | `:boolean` | Skip TLS verification. |
+| audit_metadata | `:audit_metadata` | `"auditMetadata"` | `:keyword_list` | SIEM logging: `[username: "user"]`. |
+| zero_data_retention | `:zero_data_retention` | `"zeroDataRetention"` | `:boolean` | Enable zero data retention. |
+
+## Interact
+
+### Why use it
+
+Continue interacting with a live browser session after scraping. Execute code in the browser to click buttons, fill forms, navigate, and extract dynamic content.
+
+### 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 \\ [])`
+
+### Example
+
+```elixir
+{:ok, scrape_response} = Firecrawl.scrape_and_extract_from_url(
+  url: "https://www.amazon.com",
+  formats: ["markdown"]
+)
+
+scrape_id = scrape_response.body["data"]["metadata"]["scrapeId"]
+
+{:ok, response} = Firecrawl.interact_with_scrape_browser_session(scrape_id, [
+  code: """
+  document.querySelector('input[name=field-keywords]').value = 'iPhone 16 Pro Max';
+  document.querySelector('form[role=search]').submit();
+  """
+])
+
+IO.inspect(response.body)
+
+Firecrawl.stop_interactive_scrape_browser_session(scrape_id)
+```
+
+### Parameters
+
+The first argument is the `job_id` (string). The second argument is a keyword list of parameters.
+
+| Parameter | Elixir key | JSON key | Type | Description |
+|---|---|---|---|---|
+| code | `:code` | `"code"` | `:string` | Code to execute in the browser session. **Required**. |
+| language | `:language` | `"language"` | `{:in, [:python, :node, :bash]}` | Language for code execution. Use `:node` for JavaScript, `:bash` for agent-browser CLI. |
+| timeout | `:timeout` | `"timeout"` | `:integer` | Execution timeout in seconds. |
+| origin | `:origin` | `"origin"` | `:string` | Origin label for telemetry. |
+
+Call `Firecrawl.stop_interactive_scrape_browser_session(job_id)` to end the browser session when done.
+
+## Notes
+
+- **OpenAPI-generated client**: The Elixir SDK is auto-generated from the OpenAPI spec. Function names mirror the OpenAPI operation IDs.
+- **No client constructor**: There is no client object/struct. All functions are module-level on `Firecrawl`.
+- **Keyword list parameters**: All body parameters are passed as a keyword list using snake_case atoms (e.g. `:only_main_content`). They are auto-converted to camelCase JSON keys.
+- **NimbleOptions validation**: Parameters are validated at runtime before any HTTP request. Invalid params return `{:error, %NimbleOptions.ValidationError{}}`.
+- **Bang variants**: Every function has a `!` variant (e.g. `search_and_scrape!`) that raises on error instead of returning `{:error, _}`.
+- **Per-request overrides**: Pass `:api_key` and `:base_url` in the trailing `opts` keyword list of any function.
+- **No `prompt` for interact**: Unlike the Node.js and Python SDKs, the Elixir SDK's interact function only supports `code`, not natural-language `prompt`.
+- **Req-based HTTP**: The SDK uses `Req` for HTTP. Any `Req` option can be passed through via `opts`.
+
+## Source Of Truth
+
+- SDK source: `firecrawl/apps/elixir-sdk/lib/firecrawl.ex`
+- OpenAPI spec: `firecrawl-docs/api-reference/v2-openapi.json`