> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beta.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Firecrawl compatibility

Point a Firecrawl SDK, the Firecrawl MCP server or LangChain's loader at B3OS by changing the base URL and key; which endpoints work and which do not.

B3OS vision serves Firecrawl's v1 and v2 HTTP APIs at `/compat/firecrawl`, with Firecrawl's field names, defaults, status codes, pagination, error bodies and webhook payloads. Code written for Firecrawl needs two changes:

```bash
export FIRECRAWL_API_URL="https://beta-api.b3os.org/compat/firecrawl"
export FIRECRAWL_API_KEY="$B3OS_API_KEY"
```

Inside a B3OS sandbox, use `http://127.0.0.1:7700/compat/firecrawl` instead; the key is not checked there, so any placeholder works.

## Clients

**TypeScript**

```ts
    import Firecrawl from "@mendable/firecrawl-js";

    const firecrawl = new Firecrawl({
      apiKey: process.env.B3OS_API_KEY,
      apiUrl: "https://beta-api.b3os.org/compat/firecrawl",
    });
    const doc = await firecrawl.scrape("https://example.com", { formats: ["markdown"] });
    console.log(doc.markdown);
    ```
  **Python**

```python
    import os
    from firecrawl import Firecrawl

    firecrawl = Firecrawl(
        api_key=os.environ["B3OS_API_KEY"],
        api_url="https://beta-api.b3os.org/compat/firecrawl",
    )
    doc = firecrawl.scrape("https://example.com", formats=["markdown"])
    print(doc.markdown)
    ```
  **Firecrawl MCP**

```json
    {
      "mcpServers": {
        "firecrawl": {
          "command": "npx",
          "args": ["-y", "firecrawl-mcp"],
          "env": {
            "FIRECRAWL_API_URL": "https://beta-api.b3os.org/compat/firecrawl",
            "FIRECRAWL_API_KEY": "b3os_sk_..."
          }
        }
      }
    }
    ```
  **LangChain**

```python
    from langchain_community.document_loaders import FireCrawlLoader

    loader = FireCrawlLoader(
        url="https://example.com",
        api_key="b3os_sk_...",
        api_url="https://beta-api.b3os.org/compat/firecrawl",
        mode="scrape",
    )
    docs = loader.load()
    ```

The release gate for this surface is that the firecrawl-js and firecrawl-py end-to-end tests, the Firecrawl MCP server and LangChain's `FireCrawlLoader` work with only the base URL and key changed.

## Endpoints

| Endpoint (v1 and v2) | Status |
|---|---|
| `POST /scrape` | Served |
| `POST /batch/scrape`, `GET` and `DELETE /batch/scrape/{id}`, `GET /batch/scrape/{id}/errors` | Served |
| `POST /crawl`, `GET` and `DELETE /crawl/{id}`, `GET /crawl/{id}/errors`, `GET /crawl/active` | Served |
| `POST /map` | Served |
| `GET /team/credit-usage` | Served |
| `POST /extract`, `GET /extract/{id}` | Planned; answers `501 not_implemented` until served |

Every other Firecrawl endpoint answers `404` with code `unsupported_endpoint` and names the B3OS alternative:

| Firecrawl endpoint | Use instead |
|---|---|
| `search` | B3OS has no search index in the beta. Search with your provider, then scrape the results with `batch/scrape`. |
| v2 `agent`, v1 `deep-research` | Run your agent in a [B3OS sandbox](/quickstart/sandbox-agent) and let it scrape. |
| v2 `interact`, `scrape/{jobId}/interact` | [Browser sessions](/vision/sessions): create one, then `act` or connect over CDP. |
| v2 `GET /scrape/{jobId}` | B3OS scrapes are synchronous; the document is in the `scrape` response. |
| v2 `parse` | Scrape the file's URL with `scrape`. |
| v2 `crawl/params-preview`, v1 `GET /crawl/{id}/params` | Set crawl parameters explicitly; `GET /v1/vision/crawls/{crawl_id}` returns the crawl as B3OS ran it. |
| v2 `monitor` | A [routine](/routines) with a cron trigger and a `vision/scrape@1` step. |
| v1 `llmstxt` | `map` the site and scrape the pages you need. |
| `team/token-usage`, the `historical` usage endpoints | [`GET /v1/usage`](/concepts/usage), grouped by day. |
| `team/queue-status`, v2 `concurrency-check` | [`GET /v1/limits`](/concepts/limits), which shows current concurrency against each limit. |

## Wire format

- Every successful body includes `success: true`. Errors use Firecrawl's shape, `{"success": false, "error": "...", "code": "..."}`, and a `400` for an invalid body adds `details`. Each B3OS error has its Firecrawl status, `code` and `error` prefix on the [errors page](/errors).
- Unknown body fields are rejected with `400` and Zod-style `details`, as Firecrawl does. The `origin` and `integration` fields the SDKs add to every request are accepted and ignored.
- An option B3OS cannot honor returns `400` with code `unsupported_option` naming it. Options are never silently ignored.
- No request is held longer than 60 seconds: a larger `timeout` is treated as 60000. Long work belongs in crawl and batch jobs. Crawl `limit` is capped at your plan's crawl limit and map `limit` at 5000.
- `next` pagination URLs are absolute and keep the `/compat/firecrawl/v1` or `/v2` prefix; the SDKs keep the path and swap in your base URL.
- `x-idempotency-key` works like `Idempotency-Key`.
- Webhooks use Firecrawl's payloads and `X-Firecrawl-Signature: sha256=<hex>`, signed with the B3OS [webhook secret](/platform/webhooks) of the receiving URL.
- B3OS additions appear only in `data.metadata.b3os` and in the `Server-Timing` and `x-request-id` headers.

## Credits

One Firecrawl credit is one `vision.page`. The credit usage endpoint reports the page allowance of your beta plan. Billing, limits and the cache work as for native [scrapes](/vision/scrape).