> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-9xul69.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Curl Source of Truth > Canonical Firecrawl curl source of truth for agents using search, scrape, and interact. # 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: ```bash theme={null} 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 ```bash theme={null} 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 ```json theme={null} { "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 ```bash theme={null} 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: ```bash theme={null} 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 ```json theme={null} { "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 ```bash theme={null} 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 ```json theme={null} { "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 ```bash theme={null} 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`