Skip to content

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

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 files for all SDK languages #1219

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
211 changes: 211 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,211 @@
---
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 Firecrawl via the Elixir SDK. It is generated from SDK source and OpenAPI spec.

## Install

Add to `mix.exs`:

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

Then run:

```bash
mix deps.get
```

## Authenticate

Set the API key globally in your config:

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

Or pass it per-request:

```elixir
Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-YOUR_API_KEY")
```

All functions accept an optional trailing keyword list (`opts`) that supports `:api_key` and `:base_url` (for self-hosted instances, default `"https://api.firecrawl.dev/v2"`).

## When To Use What

- **`search_and_scrape`**: Use when you start with a query and need to discover relevant URLs and their content.
- **`scrape_and_extract_from_url`**: Use when you already have a specific URL and want its page content in markdown, HTML, JSON, or other formats.
- **`interact_with_scrape_browser_session`**: Use when the page needs post-scrape browser actions like clicking, typing, scrolling, or executing code in a live browser session.

## Search

### Why use it

Search the web for a query and optionally scrape the results. Returns categorized results from web, news, and image sources with optional content extraction.

### Preferred SDK method

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

Bang variant: `Firecrawl.search_and_scrape!(params, opts)` raises on error.

### Example

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

IO.inspect(response.body)
```

### Parameters

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

| Parameter | Elixir Key | JSON Key | Type | Description |
|---|---|---|---|---|
| query | `:query` | `"query"` | `:string` | The search query (required). |
| limit | `:limit` | `"limit"` | `:integer` | Maximum number of results. Server default: `10`. |
| sources | `:sources` | `"sources"` | `{:list, :any}` | Sources to search: `"web"`, `"news"`, `"images"`. |
| categories | `:categories` | `"categories"` | `{:list, :any}` | Filter by category: `"github"`, `"research"`, `"pdf"`, `"developer"`. |
| include_domains | `:include_domains` | `"includeDomains"` | `{:list, :string}` | Restrict results to these domains. |
| exclude_domains | `:exclude_domains` | `"excludeDomains"` | `{:list, :string}` | Exclude results from these domains. |
| tbs | `:tbs` | `"tbs"` | `:string` | Time-based filter (e.g. `"qdr:d"` for past day). |
| location | `:location` | `"location"` | `:string` | Location for geo-targeted search. |
| country | `:country` | `"country"` | `:string` | ISO country code (e.g. `"US"`). |
| ignore_invalid_urls | `:ignore_invalid_urls` | `"ignoreInvalidURLs"` | `:boolean` | Ignore invalid URLs in results. |
| timeout | `:timeout` | `"timeout"` | `:integer` | Timeout in milliseconds. Server default: `60000`. |
| highlights | `:highlights` | `"highlights"` | `:boolean` | Generate query-relevant highlights. Server default: `true`. |
| scrape_options | `:scrape_options` | `"scrapeOptions"` | `:keyword_list` | Nested scrape configuration. |
| enterprise | `:enterprise` | `"enterprise"` | `{:list, :string}` | Enterprise ZDR options: `["zdr"]` or `["anon"]`. |

## Scrape

### Why use it

Scrape a single URL and get its content in one or more formats. Supports browser automation, LLM extraction, screenshots, and more.

### Preferred SDK method

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

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://example.com",
formats: ["markdown", "html"],
only_main_content: true
)

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

### Parameters

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

| Parameter | Elixir Key | JSON Key | Type | Description |
|---|---|---|---|---|
| url | `:url` | `"url"` | `:string` | The URL to scrape (required). |
| formats | `:formats` | `"formats"` | `{:list, :any}` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"json"`, etc. Server default: `["markdown"]`. |
| only_main_content | `:only_main_content` | `"onlyMainContent"` | `:boolean` | Strip boilerplate. Server default: `true`. |
| headers | `:headers` | `"headers"` | `:any` | Custom HTTP headers. |
| include_tags | `:include_tags` | `"includeTags"` | `{:list, :string}` | HTML tags to include. |
| exclude_tags | `:exclude_tags` | `"excludeTags"` | `{:list, :string}` | HTML tags to exclude. |
| timeout | `:timeout` | `"timeout"` | `:integer` | Timeout in ms. Min: `1000`, max: `300000`. Server default: `60000`. |
| wait_for | `:wait_for` | `"waitFor"` | `:integer` | Delay in ms before fetching content. |
| mobile | `:mobile` | `"mobile"` | `:boolean` | Emulate mobile device. |
| parsers | `:parsers` | `"parsers"` | `{:list, :any}` | Parser configurations. Server default: `["pdf"]`. |
| actions | `:actions` | `"actions"` | `{:list, :any}` | Browser automation actions. |
| location | `:location` | `"location"` | `:keyword_list` | Location settings. |
| skip_tls_verification | `:skip_tls_verification` | `"skipTlsVerification"` | `:boolean` | Skip TLS verification. |
| remove_base64_images | `:remove_base64_images` | `"removeBase64Images"` | `:boolean` | Remove base64 images. Server default: `true`. |
| block_ads | `:block_ads` | `"blockAds"` | `:boolean` | Block advertisements. Server default: `true`. |
| proxy | `:proxy` | `"proxy"` | `:basic \| :enhanced \| :auto` | Proxy type. Server default: `:auto`. |
| max_age | `:max_age` | `"maxAge"` | `:integer` | Use cached result if younger than this (ms). |
| min_age | `:min_age` | `"minAge"` | `:integer` | Cache-only mode. Set to `1` for any cached data. |
| store_in_cache | `:store_in_cache` | `"storeInCache"` | `:boolean` | Cache the result. Server default: `true`. |
| lockdown | `:lockdown` | `"lockdown"` | `:boolean` | Only serve cached results. |
| redact_pii | `:redact_pii` | `"redactPII"` | `:boolean` | Redact PII from content. |
| profile | `:profile` | `"profile"` | `:keyword_list` | Browser profile for session continuity. |
| audit_metadata | `:audit_metadata` | `"auditMetadata"` | `:keyword_list` | User attribution: `[username: "..."]`. |
| zero_data_retention | `:zero_data_retention` | `"zeroDataRetention"` | `:boolean` | Enable zero data retention. |

## Interact

### Why use it

Execute code in a live browser session tied to a scrape job. Use for post-scrape interactions like clicking buttons, filling forms, or running scripts.

### Preferred SDK method

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

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")
job_id = scrape_response.body["data"]["metadata"]["jobId"]

{:ok, result} = Firecrawl.interact_with_scrape_browser_session(job_id,
code: "document.title",
language: :node
)

IO.inspect(result.body)

Firecrawl.stop_interactive_scrape_browser_session(job_id)
```

### Parameters

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

| Parameter | Elixir Key | JSON Key | Type | Description |
|---|---|---|---|---|
| job_id | first argument | URL path | `String.t()` | The scrape job ID (required). |
| code | `:code` | `"code"` | `:string` | Code to execute in the browser sandbox (required). |
| language | `:language` | `"language"` | `:python \| :node \| :bash` | Execution language. Server default: `:node`. |
| timeout | `:timeout` | `"timeout"` | `:integer` | Execution timeout in seconds. Range: 1-300. Server default: `30`. |
| origin | `:origin` | `"origin"` | `:string` | Origin label for telemetry. |

Use `Firecrawl.stop_interactive_scrape_browser_session(job_id)` to end the browser session.

## Notes

- **Naming style**: Parameters use snake_case atom keys. The SDK converts them to camelCase JSON keys 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`, not `scrape`).
- **Return type**: All functions return `{:ok, %Req.Response{}}` or `{:error, exception}`. The bang variants (`!`) raise on error and return `Req.Response.t()` directly. HTTP 4xx/5xx responses raise `Firecrawl.Error` with `:status` and `:body` fields.
- **No `prompt` support**: Unlike JS/Python/Rust, the Elixir SDK `interact_with_scrape_browser_session` only accepts `code`, not a natural-language `prompt`.
- **Origin auto-injection**: The SDK automatically injects `"origin": "elixir-sdk@{version}"` into 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