Skip to content

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

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

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
192 changes: 192 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,192 @@
---
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` Hex package) and the v2 OpenAPI spec. Function names match the auto-generated client from the OpenAPI spec.

## Install

Add to `mix.exs`:

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

## 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.search_and_scrape(
[query: "site:docs.firecrawl.dev webhook retries"],
api_key: "fc-your-api-key"
)
```

Self-hosted:

```elixir
{:ok, res} = Firecrawl.scrape_and_extract_from_url(
[url: "https://example.com"],
base_url: "http://localhost:3002/v2",
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:`, for example `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
]
)
```

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | string | Search query. Use `site:example.com` to limit to a domain. Required. |
| `sources` | list | Sources: `:web`, `:news`, `:images`. Default: `[:web]`. |
| `categories` | list | Filter by category. |
| `limit` | integer | Cap the number of results. |
| `tbs` | string | Time-based filter (e.g. `"qdr:d"`, `"qdr:w"`). |
| `location` | string | Localized results. |
| `country` | string | ISO country code for geo-targeting (e.g. `"US"`). |
| `ignore_invalid_urls` | boolean | Drop URLs that cannot be scraped. |
| `timeout` | integer | Request timeout in milliseconds. |
| `scrape_options` | keyword list | Scrape each search result. See Scrape parameters. |
| `include_domains` | list of strings | Only include results from these domains. |
| `exclude_domains` | list of strings | Exclude results from these domains. |
| `highlights` | boolean | Return highlights (defaults to true). |

## 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 | The page URL to scrape. Required. |
| `formats` | list | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"audio"`, `"video"`. Use maps for object forms. |
| `headers` | any | Custom request headers. |
| `include_tags` | list of strings | Include only specific HTML tags. |
| `exclude_tags` | list of strings | Exclude specific HTML tags. |
| `only_main_content` | boolean | Strip nav, footer, and boilerplate. |
| `timeout` | integer | Timeout in milliseconds. Default: 60000, min: 1000, max: 300000. |
| `wait_for` | integer | Wait for page render (milliseconds). |
| `mobile` | boolean | Use a mobile viewport. |
| `parsers` | list | Parser configs (e.g. PDF parsing). |
| `actions` | list | Pre-scrape browser actions. |
| `location` | keyword list | `[country: "US", languages: ["en-US"]]` for geo-aware scraping. |
| `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: `:basic`, `:enhanced`, `:auto`. |
| `max_age` | integer | Use cached data up to this age (milliseconds). Default: 2 days. |
| `min_age` | integer | Use cached data only if at least this old (milliseconds). |
| `store_in_cache` | boolean | Cache the result. |
| `lockdown` | boolean | Only serve cached results. |
| `profile` | keyword list | `[name: "my-profile", save_changes: true]` for persistent browser profiles. |

## Interact

### Why use it

Use interact for code-based control of the browser session tied to a scrape job. The Elixir SDK requires `code` (no `prompt` parameter).

### 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, result} = Firecrawl.interact_with_scrape_browser_session(
job_id,
code: "console.log(await page.title());",
language: :node,
timeout: 60
)

# Stop the session when done
{:ok, _} = Firecrawl.stop_interactive_scrape_browser_session(job_id)
```

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `job_id` | string | Scrape job ID from scrape response metadata `scrapeId`. |
| `code` | string | Code to run in the browser session. Required. |
| `language` | atom | Runtime: `:python`, `:node`, `:bash`. |
| `timeout` | integer | Execution timeout in seconds. |

### Stop session

`Firecrawl.stop_interactive_scrape_browser_session(job_id, opts \\ [])`

## Notes

- The Elixir client is **auto-generated from the OpenAPI spec** — function names are derived from operation IDs and may look verbose (e.g. `scrape_and_extract_from_url` instead of `scrape`).
- All functions return `{:ok, %Req.Response{}}` or `{:error, exception}`. Bang variants (e.g. `scrape_and_extract_from_url!`) raise on error.
- Parameters use `snake_case` keyword lists, but are converted to `camelCase` JSON for the API.
- Atoms in parameter values (e.g. `:node`, `:web`) are converted to strings in the request body.
- Per-call options (`api_key:`, `base_url:`) are passed in the second argument (opts).

## Source Of Truth

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