Skip to content

docs: add agent quickstart guides for all SDK languages #1341

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

docs: add agent quickstart guides for all SDK languages #1341

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
236 changes: 236 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,236 @@
---
title: "Elixir Agent Quickstart"
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 Elixir SDK. It is generated from SDK source and the OpenAPI spec.

## Install

Add to your `mix.exs` dependencies:

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

Then run:

```bash
mix deps.get
```

## Authenticate

Pass the API key as a runtime option on each call:

```elixir
opts = [api_key: "fc-YOUR_API_KEY"]
```

To use a self-hosted instance:

```elixir
opts = [api_key: "fc-YOUR_API_KEY", base_url: "https://your-instance.com"]
```

## When To Use What

- **`search_and_scrape`**: Use when you start with a query and need to discover relevant pages across the web.
- **`scrape_and_extract_from_url`**: Use when you already have a URL and want its content (markdown, HTML, structured data, screenshots, etc.).
- **`interact_with_scrape_browser_session`**: Use when a page needs post-scrape browser actions — clicking, filling forms, executing code in a live browser session.

## Search

### Why use it

Search the web for a query and optionally scrape each result in one call. Returns results grouped by source type (web, news, images).

### Preferred SDK function

```elixir
Firecrawl.search_and_scrape(params, opts)
Firecrawl.search_and_scrape!(params, opts)
```

The bang variant (`!`) raises on error instead of returning `{:error, ...}`.

### Example

```elixir
{:ok, response} = Firecrawl.search_and_scrape(
[
query: "firecrawl web scraping API",
limit: 5,
scrape_options: [formats: ["markdown"]]
],
api_key: "fc-YOUR_API_KEY"
)

IO.inspect(response.body)
```

### Parameters

Parameters are a keyword list (first argument).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | `:string` | **Yes** | The search query string. |
| `sources` | `{:list, :any}` | No | Sources to search: `"web"`, `"news"`, `"images"`. Default: `["web"]`. |
| `categories` | `{:list, :any}` | No | Filter results: `"github"`, `"research"`, `"pdf"`, `"developer"`. |
| `include_domains` | `{:list, :string}` | No | Restrict results to these domains. |
| `exclude_domains` | `{:list, :string}` | No | Exclude results from these domains. |
| `limit` | `:integer` | No | Max results per source type. Default: `10`. Max: `100`. |
| `tbs` | `:string` | No | Time-based search filter (e.g. `"qdr:d"` for past day). |
| `location` | `:string` | No | Geographic location string. |
| `country` | `:string` | No | ISO country code for geo-targeting. |
| `ignore_invalid_urls` | `:boolean` | No | Exclude invalid URLs from results. Default: `false`. |
| `timeout` | `:integer` | No | Timeout in milliseconds. Default: `60000`. |
| `highlights` | `:boolean` | No | Generate query-relevant highlights. Default: `true`. |
| `scrape_options` | `:keyword_list` | No | Options applied when scraping each result. |
| `enterprise` | `{:list, :string}` | No | Enterprise ZDR options. |

### Return type

`{:ok, %Req.Response{}}` or `{:error, exception}`. The response body contains `"data"` with `"web"`, `"news"`, `"images"` arrays.

## Scrape

### Why use it

Scrape a single URL and get back clean markdown, HTML, structured JSON, screenshots, or other formats. Supports browser actions, location targeting, and caching.

### Preferred SDK function

```elixir
Firecrawl.scrape_and_extract_from_url(params, opts)
Firecrawl.scrape_and_extract_from_url!(params, opts)
```

### Example

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

data = response.body["data"]
IO.puts(data["markdown"])
```

### Parameters

Parameters are a keyword list (first argument).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `url` | `:string` | **Yes** | The URL to scrape. |
| `formats` | `{:list, :any}` | No | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"changeTracking"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`, or maps with format-specific options. Default: `["markdown"]`. |
| `only_main_content` | `:boolean` | No | Extract main content only. Default: `true`. |
| `include_tags` | `{:list, :string}` | No | HTML tags to include. |
| `exclude_tags` | `{:list, :string}` | No | HTML tags to exclude. |
| `headers` | `:any` | No | Custom HTTP headers. |
| `timeout` | `:integer` | No | Timeout in milliseconds. Default: `60000`. |
| `wait_for` | `:integer` | No | Extra delay in ms before fetching content. Default: `0`. |
| `mobile` | `:boolean` | No | Emulate a mobile device. Default: `false`. |
| `actions` | `{:list, :any}` | No | Browser actions: wait, click, write, press, scroll, screenshot, scrape, executeJavascript, pdf. |
| `location` | `:keyword_list` | No | Location targeting with `country` and `languages`. |
| `skip_tls_verification` | `:boolean` | No | Skip TLS verification. Default: `true`. |
| `remove_base64_images` | `:boolean` | No | Remove base64 images from markdown. Default: `true`. |
| `block_ads` | `:boolean` | No | Block ads and cookie popups. Default: `true`. |
| `proxy` | `:basic \| :enhanced \| :auto` | No | Proxy type. Default: `"auto"`. |
| `max_age` | `:integer` | No | Cache max age in milliseconds. Default: `172800000` (2 days). |
| `min_age` | `:integer` | No | Cache-only: minimum cache age in ms. |
| `store_in_cache` | `:boolean` | No | Store result in cache. Default: `true`. |
| `lockdown` | `:boolean` | No | Cache-only mode. Default: `false`. |
| `parsers` | `{:list, :any}` | No | File parser configs. Default: `["pdf"]`. |
| `redact_pii` | `:boolean` | No | Redact PII from markdown. Default: `false`. |
| `profile` | `:keyword_list` | No | Persistent browser profile. |
| `audit_metadata` | `:keyword_list` | No | User attribution for SIEM logging (requires `username`). |
| `zero_data_retention` | `:boolean` | No | Enable zero data retention for this scrape. |

### Return type

`{:ok, %Req.Response{}}` or `{:error, exception}`. The response body `"data"` contains the scraped document fields.

## Interact

### Why use it

Run code in the live browser session of an existing scrape job. Use it for clicks, form fills, navigation, or any post-scrape browser automation.

### 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
# First, scrape a page to get a job ID
{:ok, scrape_response} = Firecrawl.scrape_and_extract_from_url(
[url: "https://example.com"],
api_key: "fc-YOUR_API_KEY"
)

job_id = scrape_response.body["data"]["metadata"]["scrapeId"]

# Then interact with the browser session
{:ok, response} = Firecrawl.interact_with_scrape_browser_session(
job_id,
[
code: ~s|document.querySelector("button.submit").click();|,
language: :node
],
api_key: "fc-YOUR_API_KEY"
)

IO.inspect(response.body)
```

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `job_id` | `String.t()` | **Yes** | The scrape job ID (path parameter). |
| `code` | `:string` | **Yes** | Code to execute in the browser sandbox. |
| `language` | `:python \| :node \| :bash` | No | Runtime language. Default: `"node"`. |
| `timeout` | `:integer` | No | Execution timeout in seconds. Default: `30`. Min: `1`, Max: `300`. |
| `origin` | `:string` | No | Origin label for execution telemetry. |

### Return type

`{:ok, %Req.Response{}}` or `{:error, exception}`. The response body contains `.success`, `.stdout`, `.result`, `.stderr`, `.exitCode`, `.error`.

### Stopping a session

```elixir
Firecrawl.stop_interactive_scrape_browser_session(job_id, api_key: "fc-YOUR_API_KEY")
```

## Notes

- **Naming style**: All parameters use snake_case atoms in keyword lists. The SDK serializes to camelCase for the API.
- **OpenAPI-generated**: The Elixir SDK is generated from the OpenAPI spec. Function names reflect the API operation IDs rather than shortened aliases.
- **Function naming**:
- Search: `search_and_scrape` (not `search`)
- Scrape: `scrape_and_extract_from_url` (not `scrape`)
- Interact: `interact_with_scrape_browser_session` (not `interact`)
- Stop interaction: `stop_interactive_scrape_browser_session`
- **Bang variants**: Every function has a `!` variant that raises `Firecrawl.Error` on non-2xx responses instead of returning `{:error, ...}`.
- **Req-based**: The SDK uses the `Req` HTTP library. Runtime options (second or third argument) accept `:api_key`, `:base_url`, and any `Req` option.
- **No deprecated aliases**: The Elixir SDK has no deprecated function names.

## Source Of Truth

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