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

# Scrape a URL (Firecrawl)

Firecrawl's `POST /v2/scrape`, served by vision. Same request and response fields as Firecrawl; B3OS extras are in `data.metadata.b3os` and the `Server-Timing` header. `timeout` above 60000 is treated as 60000 (no request is held longer). Options B3OS cannot honor return `400` with code `unsupported_option` instead of being ignored. Bills one `vision.page`.

` POST /compat/firecrawl/v2/scrape `

Scrape a URL (Firecrawl)

Firecrawl's `POST /v2/scrape`, served by vision. Same request and response fields as Firecrawl; B3OS extras are in `data.metadata.b3os` and the `Server-Timing` header. `timeout` above 60000 is treated as 60000 (no request is held longer). Options B3OS cannot honor return `400` with code `unsupported_option` instead of being ignored. Bills one `vision.page`.

## Servers

- ` https://beta-api.b3os.org ` — API (API keys and CLI tokens)

- ` https://beta.b3os.org ` — Dashboard (session cookie and CSRF header; same paths)

## Authentication

The operation accepts these alternatives. Schemes within one alternative are required together.

### Alternative 1

- ` apiKey `: ` http `

  - HTTP scheme: ` bearer ` (b3os_sk_ API key or b3os_pat_ token)

  - `Authorization: Bearer <credential>`. Two credential kinds are accepted:

- **API keys** `b3os_sk_<32 base32>_<crc32>`, created in the dashboard or with `POST /v1/keys`. A key belongs to
  one project, has scopes, an optional spend cap and expiry, and is shown only once.
- **CLI tokens** `b3os_pat_<32 base32>_<crc32>`, issued by the device login (`b3os login`). They act for one
  user in the organization and project chosen at approval.

Keys are stored as SHA-256 hashes. The edge exchanges them for a 60-second node token before forwarding
a request to a node, so nodes never see your key.


## Request body (required)

Content type: ` application/json `

- ` value `: type ` object `

  - Required fields: ` url `

  - ` url `: type ` string `; format ` uri ` — The URL to scrape.

  - ` formats `: type ` array `

    - default: ` [{"type":"markdown"}] `

    - ` array item `: type ` unknown ` — A format name or a format object. Supported: `markdown`, `html`, `rawHtml`, `links`, `images`, `screenshot`, and `json` and `summary` (with the node's model). Others return `unsupported_option`.

      - ` oneOf alternative 1 `: type ` string `

        - enum: ` ["markdown","summary","html","rawHtml","rawBase64","links","images","screenshot","json","changeTracking","branding","product","menu","audio","video","attributes","question","highlights"] `

      - ` oneOf alternative 2 `: type ` object `

        - Title: Simple format

        - Required fields: ` type `

        - ` type `: type ` string `

          - enum: ` ["markdown","summary","html","rawHtml","rawBase64","links","images","branding","product","menu","audio","video"] `

      - ` oneOf alternative 3 `: type ` object `

        - Title: Screenshot

        - Required fields: ` type `

        - ` type `: type ` string `

          - enum: ` ["screenshot"] `

        - ` fullPage `: type ` boolean `

          - default: ` false `

        - ` quality `: type ` integer `

          - minimum: ` 1 `

          - maximum: ` 100 `

        - ` viewport `: type ` object `

          - Required fields: ` width `, ` height `

          - ` width `: type ` integer `

          - ` height `: type ` integer `

      - ` oneOf alternative 4 `: type ` object `

        - Title: JSON

        - Required fields: ` type `

        - ` type `: type ` string `

          - enum: ` ["json"] `

        - ` schema `: type ` object `

        - ` prompt `: type ` string `

        - ` checkPromptInjection `: type ` boolean ` — Deprecated in Firecrawl. Not supported by B3OS: setting it returns `400` with code `unsupported_option`.

          - default: ` false `

      - ` oneOf alternative 5 `: type ` object ` — Not supported by B3OS: setting it returns `400` with code `unsupported_option`.

        - Title: Change tracking

        - Required fields: ` type `

        - ` type `: type ` string `

          - enum: ` ["changeTracking"] `

        - ` modes `: type ` array `

          - ` array item `: type ` string `

            - enum: ` ["git-diff","json"] `

        - ` schema `: type ` object `

        - ` prompt `: type ` string `

        - ` tag `: type ` string `; nullable

      - ` oneOf alternative 6 `: type ` object ` — Not supported by B3OS: setting it returns `400` with code `unsupported_option`.

        - Title: Attributes

        - Required fields: ` type `, ` selectors `

        - ` type `: type ` string `

          - enum: ` ["attributes"] `

        - ` selectors `: type ` array `

          - ` array item `: type ` object `

            - Required fields: ` selector `, ` attribute `

            - ` selector `: type ` string `

            - ` attribute `: type ` string `

      - ` oneOf alternative 7 `: type ` object ` — Not supported by B3OS: setting it returns `400` with code `unsupported_option`.

        - Title: Question

        - Required fields: ` type `, ` question `

        - ` type `: type ` string `

          - enum: ` ["question"] `

        - ` question `: type ` string `

          - maxLength: ` 10000 `

      - ` oneOf alternative 8 `: type ` object ` — Not supported by B3OS: setting it returns `400` with code `unsupported_option`.

        - Title: Highlights

        - Required fields: ` type `, ` query `

        - ` type `: type ` string `

          - enum: ` ["highlights"] `

        - ` query `: type ` string `

          - maxLength: ` 10000 `

  - ` onlyMainContent `: type ` boolean `

    - default: ` true `

  - ` onlyCleanContent `: type ` boolean ` — Not supported by B3OS: setting it returns `400` with code `unsupported_option`.

    - default: ` false `

  - ` includeTags `: type ` array `

    - ` array item `: type ` string `

  - ` excludeTags `: type ` array `

    - ` array item `: type ` string `

  - ` maxAge `: type ` integer ` — Accept a cached copy up to this old, in milliseconds. Default 2 days.

    - default: ` 172800000 `

  - ` minAge `: type ` integer ` — Only answer from the cache; a miss returns `404` with code `SCRAPE_NO_CACHED_DATA`.

  - ` headers `: type ` object `

  - ` waitFor `: type ` integer `

    - default: ` 0 `

    - maximum: ` 60000 `

  - ` mobile `: type ` boolean `

    - default: ` false `

  - ` skipTlsVerification `: type ` boolean `

    - default: ` true `

  - ` timeout `: type ` integer ` — Milliseconds; values above 60000 are treated as 60000.

    - default: ` 60000 `

    - minimum: ` 1000 `

    - maximum: ` 300000 `

  - ` parsers `: type ` array ` — PDF and image parsing are not supported; a non-empty list returns `unsupported_option`.

    - ` array item `: type ` unknown `

  - ` actions `: type ` array `

    - ` array item `: type ` unknown ` — A browser action, run with vision browser actions. `pdf` is not supported.

      - ` oneOf alternative 1 `: type ` object `

        - Title: Wait

        - Required fields: ` type `

        - ` type `: type ` string `

          - enum: ` ["wait"] `

        - ` milliseconds `: type ` integer `

          - minimum: ` 1 `

        - ` selector `: type ` string `

      - ` oneOf alternative 2 `: type ` object `

        - Title: Screenshot

        - Required fields: ` type `

        - ` type `: type ` string `

          - enum: ` ["screenshot"] `

        - ` fullPage `: type ` boolean `

          - default: ` false `

        - ` quality `: type ` integer `

          - minimum: ` 1 `

          - maximum: ` 100 `

        - ` viewport `: type ` object `

          - Required fields: ` width `, ` height `

          - ` width `: type ` integer `

          - ` height `: type ` integer `

      - ` oneOf alternative 3 `: type ` object `

        - Title: Click

        - Required fields: ` type `, ` selector `

        - ` type `: type ` string `

          - enum: ` ["click"] `

        - ` selector `: type ` string `

        - ` all `: type ` boolean `

          - default: ` false `

      - ` oneOf alternative 4 `: type ` object `

        - Title: Write text

        - Required fields: ` type `, ` text `

        - ` type `: type ` string `

          - enum: ` ["write"] `

        - ` text `: type ` string `

      - ` oneOf alternative 5 `: type ` object `

        - Title: Press a key

        - Required fields: ` type `, ` key `

        - ` type `: type ` string `

          - enum: ` ["press"] `

        - ` key `: type ` string `

      - ` oneOf alternative 6 `: type ` object `

        - Title: Scroll

        - Required fields: ` type `

        - ` type `: type ` string `

          - enum: ` ["scroll"] `

        - ` direction `: type ` string `

          - enum: ` ["up","down"] `

          - default: ` "down" `

        - ` selector `: type ` string `

      - ` oneOf alternative 7 `: type ` object `

        - Title: Scrape

        - Required fields: ` type `

        - ` type `: type ` string `

          - enum: ` ["scrape"] `

      - ` oneOf alternative 8 `: type ` object `

        - Title: Execute JavaScript

        - Required fields: ` type `, ` script `

        - ` type `: type ` string `

          - enum: ` ["executeJavascript"] `

        - ` script `: type ` string `

      - ` oneOf alternative 9 `: type ` object ` — Not supported by B3OS: setting it returns `400` with code `unsupported_option`.

        - Title: Generate PDF

        - Required fields: ` type `

        - ` type `: type ` string `

          - enum: ` ["pdf"] `

        - ` format `: type ` string `

        - ` landscape `: type ` boolean `

        - ` scale `: type ` number `

  - ` location `: type ` object `

    - ` country `: type ` string ` — ISO 3166-1 alpha-2 code. B3OS emulates the language and time zone; it has no per-country proxies.

      - default: ` "US" `

      - pattern: ` "^[A-Z]{2}$" `

    - ` languages `: type ` array `

      - ` array item `: type ` string `

  - ` removeBase64Images `: type ` boolean `

    - default: ` true `

  - ` blockAds `: type ` boolean `

    - default: ` true `

  - ` proxy `: type ` string ` — `basic` and `auto` fetch directly from the node; `enhanced` returns `unsupported_option` (B3OS has no proxy network).

    - enum: ` ["basic","enhanced","auto"] `

    - default: ` "auto" `

  - ` storeInCache `: type ` boolean `

    - default: ` true `

  - ` lockdown `: type ` boolean ` — Not supported by B3OS: setting it returns `400` with code `unsupported_option`.

    - default: ` false `

  - ` checkPromptInjection `: type ` boolean ` — Not supported by B3OS: setting it returns `400` with code `unsupported_option`.

    - default: ` false `

  - ` redactPII `: type ` unknown ` — Not supported by B3OS: setting it returns `400` with code `unsupported_option`.

    - ` oneOf alternative 1 `: type ` boolean `

    - ` oneOf alternative 2 `: type ` object `

  - ` profile `: type ` object ` — Load a vision profile by name; `saveChanges` saves cookies back.

    - Required fields: ` name `

    - ` name `: type ` string `

      - minLength: ` 1 `

      - maxLength: ` 128 `

    - ` saveChanges `: type ` boolean `

      - default: ` true `

  - ` zeroDataRetention `: type ` boolean ` — Do not cache or store the result.

    - default: ` false `

  - ` threatProtection `: type ` object ` — Not supported by B3OS: setting it returns `400` with code `unsupported_option`.

  - ` auditMetadata `: type ` object ` — Accepted and ignored (the Firecrawl SDKs send it).

  - ` integration `: type ` string ` — Accepted and ignored (the Firecrawl SDKs send it).

  - ` origin `: type ` string ` — Accepted and ignored (the Firecrawl SDKs send it).

Example:

```json
{
  "url": "https://example.com/pricing",
  "formats": [
    "markdown"
  ]
}
```

## Responses

### ` 200 ` — The scraped document.

Content type: ` application/json `

- ` value `: type ` object `

  - Required fields: ` success `, ` data `

  - ` success `: type ` boolean `

    - enum: ` [true] `

  - ` data `: type ` object `

    - ` markdown `: type ` string `

    - ` summary `: type ` string `; nullable

    - ` html `: type ` string `; nullable

    - ` rawHtml `: type ` string `; nullable

    - ` links `: type ` array `

      - ` array item `: type ` string `

    - ` images `: type ` array `

      - ` array item `: type ` string `

    - ` screenshot `: type ` string `; nullable — A `data:image/...;base64,` URL (B3OS returns the image inline).

    - ` json `: type ` unknown ` — Data from the `json` format.

    - ` actions `: type ` object `; nullable

      - ` screenshots `: type ` array `

        - ` array item `: type ` string `

      - ` scrapes `: type ` array `

        - ` array item `: type ` object `

          - ` url `: type ` string `

          - ` html `: type ` string `

      - ` javascriptReturns `: type ` array `

        - ` array item `: type ` object `

          - ` type `: type ` string `

          - ` value `: type ` unknown `

      - ` pdfs `: type ` array `

        - ` array item `: type ` string `

    - ` metadata `: type ` object ` — Page metadata. Other `<meta>` tags appear under their own names.

      - ` title `: type ` unknown `

        - ` oneOf alternative 1 `: type ` string `

        - ` oneOf alternative 2 `: type ` array `

          - ` array item `: type ` string `

      - ` description `: type ` unknown `

        - ` oneOf alternative 1 `: type ` string `

        - ` oneOf alternative 2 `: type ` array `

          - ` array item `: type ` string `

      - ` language `: type ` unknown `

        - ` oneOf alternative 1 `: type ` string `; nullable

        - ` oneOf alternative 2 `: type ` array `

          - ` array item `: type ` string `

      - ` sourceURL `: type ` string `; format ` uri ` — The requested URL.

      - ` url `: type ` string `; format ` uri ` — The final URL after redirects.

      - ` keywords `: type ` unknown `

        - ` oneOf alternative 1 `: type ` string `

        - ` oneOf alternative 2 `: type ` array `

          - ` array item `: type ` string `

      - ` ogLocaleAlternate `: type ` array `

        - ` array item `: type ` string `

      - ` statusCode `: type ` integer `

      - ` contentType `: type ` string `

      - ` error `: type ` string `; nullable

      - ` scrapeId `: type ` string ` — The B3OS request ID of the scrape.

      - ` cacheState `: type ` string `

        - enum: ` ["hit","miss"] `

      - ` cachedAt `: type ` string `; format ` date-time `

      - ` creditsUsed `: type ` integer `

      - ` proxyUsed `: type ` string `

        - enum: ` ["basic","stealth"] `

      - ` concurrencyLimited `: type ` boolean `

      - ` concurrencyQueueDurationMs `: type ` number `

      - ` b3os `: type ` object ` — B3OS extras (Firecrawl clients ignore them).

        - ` tier `: type ` string `

          - enum: ` ["cache","fetch","browser"] `

        - ` request_id `: type ` string `

        - ` timing `: type ` object ` — Server-side phase durations in milliseconds with microsecond resolution: the same phases as the `Server-Timing` header, keyed `<phase>_ms`. `total_ms` is always present. Phase names are product-specific and documented per operation. Example values in this reference are illustrative, not measurements. 

          - example: ` {"claim_ms":1.1,"navigate_ms":31,"extract_ms":4.2,"total_ms":36.6} `

          - Required fields: ` total_ms `

          - ` total_ms `: type ` number `

            - minimum: ` 0 `

    - ` warning `: type ` string `; nullable

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Example:

```json
{
  "success": true,
  "data": {
    "markdown": "# Pricing\n\nStart free, then pay per page.",
    "metadata": {
      "title": "Pricing | Example",
      "description": "Plans and prices for Example.",
      "language": "en",
      "sourceURL": "https://example.com/pricing",
      "url": "https://example.com/pricing",
      "statusCode": 200,
      "contentType": "text/html; charset=utf-8",
      "scrapeId": "req_01m5t4yg394wegr3j4y01qb363",
      "cacheState": "miss",
      "creditsUsed": 1,
      "proxyUsed": "basic",
      "b3os": {
        "tier": "fetch",
        "request_id": "req_01m5t4yg394wegr3j4y01qb363",
        "timing": {
          "fetch_ms": 41.2,
          "extract_ms": 3.9,
          "total_ms": 45.8
        }
      }
    }
  }
}
```

### ` 400 ` — The body failed validation, uses an unsupported option, or a URL is invalid (`invalid_request`, `unsupported_option`, `invalid_url`).

Content type: ` application/json `

- ` value `: type ` object ` — Firecrawl's error body. `code` and the status come from the B3OS code's `firecrawl` field in errors.yaml (the Firecrawl code where one exists, such as `SCRAPE_TIMEOUT`, otherwise the B3OS code); `x-request-id` carries the request ID.

  - Required fields: ` success `, ` error `

  - ` success `: type ` boolean `

    - enum: ` [false] `

  - ` error `: type ` string ` — `<prefix>: <detail>`, where the prefix is the B3OS code's `firecrawl.error` in errors.yaml and the detail is the B3OS problem's `detail`; the prefix alone when the problem has no detail. 

  - ` code `: type ` string `

  - ` details `: type ` unknown ` — Validation issues. A `400` `invalid_request` carries the B3OS problem's `errors[]` array here; unknown body fields are reported as Firecrawl reports them, as Zod-style `unrecognized_keys` issues (`{code, keys, path, message}`). 

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Example:

```json
{
  "success": false,
  "error": "Bad Request",
  "code": "BAD_REQUEST",
  "details": [
    {
      "code": "unrecognized_keys",
      "keys": [
        "fromats"
      ],
      "path": [],
      "message": "Unrecognized key in body -- please review the v2 API documentation for request body changes"
    }
  ]
}
```

### ` 401 ` — Missing or invalid B3OS key (`unauthorized`). Firecrawl `fc-` keys are not accepted.

Content type: ` application/json `

- ` value `: type ` object ` — Firecrawl's error body. `code` and the status come from the B3OS code's `firecrawl` field in errors.yaml (the Firecrawl code where one exists, such as `SCRAPE_TIMEOUT`, otherwise the B3OS code); `x-request-id` carries the request ID.

  - Required fields: ` success `, ` error `

  - ` success `: type ` boolean `

    - enum: ` [false] `

  - ` error `: type ` string ` — `<prefix>: <detail>`, where the prefix is the B3OS code's `firecrawl.error` in errors.yaml and the detail is the B3OS problem's `detail`; the prefix alone when the problem has no detail. 

  - ` code `: type ` string `

  - ` details `: type ` unknown ` — Validation issues. A `400` `invalid_request` carries the B3OS problem's `errors[]` array here; unknown body fields are reported as Firecrawl reports them, as Zod-style `unrecognized_keys` issues (`{code, keys, path, message}`). 

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Example:

```json
{
  "success": false,
  "error": "Unauthorized: Invalid token",
  "code": "unauthorized"
}
```

### ` 402 ` — No credits left or the key's spend cap is reached (`credits_exhausted`, `spend_cap_exceeded`).

Content type: ` application/json `

- ` value `: type ` object ` — Firecrawl's error body. `code` and the status come from the B3OS code's `firecrawl` field in errors.yaml (the Firecrawl code where one exists, such as `SCRAPE_TIMEOUT`, otherwise the B3OS code); `x-request-id` carries the request ID.

  - Required fields: ` success `, ` error `

  - ` success `: type ` boolean `

    - enum: ` [false] `

  - ` error `: type ` string ` — `<prefix>: <detail>`, where the prefix is the B3OS code's `firecrawl.error` in errors.yaml and the detail is the B3OS problem's `detail`; the prefix alone when the problem has no detail. 

  - ` code `: type ` string `

  - ` details `: type ` unknown ` — Validation issues. A `400` `invalid_request` carries the B3OS problem's `errors[]` array here; unknown body fields are reported as Firecrawl reports them, as Zod-style `unrecognized_keys` issues (`{code, keys, path, message}`). 

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Example:

```json
{
  "success": false,
  "error": "Insufficient credits: Organization org_01m5t5hthd29mm5wpza5ndd6mm has no credits left",
  "code": "credits_exhausted"
}
```

### ` 403 ` — The URL is refused by the egress guard or robots.txt, or the key lacks a scope (`egress_denied`, `robots_disallowed`, `forbidden`).

Content type: ` application/json `

- ` value `: type ` object ` — Firecrawl's error body. `code` and the status come from the B3OS code's `firecrawl` field in errors.yaml (the Firecrawl code where one exists, such as `SCRAPE_TIMEOUT`, otherwise the B3OS code); `x-request-id` carries the request ID.

  - Required fields: ` success `, ` error `

  - ` success `: type ` boolean `

    - enum: ` [false] `

  - ` error `: type ` string ` — `<prefix>: <detail>`, where the prefix is the B3OS code's `firecrawl.error` in errors.yaml and the detail is the B3OS problem's `detail`; the prefix alone when the problem has no detail. 

  - ` code `: type ` string `

  - ` details `: type ` unknown ` — Validation issues. A `400` `invalid_request` carries the B3OS problem's `errors[]` array here; unknown body fields are reported as Firecrawl reports them, as Zod-style `unrecognized_keys` issues (`{code, keys, path, message}`). 

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Example:

```json
{
  "success": false,
  "error": "Destination not allowed: http://10.0.0.5/ resolves to a private address",
  "code": "egress_denied"
}
```

### ` 404 ` — No such job in this project (`crawl_not_found`, `batch_not_found`, `job_not_found`).

Content type: ` application/json `

- ` value `: type ` object ` — Firecrawl's error body. `code` and the status come from the B3OS code's `firecrawl` field in errors.yaml (the Firecrawl code where one exists, such as `SCRAPE_TIMEOUT`, otherwise the B3OS code); `x-request-id` carries the request ID.

  - Required fields: ` success `, ` error `

  - ` success `: type ` boolean `

    - enum: ` [false] `

  - ` error `: type ` string ` — `<prefix>: <detail>`, where the prefix is the B3OS code's `firecrawl.error` in errors.yaml and the detail is the B3OS problem's `detail`; the prefix alone when the problem has no detail. 

  - ` code `: type ` string `

  - ` details `: type ` unknown ` — Validation issues. A `400` `invalid_request` carries the B3OS problem's `errors[]` array here; unknown body fields are reported as Firecrawl reports them, as Zod-style `unrecognized_keys` issues (`{code, keys, path, message}`). 

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Example:

```json
{
  "success": false,
  "error": "Crawl job not found: No crawl crawl_01m5t4gh4qhgs70zwajezbe5p0 in this project",
  "code": "crawl_not_found"
}
```

### ` 408 ` — The page did not load within the timeout (`scrape_timeout`).

Content type: ` application/json `

- ` value `: type ` object ` — Firecrawl's error body. `code` and the status come from the B3OS code's `firecrawl` field in errors.yaml (the Firecrawl code where one exists, such as `SCRAPE_TIMEOUT`, otherwise the B3OS code); `x-request-id` carries the request ID.

  - Required fields: ` success `, ` error `

  - ` success `: type ` boolean `

    - enum: ` [false] `

  - ` error `: type ` string ` — `<prefix>: <detail>`, where the prefix is the B3OS code's `firecrawl.error` in errors.yaml and the detail is the B3OS problem's `detail`; the prefix alone when the problem has no detail. 

  - ` code `: type ` string `

  - ` details `: type ` unknown ` — Validation issues. A `400` `invalid_request` carries the B3OS problem's `errors[]` array here; unknown body fields are reported as Firecrawl reports them, as Zod-style `unrecognized_keys` issues (`{code, keys, path, message}`). 

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Example:

```json
{
  "success": false,
  "error": "Request Timeout",
  "code": "SCRAPE_TIMEOUT"
}
```

### ` 429 ` — A rate or concurrency limit applies (`rate_limited`, `concurrency_limited`).

Content type: ` application/json `

- ` value `: type ` object ` — Firecrawl's error body. `code` and the status come from the B3OS code's `firecrawl` field in errors.yaml (the Firecrawl code where one exists, such as `SCRAPE_TIMEOUT`, otherwise the B3OS code); `x-request-id` carries the request ID.

  - Required fields: ` success `, ` error `

  - ` success `: type ` boolean `

    - enum: ` [false] `

  - ` error `: type ` string ` — `<prefix>: <detail>`, where the prefix is the B3OS code's `firecrawl.error` in errors.yaml and the detail is the B3OS problem's `detail`; the prefix alone when the problem has no detail. 

  - ` code `: type ` string `

  - ` details `: type ` unknown ` — Validation issues. A `400` `invalid_request` carries the B3OS problem's `errors[]` array here; unknown body fields are reported as Firecrawl reports them, as Zod-style `unrecognized_keys` issues (`{code, keys, path, message}`). 

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Response header ` Retry-After ` — Seconds to wait before retrying or polling again.

- ` value `: type ` integer `

  - minimum: ` 0 `

Example:

```json
{
  "success": false,
  "error": "Rate limit exceeded",
  "code": "rate_limited"
}
```

### ` 500 ` — Something failed inside B3OS (`internal`).

Content type: ` application/json `

- ` value `: type ` object ` — Firecrawl's error body. `code` and the status come from the B3OS code's `firecrawl` field in errors.yaml (the Firecrawl code where one exists, such as `SCRAPE_TIMEOUT`, otherwise the B3OS code); `x-request-id` carries the request ID.

  - Required fields: ` success `, ` error `

  - ` success `: type ` boolean `

    - enum: ` [false] `

  - ` error `: type ` string ` — `<prefix>: <detail>`, where the prefix is the B3OS code's `firecrawl.error` in errors.yaml and the detail is the B3OS problem's `detail`; the prefix alone when the problem has no detail. 

  - ` code `: type ` string `

  - ` details `: type ` unknown ` — Validation issues. A `400` `invalid_request` carries the B3OS problem's `errors[]` array here; unknown body fields are reported as Firecrawl reports them, as Zod-style `unrecognized_keys` issues (`{code, keys, path, message}`). 

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Example:

```json
{
  "success": false,
  "error": "Internal Server Error",
  "code": "internal"
}
```

### ` 502 ` — The site could not be reached or loaded (`upstream_unreachable`, `navigation_failed`).

Content type: ` application/json `

- ` value `: type ` object ` — Firecrawl's error body. `code` and the status come from the B3OS code's `firecrawl` field in errors.yaml (the Firecrawl code where one exists, such as `SCRAPE_TIMEOUT`, otherwise the B3OS code); `x-request-id` carries the request ID.

  - Required fields: ` success `, ` error `

  - ` success `: type ` boolean `

    - enum: ` [false] `

  - ` error `: type ` string ` — `<prefix>: <detail>`, where the prefix is the B3OS code's `firecrawl.error` in errors.yaml and the detail is the B3OS problem's `detail`; the prefix alone when the problem has no detail. 

  - ` code `: type ` string `

  - ` details `: type ` unknown ` — Validation issues. A `400` `invalid_request` carries the B3OS problem's `errors[]` array here; unknown body fields are reported as Firecrawl reports them, as Zod-style `unrecognized_keys` issues (`{code, keys, path, message}`). 

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Example:

```json
{
  "success": false,
  "error": "Bad Gateway: DNS lookup for shop.example failed",
  "code": "upstream_unreachable"
}
```

### ` 503 ` — The node or vision is unavailable (`node_unavailable`, `product_unavailable`).

Content type: ` application/json `

- ` value `: type ` object ` — Firecrawl's error body. `code` and the status come from the B3OS code's `firecrawl` field in errors.yaml (the Firecrawl code where one exists, such as `SCRAPE_TIMEOUT`, otherwise the B3OS code); `x-request-id` carries the request ID.

  - Required fields: ` success `, ` error `

  - ` success `: type ` boolean `

    - enum: ` [false] `

  - ` error `: type ` string ` — `<prefix>: <detail>`, where the prefix is the B3OS code's `firecrawl.error` in errors.yaml and the detail is the B3OS problem's `detail`; the prefix alone when the problem has no detail. 

  - ` code `: type ` string `

  - ` details `: type ` unknown ` — Validation issues. A `400` `invalid_request` carries the B3OS problem's `errors[]` array here; unknown body fields are reported as Firecrawl reports them, as Zod-style `unrecognized_keys` issues (`{code, keys, path, message}`). 

Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`.

- ` value `: type ` string `

  - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a
response whose body size is known, `total` runs from reading the request head to writing the response head.
Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their
final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The
time from the first request byte to the last response byte is recorded in the node's metrics and request
log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`.


- ` value `: type ` string `

Response header ` Retry-After ` — Seconds to wait before retrying or polling again.

- ` value `: type ` integer `

  - minimum: ` 0 `

Example:

```json
{
  "success": false,
  "error": "Service Unavailable",
  "code": "node_unavailable"
}
```

## Request examples

### cURL

```curl
curl -X POST 'https://beta-api.b3os.org/compat/firecrawl/v2/scrape' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/pricing",
  "formats": [
    "markdown"
  ]
}'
```

### JavaScript

```javascript
const response = await fetch('https://beta-api.b3os.org/compat/firecrawl/v2/scrape', {
  method: 'POST',
  headers: {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "url": "https://example.com/pricing",
    "formats": [
      "markdown"
    ]
  })
});

const data = await response.json();
console.log(data);
```

### Python

```python
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.post('https://beta-api.b3os.org/compat/firecrawl/v2/scrape', headers=headers, json={
  "url": "https://example.com/pricing",
  "formats": [
    "markdown"
  ]
})
print(response.json())
```