Skip to content

Add agent quickstart docs for all SDK languages #1275

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
Draft

Add agent quickstart docs for all SDK languages #1275

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
234 changes: 234 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,234 @@
---
title: "Elixir Agent Quickstart"
description: "Canonical Firecrawl Elixir quickstart for external agents using search, scrape, and interact."
og:title: "Elixir Agent Quickstart | Firecrawl"
og:description: "Canonical Firecrawl Elixir quickstart for external agents using search, scrape, and interact."
---

# Firecrawl Elixir Agent Quickstart

This file is the canonical quickstart for external agents integrating with Firecrawl using the official Elixir SDK. It is generated from SDK source and OpenAPI spec.

## Install

Add to your `mix.exs`:

```elixir
defp deps do
[
{:firecrawl, "~> 1.9"}
]
end
```

Then run:

```bash
mix deps.get
```

## Authenticate

Configure via application config:

```elixir
# config/config.exs
config :firecrawl, api_key: "fc-YOUR_API_KEY"
```

Or pass the API key per-request via the `opts` keyword:

```elixir
Firecrawl.search_and_scrape([query: "example"], api_key: "fc-YOUR_API_KEY")
```

For self-hosted instances, set the base URL:

```elixir
config :firecrawl,
api_key: "fc-YOUR_API_KEY",
base_url: "https://your-firecrawl-instance.com/v2"
```

The default base URL is `"https://api.firecrawl.dev/v2"`. Omitting the API key enables the keyless free tier (rate-limited per IP).

## When To Use What

- **`search_and_scrape`** -- Use when you start with a query and need to discover relevant URLs and their content. Returns categorized results from web, news, and images.
- **`scrape_and_extract_from_url`** -- Use when you already have a URL and want to extract page content in structured formats (markdown, HTML, JSON, screenshots, etc.).
- **`interact_with_scrape_browser_session`** -- Use when the page needs post-scrape browser actions: running code in the live browser session.

## Search

### Why use it

Search finds relevant pages across the web for a given query, optionally scraping the results. It returns results grouped by source type.

### Preferred SDK function

```elixir
Firecrawl.search_and_scrape(params, opts \\ [])
Firecrawl.search_and_scrape!(params, opts \\ [])
```

### Example

```elixir
{:ok, results} = Firecrawl.search_and_scrape(
query: "firecrawl web scraping API",
limit: 5,
highlights: true
)

IO.inspect(results)
```

The bang variant raises `Firecrawl.Error` on failure:

```elixir
results = Firecrawl.search_and_scrape!(
query: "firecrawl web scraping API",
limit: 5
)
```

### Parameters

All parameters are passed as a keyword list. Only `query` is required.

| Parameter | Type | Description |
|---|---|---|
| `query` | `:string` | The search query (required). |
| `limit` | `:integer` | Maximum number of results to return. |
| `sources` | `{:list, :any}` | Source types to search. Defaults to `["web"]`. |
| `categories` | `{:list, :any}` | Filter results by category. |
| `include_domains` | `{:list, :string}` | Only include results from these domains. |
| `exclude_domains` | `{:list, :string}` | Exclude results from these domains. |
| `tbs` | `:string` | Time-based search filter (e.g. `"qdr:d"` for past day). |
| `location` | `:string` | Geographic location for search results (e.g. `"San Francisco,California,United States"`). |
| `country` | `:string` | ISO country code for geo-targeting (e.g. `"US"`). |
| `ignore_invalid_urls` | `:boolean` | Exclude invalid URLs from results. |
| `timeout` | `:integer` | Timeout in milliseconds. |
| `highlights` | `:boolean` | Generate query-relevant highlights. Defaults to `true`. |
| `scrape_options` | `:keyword_list` | Options for scraping search results. Accepts the same parameters as scrape. |
| `enterprise` | `{:list, :string}` | Enterprise ZDR options: `["zdr"]` or `["anon"]`. |

## Scrape

### Why use it

Scrape extracts content from a single URL and returns it in one or more formats: markdown, HTML, raw HTML, JSON (via schema), screenshots, links, images, audio, video, and more.

### Preferred SDK function

```elixir
Firecrawl.scrape_and_extract_from_url(params, opts \\ [])
Firecrawl.scrape_and_extract_from_url!(params, opts \\ [])
```

### Example

```elixir
{:ok, doc} = Firecrawl.scrape_and_extract_from_url(
url: "https://example.com",
formats: ["markdown", "links"]
)

IO.puts(doc["data"]["markdown"])
```

### Parameters

All parameters are passed as a keyword list. Only `url` is required.

| Parameter | Type | Description |
|---|---|---|
| `url` | `:string` | The URL to scrape (required). |
| `formats` | `{:list, :any}` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"audio"`, `"video"`, etc. |
| `headers` | `:any` | Custom HTTP headers (cookies, user-agent, etc.). |
| `include_tags` | `{:list, :string}` | Only include content from these HTML tags. |
| `exclude_tags` | `{:list, :string}` | Exclude content from these HTML tags. |
| `only_main_content` | `:boolean` | Only return main content, excluding navbars, footers, etc. |
| `timeout` | `:integer` | Timeout in milliseconds. Default: `60000`, Min: `1000`, Max: `300000`. |
| `wait_for` | `:integer` | Wait time in milliseconds before scraping. |
| `mobile` | `:boolean` | Scrape as a mobile device. |
| `parsers` | `{:list, :any}` | File processing control (e.g. PDF settings). |
| `actions` | `{:list, :any}` | Actions to execute before content extraction. |
| `location` | `:keyword_list` | Geolocation settings. Defaults to US. |
| `skip_tls_verification` | `:boolean` | Skip TLS certificate verification. |
| `remove_base64_images` | `:boolean` | Remove base64-encoded images from markdown output. |
| `block_ads` | `:boolean` | Block advertisements and cookie popups. |
| `proxy` | `{:in, [:basic, :enhanced, :auto]}` | Proxy type. |
| `max_age` | `:integer` | Use cached result if younger than this many milliseconds. Defaults to 2 days. |
| `min_age` | `:integer` | Cache-only mode; minimum age in milliseconds. |
| `store_in_cache` | `:boolean` | Whether to cache the result. |
| `lockdown` | `:boolean` | Only serve previously cached results. |
| `redact_pii` | `:boolean` | Redact personally identifiable information. |
| `audit_metadata` | `:keyword_list` | User attribution for SIEM logging. Keys: `username` (required). |
| `profile` | `:keyword_list` | Persistent browser storage across sessions. |
| `zero_data_retention` | `:boolean` | Enable zero data retention. |

## Interact

### Why use it

Interact lets you execute code in a live browser session that was opened by a prior scrape call. Use it for clicking buttons, filling forms, navigating multi-step flows, or extracting dynamic content.

### Preferred SDK function

```elixir
Firecrawl.interact_with_scrape_browser_session(job_id, params, opts \\ [])
Firecrawl.interact_with_scrape_browser_session!(job_id, params, opts \\ [])
```

### Example

```elixir
{:ok, doc} = Firecrawl.scrape_and_extract_from_url(
url: "https://example.com",
formats: ["markdown"]
)

job_id = doc["data"]["metadata"]["jobId"]

{:ok, result} = Firecrawl.interact_with_scrape_browser_session(job_id,
code: "document.querySelector('button.load-more').click()",
language: :node,
timeout: 30
)

IO.inspect(result)
```

### Parameters

The `job_id` is passed as the first positional argument. Remaining parameters are a keyword list.

| Parameter | Type | Description |
|---|---|---|
| `job_id` | `String.t()` | The scrape job ID from a prior scrape call (required, first argument). |
| `code` | `:string` | Code to execute in the browser sandbox (required). |
| `language` | `{:in, [:python, :node, :bash]}` | Language for code execution. |
| `timeout` | `:integer` | Execution timeout in seconds. |
| `origin` | `:string` | Origin label for telemetry. |

### Stopping a session

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

## Notes

- **Naming style:** Function names and parameters use snake_case, matching Elixir conventions. The SDK converts to camelCase for the API automatically.
- **OpenAPI-generated:** The Elixir SDK is auto-generated from the OpenAPI spec. Function names match the OpenAPI operation IDs directly (e.g. `scrape_and_extract_from_url` rather than just `scrape`).
- **Return values:** Regular functions return `{:ok, response}` or `{:error, %Firecrawl.Error{}}`. Bang variants (`!`) return the response directly or raise.
- **No deprecated aliases:** The Elixir SDK does not have deprecated method aliases.
- **Per-request options:** The trailing `opts` keyword list can include `api_key:` and `base_url:` to override the application config for a single request.
- **Origin:** The SDK automatically injects `"elixir-sdk@{version}"` as the origin in every request body.

## Source Of Truth

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