firecrawl · ericciarla · Aug 15, 2026
diff --git a/agent-quickstart/elixir.mdx b/agent-quickstart/elixir.mdx
@@ -0,0 +1,190 @@
+---
+title: "Elixir Agent Quickstart"
+description: "Canonical Firecrawl Elixir quickstart for external agents using search, scrape, and interact."
+---
+
+Canonical Firecrawl Elixir quickstart for agents. Generated from SDK source (`firecrawl` **v1.9.1**, `firecrawl/apps/elixir-sdk`) and the v2 OpenAPI spec.
+
+## Install
+
+Add to `mix.exs`:
+
+```elixir
+{:firecrawl, "~> 1.9"}
+```
+
+## 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"
+)
+```
+
+## 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
+{:ok, res} = Firecrawl.search_and_scrape(
+  query: "site:docs.firecrawl.dev webhook retries",
+  sources: [:web, :news],
+  limit: 10,
+  scrape_options: [
+    formats: ["markdown"],
+    only_main_content: true
+  ]
+)
+```
+
+### Parameters
+
+| Parameter | Type | Use when |
+|---|---|---|
+| `query` | string (required) | You need a search query. Use `site:example.com` to scope. |
+| `sources` | list of atoms or strings | You want to control sources. Values: `:web`, `:news`, `:images`. Default: `[:web]`. |
+| `categories` | list of atoms, strings, or maps | You want to filter by category. Values: `:github`, `:research`, `:pdf`. |
+| `include_domains` | list of strings | You want results only from specific domains. |
+| `exclude_domains` | list of strings | You want to exclude specific domains. |
+| `limit` | integer | You want to cap results. |
+| `tbs` | string | You need a time filter (e.g. `qdr:d`, `qdr:w`). |
+| `location` | string | You want localized results. |
+| `country` | string | You want ISO 3166-1 alpha-2 targeting (e.g. `"US"`). |
+| `ignore_invalid_urls` | boolean | You want to drop URLs that cannot be scraped. |
+| `timeout` | integer | You need a request timeout in milliseconds. |
+| `highlights` | boolean | You want query-relevant highlights. Default: `true`. |
+| `scrape_options` | keyword list | You want to scrape each search result inline. |
+| `enterprise` | list of strings | You need enterprise controls. Values: `"zdr"`, `"anon"`. |
+
+## 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
+{:ok, res} = Firecrawl.scrape_and_extract_from_url(
+  url: "https://example.com/pricing",
+  formats: [
+    "markdown",
+    "links",
+    %{type: "json", prompt: "Extract plan names and prices."}
+  ],
+  only_main_content: true,
+  wait_for: 1000
+)
+```
+
+### Parameters
+
+| Parameter | Type | Use when |
+|---|---|---|
+| `url` | string (required) | You want to scrape a specific page. |
+| `formats` | list of strings or maps | You want multiple output formats. See format types below. |
+| `headers` | map | You need custom request headers. |
+| `include_tags` | list of strings | You want to include only specific HTML tags. |
+| `exclude_tags` | list of strings | You want to exclude specific HTML tags. |
+| `only_main_content` | boolean | You want to strip nav, footer, and boilerplate. |
+| `timeout` | integer | You need a timeout in milliseconds. Default: `60000`. Min: `1000`. Max: `300000`. |
+| `wait_for` | integer | You need to wait for page render (milliseconds). |
+| `mobile` | boolean | You want a mobile viewport. |
+| `parsers` | list of strings or maps | You need file parsing controls. |
+| `actions` | list of maps | You need pre-scrape browser actions. |
+| `location` | keyword list | You need geo or language-aware scraping. |
+| `skip_tls_verification` | boolean | You need to skip TLS verification. |
+| `remove_base64_images` | boolean | You want to drop base64 images from markdown. |
+| `block_ads` | boolean | You want ad and cookie popup blocking. |
+| `proxy` | atom | You need proxy control. Values: `:basic`, `:enhanced`, `:auto`. |
+| `max_age` | integer | You want cached data up to a maximum age (ms). Default: 2 days. |
+| `min_age` | integer | You want cached data only if at least this old (ms). |
+| `store_in_cache` | boolean | You want Firecrawl to cache the result. |
+| `lockdown` | boolean | You want only cached results, no outbound requests. |
+| `redact_pii` | boolean | You want PII redacted from content. |
+| `audit_metadata` | keyword list | You need user attribution for SIEM. Key: `username` (required). |
+| `profile` | keyword list | You want a persistent browser profile. Keys: `name`, `save_changes`. |
+| `zero_data_retention` | boolean | You want zero data retention for this scrape. |
+
+**Format strings:** `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"branding"`, `"audio"`, `"video"`
+
+**Format maps:** `%{type: "json", prompt: ...}`, `%{type: "screenshot", fullPage: true}`, `%{type: "changeTracking", modes: ["git-diff"]}`
+
+**Action types:** `wait`, `click`, `write`, `press`, `scroll`, `screenshot`, `scrape`, `executeJavascript`, `pdf`
+
+## Interact
+
+### Why use it
+
+Use interact when a page requires browser actions or code execution after a scrape starts. The Elixir SDK exposes **code-based interactions only** (no `prompt` parameter).
+
+### Preferred SDK method
+
+`Firecrawl.interact_with_scrape_browser_session(job_id, params \\ [], opts \\ [])`
+
+### Example
+
+```elixir
+{: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
+)
+```
+
+### Parameters
+
+| Parameter | Type | Use when |
+|---|---|---|
+| `job_id` | string | You have a scrape job ID. |
+| `code` | string (required) | You want to run code in the browser session. |
+| `language` | atom or string | You need a specific runtime. Values: `:python`, `:node`, `:bash`. |
+| `timeout` | integer | You need an execution timeout in seconds. |
+
+### Stop session
+
+`Firecrawl.stop_interactive_scrape_browser_session(job_id)` → ends the browser session. A bang variant `stop_interactive_scrape_browser_session!/2` is also available.
+
+## 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`).
+- Pass `api_key:` in `opts` to override the configured key per call.
+
+## Source Of Truth
+
+- `firecrawl/apps/elixir-sdk/mix.exs`
+- `firecrawl/apps/elixir-sdk/lib/firecrawl.ex`
+- `firecrawl-docs/api-reference/v2-openapi.json`