Curl Source of Truth

​

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.

​

Search

​

Why use it

​

Endpoint

​

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

• data.web, data.images, data.news: result arrays; which keys appear depends on sources (by default only data.web is populated).
• Web and news items include fields such as title, url, and (when scrapeOptions / formats request it) markdown, html, rawHtml, links, screenshot, audio, 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" }
• categories
  • Type: array of typed category objects
  • Use when: you want to filter results by category.
  • Confirmed object shapes:
    • { "type": "github" }
    • { "type": "research" }
    • { "type": "pdf" }
• limit
  • Type: integer (minimum 1, maximum 100, default 5)
  • 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
• scrapeOptions
  • Type: object
  • Use when: you want to scrape each search result (see Scrape parameters for fields).

​

Scrape

​

Why use it

​

Endpoint

​

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

• markdown, summary, html, rawHtml, screenshot, audio, 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
    • "links": page links
    • "images": image URLs
    • "screenshot": screenshot output
    • "summary": summary output
    • "changeTracking": change tracking output
    • "json": JSON extraction
    • "branding": branding profile output
    • "audio": audio extraction
  • Format object fields:
    • 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"
• 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
  • Use when: you want to strip nav, footer, and other boilerplate.
• timeout
  • Type: number
  • 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
  • Use when: you need file parsing controls.
  • Confirmed shape: { "type": "pdf", "mode": "fast" | "auto" | "ocr", "maxPages": number } (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
  • Use when: you need to skip TLS verification.
• removeBase64Images
  • Type: boolean
  • Use when: you want to drop base64 images from markdown output.
• blockAds
  • Type: boolean
  • Use when: you want ad and cookie popup blocking.
• proxy
  • Type: string
  • Use when: you need proxy control.
  • Confirmed values: "basic", "enhanced", "auto"
• maxAge
  • Type: number
  • 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
  • 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.

​

Interact

​

Why use it

​

Endpoint

​

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.

​

Response

​

DELETE /scrape//interact

​

Example

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

​

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