Add agent quickstart docs for all SDK languages

agent-quickstart/elixir.mdx

@@ -0,0 +1,392 @@
+---
+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` **1.12.6** on Hex) and the v2 OpenAPI spec. The Elixir SDK is auto-generated from the OpenAPI spec; function names and parameter keys are spec-derived. All params are snake_case keyword lists; JSON camelCase mapping is handled internally.
+
+## Install
+
+Add to `mix.exs`:
+
+```elixir
+{:firecrawl, "~> 1.12"}
+```
+
+## Authenticate
+
+```elixir
+# config/runtime.exs or config.exs
+config :firecrawl, api_key: System.get_env("FIRECRAWL_API_KEY")
+```
+
+Or pass `api_key` per call:
+
+```elixir
+{: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:` in the query, for example `site:docs.firecrawl.dev crawl webhooks`.
+
+### Preferred SDK method
+
+`Firecrawl.search_and_scrape(params \\ [], opts \\ [])` — also available as `search_and_scrape!/2` (raises on error).
+
+### Example
+
+```elixir
+{:ok, res} = Firecrawl.search_and_scrape(
+  query: "site:docs.firecrawl.dev crawl webhooks",
+  sources: [:web, :news],
+  categories: [:research],
+  limit: 10,
+  tbs: "qdr:m",
+  location: "San Francisco,California,United States",
+  country: "US",
+  ignore_invalid_urls: true,
+  timeout: 60000,
+  scrape_options: [
+    formats: [
+      "markdown",
+      "links",
+      %{type: "json", prompt: "Extract title and key endpoints."}
+    ],
+    only_main_content: true,
+    include_tags: ["main", "article"],
+    exclude_tags: ["nav", "footer"],
+    wait_for: 1000
+  ]
+)
+```
+
+### Parameters
+
+- `query`
+  - Type: string (required)
+  - Use when: you need a search query.
+  - Notes: use `site:example.com` to limit results to a domain.
+
+- `sources`
+  - Type: list of atoms, strings, or maps
+  - Use when: you want to control which sources are searched.
+  - Confirmed values: `:web`, `:news`, `:images`, `:alexandria`
+
+- `domain_tools`
+  - Type: boolean
+  - Use when: you want Alexandria domain-tool discovery alongside semantic matches.
+
+- `tool_detail`
+  - Type: `:compact` | `:summary` | `:full`
+  - Use when: you want to control how much tool metadata is returned.
+
+- `categories`
+  - Type: list of atoms, strings, or maps
+  - Use when: you want to filter results by category.
+  - Confirmed values: `:developer`, `:research`, `:pdf`
+
+- `include_domains`
+  - Type: list of strings
+  - Use when: you want to restrict results to specific domains (hostnames only).
+
+- `exclude_domains`
+  - Type: list of strings
+  - Use when: you want to exclude results from specific domains.
+
+- `limit`
+  - Type: integer
+  - Use when: you want to cap results.
+
+- `tbs`
+  - Type: string
+  - Use when: you need a time-based filter (for example `qdr:d`, `qdr:w`, `sbd:1,qdr:m`).
+
+- `location`
+  - Type: string
+  - Use when: you want localized results.
+
+- `country`
+  - Type: string
+  - Use when: you want ISO 3166-1 alpha-2 geo-targeting (for example `"US"`).
+
+- `safe`
+  - Type: boolean
+  - Use when: you want SafeSearch filtering enabled.
+
+- `highlights`
+  - Type: boolean
+  - Use when: you want query-relevant highlights generated for results.
+
+- `ignore_invalid_urls`
+  - Type: boolean
+  - Use when: you want to drop URLs that cannot be scraped by other endpoints.
+
+- `timeout`
+  - Type: integer
+  - Use when: you need a request timeout in milliseconds.
+
+- `scrape_options`
+  - Type: keyword list
+  - Use when: you want to scrape each search result (see Scrape parameters for fields).
+
+- `enterprise`
+  - Type: list of strings
+  - Use when: you need enterprise search controls.
+  - Confirmed values: `"zdr"` (end-to-end zero data retention), `"anon"` (anonymized zero data retention).
+
+- `threat_protection`
+  - Type: keyword list
+  - Use when: you need per-request threat protection overrides.
+
+## 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 \\ [])` — also available as `scrape_and_extract_from_url!/2` (raises on error).
+
+### 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."},
+    %{type: "screenshot", fullPage: true, quality: 80}
+  ],
+  headers: %{"User-Agent" => "FirecrawlDocsBot/1.0"},
+  only_main_content: true,
+  wait_for: 1000,
+  parsers: [%{type: "pdf", mode: "auto", maxPages: 5}],
+  actions: [
+    %{type: "click", selector: "#accept"},
+    %{type: "wait", milliseconds: 750},
+    %{type: "scrape"}
+  ],
+  location: [country: "US", languages: ["en-US"]],
+  remove_base64_images: true,
+  block_ads: true,
+  proxy: :auto,
+  max_age: 86400000,
+  store_in_cache: true,
+  profile: [name: "docs-session", save_changes: true]
+)
+```
+
+### Parameters
+
+- `url`
+  - Type: string (required)
+  - Use when: you want to scrape a specific page.
+
+- `formats`
+  - Type: list of format strings or format maps
+  - Use when: you want multiple output formats.
+  - Confirmed format strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`
+  - Format map fields: `type` (one of the above), plus format-specific options such as `prompt`/`schema` for `"json"`, `modes`/`tag` for `"changeTracking"`, `fullPage`/`quality`/`viewport` for `"screenshot"`.
+
+- `headers`
+  - Type: map
+  - Use when: you need custom request headers.
+
+- `include_tags`
+  - Type: list of strings
+  - Use when: you want to include only specific HTML tags.
+
+- `exclude_tags`
+  - Type: list of strings
+  - Use when: you want to exclude specific HTML tags.
+
+- `only_main_content`
+  - Type: boolean
+  - Use when: you want to strip nav, footer, and other boilerplate.
+
+- `only_clean_content`
+  - Type: boolean
+  - Use when: you want LLM-based residual boilerplate removal (beta).
+
+- `timeout`
+  - Type: integer
+  - Use when: you need a timeout in milliseconds. Min 1000, default 60000, max 300000.
+
+- `wait_for`
+  - Type: integer
+  - Use when: you need to wait for the page to render (milliseconds).
+
+- `mobile`
+  - Type: boolean
+  - Use when: you want a mobile viewport.
+
+- `parsers`
+  - Type: list of parser strings or maps
+  - Use when: you need file parsing controls.
+  - Confirmed values: `"pdf"`, `%{type: "pdf", mode: "fast" | "auto" | "ocr", maxPages: integer}`
+
+- `actions`
+  - Type: list of action maps
+  - Use when: you need lightweight pre-scrape actions.
+  - Confirmed action types: `wait` (`milliseconds` or `selector`), `screenshot` (`fullPage`, `quality`, `viewport`), `click` (`selector`, optional `all`), `write` (`text`), `press` (`key`), `scroll` (`direction`: `up`/`down`, optional `selector`), `scrape`, `executeJavascript` (`script`), `pdf` (`format`, `landscape`, `scale`).
+
+- `location`
+  - Type: keyword list
+  - Use when: you need geo or language-aware scraping.
+  - Fields: `country:`, `languages:`
+
+- `skip_tls_verification`
+  - Type: boolean
+  - Use when: you need to skip TLS verification.
+
+- `remove_base64_images`
+  - Type: boolean
+  - Use when: you want to drop base64 images from markdown output.
+
+- `block_ads`
+  - Type: boolean
+  - Use when: you want ad and cookie popup blocking.
+
+- `proxy`
+  - Type: atom or string
+  - Use when: you need proxy control.
+  - Confirmed values: `:basic`, `:stealth`, `:enhanced`, `:auto`
+
+- `max_age`
+  - Type: integer
+  - Use when: you want cached data up to a maximum age (milliseconds).
+
+- `min_age`
+  - Type: integer
+  - Use when: you want cached data only if it is at least this old (milliseconds).
+
+- `store_in_cache`
+  - Type: boolean
+  - Use when: you want Firecrawl to cache the result.
+
+- `lockdown`
+  - Type: boolean
+  - Use when: you want cache-only mode for compliance (404 on cache miss).
+
+- `check_prompt_injection`
+  - Type: boolean
+  - Use when: you want to scan for prompt injection before LLM formats run.
+
+- `redact_pii`
+  - Type: any
+  - Use when: you want to redact personally identifiable information from output.
+
+- `zero_data_retention`
+  - Type: boolean
+  - Use when: you want zero data retention for this scrape.
+
+- `audit_metadata`
+  - Type: keyword list
+  - Use when: you need user attribution for SIEM logging.
+
+- `profile`
+  - Type: keyword list
+  - Use when: you want a persistent browser profile shared across scrapes and interactions.
+  - Fields: `name:`, optional `save_changes:` (or `saveChanges:`)
+
+- `domain_tools`
+  - Type: boolean
+  - Use when: you want Alexandria domain-tool discovery.
+
+- `tool_detail`
+  - Type: `:compact` | `:summary` | `:full`
+  - Use when: you want to control how much tool metadata is returned.
+
+- `threat_protection`
+  - Type: keyword list
+  - Use when: you need per-request threat protection overrides.
+
+- `alexandria`
+  - Type: any
+  - Use when: you want to execute catalogued provider tools instead of scraping.
+
+## Interact
+
+### Why use it
+
+Use interact when a page requires browser actions or code execution after a scrape starts. The Elixir SDK supports code-based interactions only (no `prompt` parameter).
+
+### Preferred SDK method
+
+`Firecrawl.interact_with_scrape_browser_session(job_id, params \\ [], opts \\ [])` — also available as `interact_with_scrape_browser_session!/3` (raises on error).
+
+To end the session: `Firecrawl.stop_interactive_scrape_browser_session(job_id, 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, ["metadata", "scrapeId"])
+
+{:ok, res} = Firecrawl.interact_with_scrape_browser_session(
+  job_id,
+  code: "console.log(await page.title());",
+  language: :node,
+  timeout: 60
+)
+
+{:ok, _stopped} = Firecrawl.stop_interactive_scrape_browser_session(job_id)
+```
+
+### Parameters
+
+- `job_id`
+  - Type: string (required, first positional argument)
+  - Use when: you have a scrape job ID from a prior scrape response.
+
+- `code`
+  - Type: string (required)
+  - Use when: you want to run code in the browser session.
+
+- `language`
+  - Type: atom or string
+  - Use when: you need a specific runtime.
+  - Confirmed values: `:python`, `:node`, `:bash`
+
+- `timeout`
+  - Type: integer
+  - Use when: you need an execution timeout in seconds.
+
+- `origin`
+  - Type: string
+  - Use when: you want an optional origin label for execution telemetry.
+
+## Notes
+
+- The Elixir SDK is auto-generated from the OpenAPI spec (`generate.exs`). Function names are spec-derived, not simplified (for example `scrape_and_extract_from_url` rather than `scrape`).
+- Every public function has a bang (`!`) variant that raises on error instead of returning `{:error, _}`.
+- The last argument `opts` on every function supports `:api_key`, `:base_url`, and passthrough `Req` options.
+- This SDK exposes code-based interactions only; there is no `prompt` parameter on `interact_with_scrape_browser_session`.
+- Deprecated alias: `search_github` → use `search_developer` instead (stops responding after 2026-11-03).
+- Standalone interact sessions (not bound to a scrape job) are available via `create_browser_session`, `execute_browser_code`, and `delete_browser_session`.
+
+## Source Of Truth
+
+- `firecrawl/apps/elixir-sdk/mix.exs`
+- `firecrawl/apps/elixir-sdk/lib/firecrawl.ex`
+- `firecrawl-docs/api-reference/v2-openapi.json`