Firecrawl Curl Agent Quickstart

This file is the canonical quickstart for external agents using the Firecrawl REST API directly. It is generated from the Firecrawl OpenAPI spec (v2-openapi.json).

Base URL

https://api.firecrawl.dev/v2

Authenticate

Pass your API key in the Authorization header:

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

The API key can be omitted for the keyless free tier (rate-limited per IP) on scrape, search, and interact.

When To Use What

POST /search — Use when you start with a query and need to discover relevant URLs. Returns search results and optionally scrapes each result page.
POST /scrape — Use when you already have a URL and want page content (markdown, HTML, screenshots, structured JSON, etc.).
POST /scrape/{jobId}/interact — Use when the page needs post-scrape browser actions: executing code in the live browser session.

Search

Why use it

Search the web for a query and get back results with metadata. Optionally scrape each result page by passing scrapeOptions.

Endpoint

POST /v2/search

Example

curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "firecrawl web scraping API",
    "limit": 5,
    "scrapeOptions": {
      "formats": ["markdown"]
    }
  }'

Parameters

Parameter	Type	Required	Default	Description
`query`	`string`	Yes	—	The search query. Max length: 500.
`sources`	`array`	No	`["web"]`	Sources to search. Each item: `{"type": "web"}`, `{"type": "news"}`, or `{"type": "images"}`.
`categories`	`array`	No	`[]`	Category filters. Each item: `{"type": "github"}`, `{"type": "research"}`, or `{"type": "pdf"}`.
`includeDomains`	`string[]`	No	—	Restrict to these domains (hostnames only). Cannot use with `excludeDomains`.
`excludeDomains`	`string[]`	No	—	Exclude these domains. Cannot use with `includeDomains`.
`limit`	`integer`	No	`10`	Max results per source type. Min: 1, Max: 100.
`tbs`	`string`	No	—	Time-based search filter. `"qdr:h"` (hour), `"qdr:d"` (day), `"qdr:w"` (week), `"qdr:m"` (month), `"qdr:y"` (year). Custom: `"cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY"`. Sort by date: `"sbd:1"`. Combinable: `"sbd:1,qdr:w"`.
`location`	`string`	No	—	Location for geo-targeted results (e.g. `"San Francisco,California,United States"`).
`country`	`string`	No	`"US"`	ISO country code.
`timeout`	`integer`	No	`60000`	Timeout in milliseconds.
`ignoreInvalidURLs`	`boolean`	No	`false`	Skip invalid URLs.
`highlights`	`boolean`	No	`true`	Generate query-relevant highlights.
`enterprise`	`string[]`	No	—	Enterprise options: `["anon"]` for anonymized ZDR, `["zdr"]` for full ZDR.
`scrapeOptions`	`object`	No	`{}`	Options for scraping each result page (same schema as scrape body).
`threatProtection`	`object`	No	—	Per-request threat protection override (enterprise).

Response

{
  "success": true,
  "data": {
    "web": [{"url": "...", "title": "...", "description": "...", "markdown": "..."}],
    "news": [{"title": "...", "snippet": "...", "url": "...", "date": "..."}],
    "images": [{"title": "...", "imageUrl": "...", "url": "..."}]
  },
  "warning": null,
  "id": "search-job-id",
  "creditsUsed": 1
}

Scrape

Why use it

Scrape a single URL and get back its content in one or more formats. Supports markdown, HTML, screenshots, structured JSON extraction, and more.

Endpoint

POST /v2/scrape

Example

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown", "links"]
  }'

Structured JSON extraction:

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product",
    "formats": [{"type": "json", "schema": {"type": "object", "properties": {"title": {"type": "string"}, "price": {"type": "number"}}}}]
  }'

Parameters

Parameter	Type	Required	Default	Description
`url`	`string` (URI)	Yes	—	The URL to scrape.
`formats`	`array`	No	`["markdown"]`	Output formats. See Format types below.
`onlyMainContent`	`boolean`	No	`true`	Only return main content.
`onlyCleanContent`	`boolean`	No	`false`	Beta. LLM-based removal of residual boilerplate.
`includeTags`	`string[]`	No	—	HTML tags to include.
`excludeTags`	`string[]`	No	—	HTML tags to exclude.
`headers`	`object`	No	—	Custom HTTP headers.
`timeout`	`integer`	No	`60000`	Timeout in ms. Min: 1000, Max: 300000.
`waitFor`	`integer`	No	`0`	Wait time in ms before scraping.
`mobile`	`boolean`	No	`false`	Emulate mobile device.
`skipTlsVerification`	`boolean`	No	`true`	Skip TLS verification.
`parsers`	`array`	No	`["pdf"]`	Parser config. Each item: `"pdf"` or `{"type": "pdf", "mode": "fast"\|"auto"\|"ocr", "maxPages": N}`.
`actions`	`array`	No	—	Browser actions. See Action types below.
`location`	`object`	No	—	`{"country": "US", "languages": ["en-US"]}`.
`removeBase64Images`	`boolean`	No	`true`	Remove base64 images from markdown.
`blockAds`	`boolean`	No	`true`	Block ads and cookie popups.
`proxy`	`string`	No	`"auto"`	`"basic"`, `"enhanced"`, `"auto"`.
`maxAge`	`integer`	No	`172800000`	Max cache age in ms (default 2 days).
`minAge`	`integer`	No	—	Min cache age. Only checks cache, never fresh scrape. Set to `1` for any cached data.
`storeInCache`	`boolean`	No	`true`	Store result in cache.
`lockdown`	`boolean`	No	`false`	Serve only cached results. 404 on miss.
`redactPII`	`boolean \| object`	No	`false`	Redact PII. Object: `{"mode": "accurate", "entities": ["PERSON","EMAIL"], "replaceStyle": "tag"}`.
`zeroDataRetention`	`boolean`	No	`false`	Enable zero data retention.
`profile`	`object`	No	—	`{"name": "my-profile", "saveChanges": true}`.
`threatProtection`	`object`	No	—	Per-request threat protection override (enterprise).
`auditMetadata`	`object`	No	—	`{"username": "agent-name"}`.

Format types

Each item in formats is either a string or an object with a type field:

Type	Extra fields	Description
`"markdown"`	—	Markdown output
`"html"`	—	Cleaned HTML
`"rawHtml"`	—	Exact unmodified HTML
`"links"`	—	List of links
`"images"`	—	Images
`"summary"`	—	Page summary
`"screenshot"`	`fullPage`, `quality`, `viewport`	Screenshot (expires 24h)
`"json"`	`schema` (JSON Schema), `prompt`	LLM extraction to JSON
`"changeTracking"`	`modes` (`["git-diff","json"]`), `schema`, `prompt`, `tag`	Change tracking
`"branding"`	—	Brand info
`"product"`	—	Product info
`"menu"`	—	Menu extraction
`"audio"`	—	Audio from video URLs (signed URL, 1h)
`"video"`	—	Video extraction (signed URL, 1h)
`"question"`	`question` (required)	Ask a question about the page
`"highlights"`	`query` (required)	Find relevant source text

Action types

Type	Required fields	Optional fields	Description
`"wait"`	`milliseconds` or `selector`	—	Wait by duration or for element
`"screenshot"`	—	`fullPage`, `quality`, `viewport`	Take screenshot
`"click"`	`selector`	`all`	Click element(s)
`"write"`	`text`	—	Type text into focused element
`"press"`	`key`	—	Press a key
`"scroll"`	—	`direction` (`"up"`/`"down"`), `selector`	Scroll
`"scrape"`	—	—	Scrape current page
`"executeJavascript"`	`script`	—	Execute JS
`"pdf"`	—	`format`, `landscape`, `scale`	Generate PDF

Response

{
  "success": true,
  "data": {
    "markdown": "...",
    "html": null,
    "rawHtml": null,
    "screenshot": null,
    "links": ["..."],
    "metadata": {
      "title": "...",
      "description": "...",
      "sourceURL": "https://example.com",
      "url": "https://example.com",
      "statusCode": 200
    },
    "warning": null
  }
}

Interact

Why use it

Execute code in the live browser session that was created by a prior scrape call. Use this for multi-step workflows: running scripts, navigating, or extracting additional data from the page.

Endpoint

POST /v2/scrape/{jobId}/interact

Example

curl -X POST https://api.firecrawl.dev/v2/scrape/JOB_ID/interact \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "document.title",
    "language": "node",
    "timeout": 30
  }'

Parameters

Parameter	Type	Required	Default	Description
`jobId`	`string` (UUID)	Yes	—	Path parameter. The scrape job ID.
`code`	`string`	Yes	—	Code to execute. Min: 1, Max: 100000 chars.
`language`	`string`	No	`"node"`	`"python"`, `"node"`, or `"bash"`.
`timeout`	`integer`	No	`30`	Timeout in seconds. Min: 1, Max: 300.
`origin`	`string`	No	—	Origin label for telemetry.

Response

{
  "success": true,
  "cdpUrl": null,
  "liveViewUrl": "https://...",
  "interactiveLiveViewUrl": "https://...",
  "output": null,
  "stdout": "Example Domain",
  "result": "Example Domain",
  "stderr": null,
  "exitCode": 0,
  "killed": false,
  "error": null
}

Stop interaction

curl -X DELETE https://api.firecrawl.dev/v2/scrape/JOB_ID/interact \
  -H "Authorization: Bearer fc-YOUR_API_KEY"

Response: {"success": true, "sessionDurationMs": 12345, "creditsBilled": 1}.

Notes

code is required — The OpenAPI spec requires code for the interact endpoint. Some SDKs (Node.js, Python, Rust) additionally support a prompt parameter for natural-language interaction, but the REST API requires code.
scrapeOptions in search — The full set of scrape options can be passed inside search to scrape each result page.
Error responses — All errors return {"success": false, "error": "..."} with appropriate HTTP status codes (400, 402, 404, 408, 409, 410, 429, 500).

Source Of Truth

firecrawl-docs/api-reference/v2-openapi.json

Getting Started

AI Tools

Agent Harnesses

LLM SDKs and Frameworks

Agent Endpoint

Agentic Debugging

Cookbooks

Curl Source of Truth

Firecrawl Curl Agent Quickstart

Base URL

Authenticate

When To Use What

Search

Why use it

Endpoint

Example

Parameters

Response

Scrape

Why use it

Endpoint

Example

Parameters

Format types

Action types

Response

Interact

Why use it

Endpoint

Example

Parameters

Response

Stop interaction

Notes

Source Of Truth

​Firecrawl Curl Agent Quickstart

​Base URL

​Authenticate

​When To Use What

​Search

​Why use it

​Endpoint

​Example

​Parameters

​Response

​Scrape

​Why use it

​Endpoint

​Example

​Parameters

​Format types

​Action types

​Response

​Interact

​Why use it

​Endpoint

​Example

​Parameters

​Response

​Stop interaction

​Notes

​Source Of Truth

Firecrawl Curl Agent Quickstart

Base URL

Authenticate

When To Use What

Search

Why use it

Endpoint

Example

Parameters

Response

Scrape

Why use it

Endpoint

Example

Parameters

Format types

Action types

Response

Interact

Why use it

Endpoint

Example

Parameters

Response

Stop interaction

Notes

Source Of Truth