docs(agent-quickstart): add per-language quickstarts

agent-quickstart/elixir.mdx

@@ -0,0 +1,189 @@
+---
+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` hex package **1.9.1**) and the v2 OpenAPI spec. Function names are auto-generated from the OpenAPI spec and match the SDK exactly.
+
+## Install
+
+```elixir
+# mix.exs
+defp deps do
+  [
+    {:firecrawl, "~> 1.9"}
+  ]
+end
+```
+
+## Authenticate
+
+```elixir
+# Option 1: Application config
+config :firecrawl, api_key: "fc-your-api-key"
+
+# Option 2: Per-request in opts
+Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-...")
+```
+
+All functions accept `api_key` and `base_url` (default `"https://api.firecrawl.dev/v2"`) in the trailing `opts` keyword list.
+
+## When To Use What
+
+- `search_and_scrape`: use when you start with a query and need discovery.
+- `scrape_and_extract_from_url`: use when you already have a URL and want page content.
+- `interact_with_scrape_browser_session`: 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 function
+
+`Firecrawl.search_and_scrape(params, opts \\ [])` → `{:ok, Req.Response.t()} | {:error, Exception.t()}`
+
+Bang variant: `Firecrawl.search_and_scrape!(params, opts)` raises on error.
+
+### Example
+
+```elixir
+{:ok, response} = Firecrawl.search_and_scrape(
+  query: "site:docs.firecrawl.dev webhook retries",
+  limit: 5,
+  scrape_options: [formats: ["markdown"]]
+)
+
+results = response.body
+for hit <- results["web"] || [] do
+  IO.puts("#{hit["url"]}: #{String.slice(hit["markdown"] || "", 0..199)}")
+end
+```
+
+### Parameters
+
+| Parameter | Type | JSON key | Description |
+|---|---|---|---|
+| `query` | `:string` (required) | `query` | Search query. Use `site:example.com` to limit to a domain. |
+| `sources` | `{:list, :any}` | `sources` | Which sources: `"web"`, `"news"`, `"images"`. |
+| `categories` | `{:list, :any}` | `categories` | Filter by category: `"github"`, `"research"`, `"pdf"`. |
+| `include_domains` | `{:list, :string}` | `includeDomains` | Only include these domains. |
+| `exclude_domains` | `{:list, :string}` | `excludeDomains` | Exclude these domains. |
+| `limit` | `:integer` | `limit` | Max number of results. |
+| `tbs` | `:string` | `tbs` | Time-based filter (e.g. `qdr:d`). |
+| `location` | `:string` | `location` | Localized results. |
+| `ignore_invalid_urls` | `:boolean` | `ignoreInvalidURLs` | Drop invalid URLs. |
+| `timeout` | `:integer` | `timeout` | Timeout in milliseconds. |
+| `highlights` | `:boolean` | `highlights` | Generate highlights. |
+| `scrape_options` | `:keyword_list` | `scrapeOptions` | Scrape each result (see Scrape parameters). |
+
+## Scrape
+
+### Why use it
+
+Use scrape when you already have a URL and want structured content in one or more formats.
+
+### Preferred SDK function
+
+`Firecrawl.scrape_and_extract_from_url(params, opts \\ [])` → `{:ok, Req.Response.t()} | {:error, Exception.t()}`
+
+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://docs.firecrawl.dev",
+  formats: ["markdown"],
+  only_main_content: true
+)
+
+doc = response.body["data"]
+IO.puts(doc["markdown"])
+```
+
+### Parameters
+
+| Parameter | Type | JSON key | Description |
+|---|---|---|---|
+| `url` | `:string` (required) | `url` | Target URL. |
+| `formats` | `{:list, :any}` | `formats` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, etc. |
+| `headers` | `:any` | `headers` | Custom HTTP headers. |
+| `include_tags` | `{:list, :string}` | `includeTags` | Only include these HTML tags. |
+| `exclude_tags` | `{:list, :string}` | `excludeTags` | Exclude these HTML tags. |
+| `only_main_content` | `:boolean` | `onlyMainContent` | Strip nav, footer, and boilerplate. |
+| `timeout` | `:integer` | `timeout` | Timeout in milliseconds. |
+| `wait_for` | `:integer` | `waitFor` | Wait for page to render (milliseconds). |
+| `mobile` | `:boolean` | `mobile` | Use a mobile viewport. |
+| `parsers` | `{:list, :any}` | `parsers` | File parsing controls. |
+| `actions` | `{:list, :any}` | `actions` | Pre-scrape browser actions. |
+| `location` | `:keyword_list` | `location` | `[country: ..., languages: [...]]` for geo-aware scraping. |
+| `skip_tls_verification` | `:boolean` | `skipTlsVerification` | Skip TLS verification. |
+| `remove_base64_images` | `:boolean` | `removeBase64Images` | Drop base64 images from markdown output. |
+| `block_ads` | `:boolean` | `blockAds` | Block ads and cookie popups. |
+| `proxy` | `:basic \| :enhanced \| :auto` | `proxy` | Proxy control. |
+| `max_age` | `:integer` | `maxAge` | Use cached data up to this age (milliseconds). |
+| `min_age` | `:integer` | `minAge` | Use cached data only if at least this old (milliseconds). |
+| `store_in_cache` | `:boolean` | `storeInCache` | Cache the result. |
+| `lockdown` | `:boolean` | `lockdown` | Serve from cache only. |
+| `profile` | `:keyword_list` | `profile` | Persistent browser profile. |
+
+## Interact
+
+### Why use it
+
+Use `interact` to run code in the browser session tied to a scrape job. The Elixir SDK accepts `code` (required) and does not support `prompt` — use code-based interaction.
+
+### Preferred SDK function
+
+`Firecrawl.interact_with_scrape_browser_session(job_id, params, opts \\ [])` → `{:ok, Req.Response.t()} | {:error, Exception.t()}`
+
+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",
+  formats: ["markdown"]
+)
+
+job_id = get_in(scrape_response.body, ["data", "metadata", "scrapeId"])
+
+{:ok, result} = Firecrawl.interact_with_scrape_browser_session(job_id,
+  code: "console.log(await page.title());"
+)
+
+IO.puts(result.body["stdout"])
+```
+
+### Parameters
+
+| Parameter | Type | JSON key | Description |
+|---|---|---|---|
+| `job_id` | `String.t()` (path) | — | Scrape job ID from scrape response metadata. |
+| `code` | `:string` (required) | `code` | Code to execute in the browser session. |
+| `language` | `:python \| :node \| :bash` | `language` | Execution runtime. Default: `"node"` (server-side). |
+| `timeout` | `:integer` | `timeout` | Execution timeout in seconds. |
+
+### Stop session
+
+`Firecrawl.stop_interactive_scrape_browser_session(job_id, opts \\ [])` → `{:ok, Req.Response.t()} | {:error, Exception.t()}`
+
+## Notes
+
+- The Elixir SDK is **auto-generated from the OpenAPI spec** (`generate.exs`). Function names are long and OpenAPI-derived — do not rename them.
+- No deprecated aliases exist in the Elixir SDK.
+- `interact` does not support `prompt` — only code-based interaction is available.
+- The SDK uses `Req` under the hood. Extra `opts` are passed through to `Req`.
+- The proxy parameter accepts atoms (`:basic`, `:enhanced`, `:auto`), not strings.
+- Errors return `{:error, Firecrawl.Error.t()}` with `status` and `body` fields.
+
+## Source Of Truth
+
+- `firecrawl/apps/elixir-sdk/lib/firecrawl.ex`
+- `firecrawl/apps/elixir-sdk/mix.exs`
+- `firecrawl-docs/api-reference/v2-openapi.json`