Skip to content

docs: add agent quickstart files for all SDK languages #1306

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ericciarla wants to merge 1 commit into
base: main
Choose a base branch
from
+1,043 −0
Draft

docs: add agent quickstart files for all SDK languages #1306

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
194 changes: 194 additions & 0 deletions agent-quickstart/elixir.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,194 @@
---
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.9.2**, `firecrawl/apps/elixir-sdk`) and the v2 OpenAPI spec. Function names and parameter keys are generated from the OpenAPI spec.

## Install

Add to `mix.exs`:

```elixir
{:firecrawl, "~> 1.4"}
```

## 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.scrape_and_extract_from_url(
[url: "https://example.com"],
api_key: "fc-your-api-key"
)
```

There is no client struct. Configuration is resolved per-call from Application config or per-call opts.

## 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

Discover relevant pages from a query, then pick URLs to scrape or interact with. Constrain results to a site with `site:`, e.g. `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],
limit: 5,
scrape_options: [
formats: ["markdown"],
only_main_content: true
]
)
```

A bang variant `search_and_scrape!/2` is also available — it raises on error instead of returning `{:error, _}`.

### Parameters

| Parameter | Type | Description |
|---|---|---|
| `query` | `string` | Search query (required). Use `site:example.com` to limit to a domain. |
| `sources` | `list` | Sources: `:web`, `:news`, `:images` (atoms or strings). |
| `categories` | `list` | Categories: `:github`, `:research`, `:pdf` (atoms or strings). |
| `include_domains` | `list(string)` | Restrict results to these domains. |
| `exclude_domains` | `list(string)` | Exclude these domains. |
| `limit` | `integer` | Max results. |
| `tbs` | `string` | Time-based filter (e.g. `qdr:d`, `qdr:w`). |
| `location` | `string` | Location for localized results. |
| `country` | `string` | ISO 3166-1 alpha-2 code (e.g. `"US"`). |
| `ignore_invalid_urls` | `boolean` | Drop invalid URLs. |
| `timeout` | `integer` | Timeout in milliseconds. |
| `highlights` | `boolean` | Generate query-relevant highlights. Default: `true`. |
| `enterprise` | `list(string)` | Enterprise options: `["zdr"]` for zero data retention, `["anon"]` for anonymized. |
| `scrape_options` | `keyword list` | 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 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 | Description |
|---|---|---|
| `url` | `string` | Target URL (required). |
| `formats` | `list` | Output formats. Strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"branding"`, `"audio"`, `"video"`. Maps: `%{type: "json", prompt: ...}`, `%{type: "screenshot", fullPage: true}`, etc. |
| `headers` | `map` | Custom HTTP headers. |
| `include_tags` | `list(string)` | Only include these HTML tags. |
| `exclude_tags` | `list(string)` | Exclude these HTML tags. |
| `only_main_content` | `boolean` | Strip nav, footer, and boilerplate. |
| `timeout` | `integer` | Timeout in milliseconds. Default: 60000. |
| `wait_for` | `integer` | Wait for page to render (milliseconds). |
| `mobile` | `boolean` | Mobile viewport. |
| `parsers` | `list` | Parser controls. E.g. `[%{type: "pdf", mode: "auto", maxPages: 5}]`. |
| `actions` | `list(map)` | Pre-scrape browser actions. Types: `wait`, `click`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `screenshot`, `pdf`. |
| `location` | `keyword list` | Geo/language-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` | Proxy control: `:basic`, `:enhanced`, `:auto`. |
| `max_age` | `integer` | Cached data up to this age (milliseconds). |
| `min_age` | `integer` | Cached data only if at least this old (milliseconds). |
| `store_in_cache` | `boolean` | Cache the result. |
| `lockdown` | `boolean` | Only serve previously cached results. |
| `redact_pii` | `boolean` | Redact PII from output. |
| `profile` | `keyword list` | Persistent browser profile. E.g. `[name: "session", save_changes: true]`. |
| `zero_data_retention` | `boolean` | Enable zero data retention. |

## Interact

### Why use it

Use interact when a page requires browser actions or code execution after a scrape starts.

### 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
)
```

To end the session:

```elixir
{:ok, _} = Firecrawl.stop_interactive_scrape_browser_session(job_id)
```

### Parameters

| Parameter | Type | Description |
|---|---|---|
| `job_id` | `string` | Scrape job ID (first positional argument). |
| `code` | `string` | Code to run in the browser session (required). |
| `language` | `atom` | Runtime: `:python`, `:node`, `:bash`. |
| `timeout` | `integer` | Execution timeout in seconds. |

The Elixir SDK exposes code-based interactions only — there is no `prompt` parameter (unlike JS/TS, Python, and Rust SDKs).

## Notes

- The Elixir SDK is auto-generated from the OpenAPI spec. Function names match the spec operations.
- Each function has a bang (`!`) variant that raises on error instead of returning `{:error, _}`.
- Parameters use `snake_case` in Elixir and are auto-converted to `camelCase` for the JSON body.
- OpenAPI enum values are represented as Elixir atoms (e.g. `proxy: :basic`, `language: :node`).
- No client struct — configuration via Application config or per-call opts.
- Uses the `Req` HTTP library. Extra opts are passed through to `Req`.

## Source Of Truth

- `firecrawl/apps/elixir-sdk/mix.exs`
- `firecrawl/apps/elixir-sdk/lib/firecrawl.ex`
- `firecrawl-docs/api-reference/v2-openapi.json`
Loading