Curl Source of Truth - Firecrawl Docs

Canonical Firecrawl curl source of truth for agents. Aligned with api-reference/v2-openapi.json (server base URL https://api.firecrawl.dev/v2).

Authenticate

export FIRECRAWL_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.
support/ask: use when a Firecrawl API call fails or returns unexpected results and you need a diagnosis.
support/docs-search: use when you need to look up Firecrawl documentation.

Search

Why use it

Use search to discover relevant pages from a query, then pick URLs to scrape or interact with. You can constrain results to a site with site:, for example site:docs.firecrawl.dev crawl webhooks.

Endpoint

POST /search

Simple Example

curl -X POST "https://api.firecrawl.dev/v2/search" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "site:docs.firecrawl.dev webhook retries"
  }'

Complex Example

curl -X POST "https://api.firecrawl.dev/v2/search" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "site:docs.firecrawl.dev crawl webhooks",
    "sources": [{"type": "web"}, {"type": "news"}],
    "categories": [{"type": "research"}],
    "limit": 10,
    "tbs": "qdr:m",
    "location": "San Francisco,California,United States",
    "country": "US",
    "ignoreInvalidURLs": true,
    "timeout": 60000,
    "enterprise": ["anon"],
    "scrapeOptions": {
      "formats": [
        "markdown",
        "links",
        {"type": "json", "prompt": "Extract title and key endpoints."}
      ],
      "onlyMainContent": true,
      "includeTags": ["main", "article"],
      "excludeTags": ["nav", "footer"],
      "waitFor": 1000
    }
  }'

Response

Successful responses include success, data, optional warning, id, and creditsUsed.

data.web, data.images, data.news: result arrays; which keys appear depends on sources (by default only data.web is populated).
data.tools: array of DiscoveredTool objects; present when domainTools is enabled or an alexandria source is included.
Web and news items include fields such as title, url, and (when scrapeOptions / formats request it) markdown, html, rawHtml, links, screenshot, audio, video, and metadata.
Image items include fields such as imageUrl, url, and dimensions when available.
warning: optional human-readable notice.
id: search job id string.
creditsUsed: integer credits charged for the call.

Parameters

query
- Type: string (required, max length 500)
- Use when: you need a search query.
- Notes: use site:example.com to limit results to a domain.
sources
- Type: array of typed source objects
- Use when: you want to control which sources are searched.
- Confirmed object shapes:
  - { "type": "web" } with optional per-source tbs and location
  - { "type": "news" }
  - { "type": "images" }
  - { "type": "alexandria" } (free; returns tool contracts instead of web results)
categories
- Type: array of typed category objects
- Use when: you want to filter results by category.
- Confirmed object shapes:
  - { "type": "developer" }
  - { "type": "research" }
  - { "type": "pdf" }
limit
- Type: integer (minimum 1, maximum 100, default 10)
- Use when: you want to cap results.
tbs
- Type: string
- Use when: you need a time-based filter (for example qdr:d, qdr:w, sbd:1,qdr:m).
location
- Type: string
- Use when: you want localized results.
country
- Type: string (default "US")
- Use when: you want ISO 3166-1 alpha-2 targeting (for example "US").
ignoreInvalidURLs
- Type: boolean (default false)
- Use when: you want to drop URLs that cannot be scraped by other endpoints.
timeout
- Type: integer (milliseconds, default 60000)
- Use when: you need a request timeout in milliseconds.
enterprise
- Type: array of strings ("anon" or "zdr" per item)
- Use when: you need enterprise search controls.
- Values:
  - "zdr": end-to-end zero data retention
  - "anon": anonymized zero data retention
includeDomains
- Type: array of strings (hostname format)
- Use when: you want to restrict results to specific domains.
- Notes: cannot be used together with excludeDomains.
excludeDomains
- Type: array of strings (hostname format)
- Use when: you want to exclude specific domains from results.
- Notes: cannot be used together with includeDomains.
highlights
- Type: boolean (default true)
- Use when: you want query-relevant highlights in search results.
safe
- Type: boolean
- Use when: you want to filter explicit content (SafeSearch).
domainTools
- Type: boolean
- Use when: you want to include tool contracts matching result domains.
threatProtection
- Type: ThreatProtectionOverride object
- Use when: you need per-request threat protection settings.
- Fields: mode ("off" | "normal"), riskScoreThreshold (0-100), blacklist (string[]), whitelist (string[]), blockedTlds (string[]), failurePolicy ("open" | "closed").
scrapeOptions
- Type: object
- Use when: you want to scrape each search result (see Scrape parameters for fields).

Scrape

Why use it

Use scrape when you already have a URL and want structured content in one or more formats.

Endpoint

POST /scrape

Simple Example

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

Complex Example

curl -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "formats": [
      "markdown",
      "links",
      {"type": "json", "prompt": "Extract plan names and prices."},
      {"type": "screenshot", "fullPage": true, "quality": 80, "viewport": {"width": 1280, "height": 720}},
      {"type": "changeTracking", "modes": ["git-diff"], "tag": "pricing"}
    ],
    "headers": {"User-Agent": "FirecrawlDocsBot/1.0"},
    "onlyMainContent": true,
    "waitFor": 1000,
    "parsers": [{"type": "pdf", "mode": "auto", "maxPages": 5}],
    "actions": [
      {"type": "click", "selector": "#accept"},
      {"type": "wait", "milliseconds": 750},
      {"type": "scrape"}
    ],
    "location": {"country": "US", "languages": ["en-US"]},
    "removeBase64Images": true,
    "blockAds": true,
    "proxy": "auto",
    "maxAge": 86400000,
    "minAge": 1,
    "storeInCache": true,
    "profile": {"name": "docs-session", "saveChanges": true},
    "zeroDataRetention": false
  }'

Response

Successful responses include success and data. Common data fields (depending on formats and options):

markdown, summary, html, rawHtml, screenshot, audio, video, links
actions: when the request included scrape-time actions, contains ordered results such as screenshots, scrapes, javascriptReturns, and pdfs
metadata: page metadata (title, sourceURL, url, statusCode, error, and other extracted fields)
warning: optional extraction or formatting notice
changeTracking: present when the changeTracking format is requested

Parameters

url
- Type: string
- Use when: you want to scrape a specific page.
formats
- Type: array of format strings or format objects
- Use when: you want multiple output formats.
- Confirmed format strings:
  - "markdown": markdown content
  - "html": cleaned HTML
  - "rawHtml": raw HTML
  - "rawBase64": base64-encoded response body
  - "links": page links
  - "images": image URLs
  - "screenshot": screenshot output
  - "summary": summary output
  - "changeTracking": change tracking output
  - "json": JSON extraction
  - "branding": branding profile output
  - "product": product profile output
  - "menu": menu profile output
  - "audio": audio extraction
  - "video": video extraction
- Format object forms:
  - type: one of the format strings above
  - prompt, schema: JSON extraction options for type: "json"
  - modes, schema, prompt, tag: change tracking options for type: "changeTracking"
  - fullPage, quality, viewport: screenshot options for type: "screenshot"
  - { "type": "question", "question": "..." }: question-answering format (required question, max 10000 chars)
  - { "type": "highlights", "query": "..." }: highlight extraction format (required query, max 10000 chars)
headers
- Type: object
- Use when: you need custom request headers.
includeTags
- Type: array of strings
- Use when: you want to include only specific HTML tags.
excludeTags
- Type: array of strings
- Use when: you want to exclude specific HTML tags.
onlyMainContent
- Type: boolean (default true)
- Use when: you want to strip nav, footer, and other boilerplate.
timeout
- Type: number (default 60000, minimum 1000, maximum 300000)
- Use when: you need a timeout in milliseconds.
waitFor
- Type: number
- Use when: you need to wait for the page to render (milliseconds).
mobile
- Type: boolean
- Use when: you want a mobile viewport.
parsers
- Type: array of objects (default ["pdf"])
- Use when: you need file parsing controls.
- Confirmed shape: { "type": "pdf", "mode": "fast" | "auto" | "ocr", "maxPages": number, "pages": boolean, "blocks": boolean, "pageMarkers": boolean } (type required; other fields optional with defaults per spec)
actions
- Type: array of action objects
- Use when: you need lightweight pre-scrape actions.
- Confirmed action types:
  - wait: milliseconds or selector required
  - screenshot: fullPage, quality, viewport optional
  - click: selector required, all optional
  - write: text required (click to focus the input first)
  - press: key required
  - scroll: type required; direction (up or down, default down); optional selector
  - scrape: no additional fields
  - executeJavascript: script required
  - pdf: format (A0, A1, A2, A3, A4, A5, A6, Letter, Legal, Tabloid, Ledger), landscape, scale optional
location
- Type: object with country and languages
- Use when: you need geo or language-aware scraping.
skipTlsVerification
- Type: boolean (default true)
- Use when: you need to skip TLS verification.
removeBase64Images
- Type: boolean (default true)
- Use when: you want to drop base64 images from markdown output.
blockAds
- Type: boolean (default true)
- Use when: you want ad and cookie popup blocking.
proxy
- Type: string (default "auto")
- Use when: you need proxy control.
- Confirmed values: "basic", "enhanced", "auto"
maxAge
- Type: number (default 172800000, i.e. 2 days)
- Use when: you want cached data up to a maximum age (milliseconds).
minAge
- Type: number
- Use when: you want cached data only if it is at least this old (milliseconds).
storeInCache
- Type: boolean (default true)
- Use when: you want Firecrawl to cache the result.
profile
- Type: object with name and optional saveChanges
- Use when: you want a persistent browser profile shared across scrapes and interactions.
zeroDataRetention
- Type: boolean
- Use when: you want zero data retention for this scrape.
lockdown
- Type: boolean (default false)
- Use when: you want to serve from cache only, never making an outbound request. ZDR. 5 credits on cache hit, 1 on miss.
redactPII
- Type: boolean or RedactPIIOptions object (default false)
- Use when: you want to redact PII from returned markdown.
- Notes: true for defaults. Object form: { "mode": "accurate" | "aggressive" | "fast", "entities": ["PERSON", "EMAIL", "PHONE", "LOCATION", "FINANCIAL", "SECRET"], "replaceStyle": "tag" | "mask" | "remove" }.
auditMetadata
- Type: object
- Use when: you need user attribution for SIEM logging.
- Fields: username (string, max 1024 chars).
domainTools
- Type: boolean (default false)
- Use when: you want to discover Alexandria tool contracts for the scraped domain.
threatProtection
- Type: ThreatProtectionOverride object
- Use when: you need per-request threat protection settings.
- Fields: mode ("off" | "normal"), riskScoreThreshold (0-100), blacklist (string[]), whitelist (string[]), blockedTlds (string[]), failurePolicy ("open" | "closed").
alexandria
- Type: AlexandriaCall or array of AlexandriaCall (1-10)
- Use when: you want to execute catalogued provider tools instead of scraping a URL.
- Each call: { "provider": string, "capability": string, "options": object }.
onlyCleanContent
- Type: boolean (default false, beta)
- Use when: you want an LLM-based pass to remove residual boilerplate from output.

Interact

Why use it

Use interact when a page requires browser actions or code execution after a scrape starts.

Endpoint

POST /scrape/{jobId}/interact

Simple Example

curl -X POST "https://api.firecrawl.dev/v2/scrape/<jobId>/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "console.log(await page.title());"
  }'

Complex Example

curl -X POST "https://api.firecrawl.dev/v2/scrape/<jobId>/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "const title = await page.title();\nconst h1 = await page.locator(\"h1\").first().textContent().catch(() => null);\nconsole.log(JSON.stringify({ title, h1 }));",
    "language": "node",
    "timeout": 120
  }'

Parameters

jobId (path)
- Type: string (UUID)
- Use when: you have the scrape job id for the live browser session.
code (JSON body)
- Type: string (required in OpenAPI; min length 1, max length 100000)
- Use when: you want to run code in the scrape-bound browser sandbox.
language (JSON body)
- Type: string
- Use when: you need a specific runtime.
- Confirmed values: "python", "node", "bash" (default "node")
timeout (JSON body)
- Type: integer (seconds; minimum 1, maximum 300, default 30)
- Use when: you need an execution timeout.
origin (JSON body)
- Type: string (optional)
- Use when: you want to attach an origin label to the interaction.

Response

Successful responses include success plus execution fields such as stdout, result (alias of stdout), stderr, exitCode, killed, error (nullable), cdpUrl, and interactiveLiveViewUrl.

DELETE /scrape//interact

Example

curl -X DELETE "https://api.firecrawl.dev/v2/scrape/<jobId>/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

No JSON body. A successful response includes success.

Ask (Agentic Debugging)

Why use it

Use ask when a Firecrawl API call fails or returns unexpected results. The AI support agent diagnoses the issue, proposes fix parameters, and optionally validates the fix against the live API. Typical latency: 15-30 seconds.

Endpoint

POST /support/ask

Simple Example

curl -X POST "https://api.firecrawl.dev/v2/support/ask" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "my scrape returned empty markdown for https://example.com"
  }'

Complex Example

curl -X POST "https://api.firecrawl.dev/v2/support/ask" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "crawl returned 3 pages but I expected 50",
    "rationale": "user is on their third failed crawl attempt today",
    "context": {"userPlan": "standard", "retryCount": 3}
  }'

Response

Successful responses include requestId, answer, confidence, fixParameters, validation, usage, and durationMs.

answer: 2-4 sentence prose covering the diagnosis and fix.
confidence: high, medium, or low.
fixParameters: machine-actionable API parameters to apply the fix (null if no fix applies).
validation.tested: whether the agent tested the fix against the live API.
validation.result: success, failure, or skipped.
feedback: present when the agent gets stuck; null on success.

Parameters

question
- Type: string (required, 1-8000 chars)
- Use when: you need to describe the issue.
rationale
- Type: string (1-2000 chars)
- Use when: you are an AI agent calling on behalf of a user. Describe what the user is trying to accomplish.
context
- Type: object (free-form)
- Use when: you want to pass metadata from your agent into the debugging prompt.

Docs Search

Why use it

Use docs-search to look up Firecrawl documentation.

Endpoint

POST /support/docs-search

Example

curl -X POST "https://api.firecrawl.dev/v2/support/docs-search" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "how do I verify webhook signatures?"
  }'

Parameters

question
- Type: string (required, 1-8000 chars)
- Use when: you need a docs-grounded answer.

Notes

Search result rows are nested under data.web, data.images, or data.news, not as a flat data array.
Use POST /scrape/{jobId}/interact for multi-step browser workflows; scrape actions are best for small pre-scrape steps.
The published OpenAPI schema requires code for interact. Some SDKs and clients also accept a prompt field for natural-language instructions; that alias is not in v2-openapi.json.

Source Of Truth

firecrawl-docs/api-reference/v2-openapi.json
firecrawl/apps/js-sdk/firecrawl/src/v2/types.ts
firecrawl/apps/python-sdk/firecrawl/v2/types.py
firecrawl/apps/rust-sdk/src/v2/scrape.rs

​Authenticate

​When To Use What

​Search

​Why use it

​Endpoint

​Simple Example

​Complex Example

​Response

​Parameters

​Scrape

​Why use it

​Endpoint

​Simple Example

​Complex Example

​Response

​Parameters

​Interact

​Why use it

​Endpoint

​Simple Example

​Complex Example

​Parameters

​Response

​DELETE /scrape//interact

​Example

​Ask (Agentic Debugging)

​Why use it

​Endpoint

​Simple Example

​Complex Example

​Response

​Parameters

​Docs Search

​Why use it

​Endpoint

​Example

​Parameters

​Notes

​Source Of Truth

Authenticate

When To Use What

Search

Why use it

Endpoint

Simple Example

Complex Example

Response

Parameters

Scrape

Why use it

Endpoint

Simple Example

Complex Example

Response

Parameters

Interact

Why use it

Endpoint

Simple Example

Complex Example

Parameters

Response

DELETE /scrape//interact

Example

Ask (Agentic Debugging)

Why use it

Endpoint

Simple Example

Complex Example

Response

Parameters

Docs Search

Why use it

Endpoint

Example

Parameters

Notes

Source Of Truth