Firecrawl compatibility

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

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
import osfrom firecrawl import Firecrawlfirecrawl = 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)

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_..."      }    }  }}

python
from langchain_community.document_loaders import FireCrawlLoaderloader = 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

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

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.
• 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 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.