> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nativeport.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nativeport.ai/_mcp/server.

# Firecrawl

Fronts the scraping and crawling surface of [Firecrawl](https://firecrawl.dev) at `https://api.firecrawl.dev`: scrape, crawl, map, search, extract, and batch scrape, along with crawl cancellation and id-gated job status. The path following `/firecrawl/` is relayed upstream, restricted to those actions:

```
GET|POST|DELETE /firecrawl/<api path>   → https://api.firecrawl.dev/<api path>
```

Admission is default-deny against a fixed allowlist — only the admitted actions go through, and any other path draws a `404` until the endpoint concerned is added to the allowlist. Methods track Firecrawl's own docs: `POST` on the action endpoints, `GET` on the id-gated job-status reads for crawl/batch/extract (errors included), `DELETE` for crawl cancellation. The usage endpoints under `/v2/team/*`, plus `GET /v2/crawl/active`, stay out. Neither `PUT` nor `PATCH` appears on any documented endpoint.

## Common paths

| Path                              | Purpose                 |
| --------------------------------- | ----------------------- |
| `POST /firecrawl/v2/scrape`       | Scrape a single URL     |
| `POST /firecrawl/v2/crawl`        | Start a crawl           |
| `GET /firecrawl/v2/crawl/{id}`    | Crawl status            |
| `DELETE /firecrawl/v2/crawl/{id}` | Cancel a crawl          |
| `POST /firecrawl/v2/map`          | Map a site's URLs       |
| `POST /firecrawl/v2/search`       | Search the web          |
| `POST /firecrawl/v2/extract`      | Extract structured data |
| `POST /firecrawl/v2/batch/scrape` | Batch scrape            |

## Credential handling

Firecrawl reads its key from `Authorization: Bearer` — the very header carrying your gateway token — so rather than stripping that header, the gateway **replaces** it with the Firecrawl key:

* **`Authorization` is overwritten with Firecrawl's secret key.** Your gateway token stops at the gateway and never travels upstream.
* No query-param form of the key exists on Firecrawl's side, so nothing gets removed from the query string.

## Responses

Every response is **JSON** — screenshot, audio, and video payloads arrive as base64 strings or URLs *within* that JSON, never as a raw binary body.

## Examples

#### Scrape a URL

```bash
curl -X POST "$GATEWAY/firecrawl/v2/scrape" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}'
```

#### Start a crawl

```bash
curl -X POST "$GATEWAY/firecrawl/v2/crawl" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "limit": 50}'
```

#### Crawl status

```bash
curl "$GATEWAY/firecrawl/v2/crawl/{id}" \
  -H "Authorization: Bearer $TOKEN"
```

Responses arrive as Firecrawl's JSON, untouched. Field-level request and response detail lives in [Firecrawl's API reference](https://docs.firecrawl.dev/api-reference); the gateway modifies neither.