fastcrw-com Scrape API

openapi: 3.2.0
info:
  title: CRW REST Scrape API
  version: 0.39.1
  description: Firecrawl-compatible web scraping, crawling, mapping, search, and extraction API. Hosted at https://api.fastcrw.com; self-host with `docker run -p 3000:3000 ghcr.io/fastcrw/crw:latest`.
  license:
    name: AGPL-3.0
    url: https://opensource.org/licenses/AGPL-3.0
  contact:
    url: https://github.com/fastcrw/crw
servers:
- url: https://api.fastcrw.com
  description: Hosted (requires Bearer token)
- url: http://localhost:3000
  description: Self-hosted (no auth by default)
security:
- bearerAuth: []
- {}
tags:
- name: Scrape
  description: Single-URL content extraction
paths:
  /v1/scrape:
    post:
      tags:
      - Scrape
      summary: Scrape one URL
      operationId: scrape
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrapeRequest'
      responses:
        '200':
          description: Scrape result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrapeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    BadRequest:
      description: Invalid request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid bearer token (hosted only)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Basis:
      type: object
      required:
      - basisVersion
      - field
      - value
      - status
      - citations
      description: Per-field extraction evidence. Emitted only for top-level scalar schema properties, and only when the request set basis:true. citations is empty exactly when status is 'unsupported' or 'notFound'; value is null exactly when status is 'notFound'.
      properties:
        basisVersion:
          type: integer
        field:
          type: string
        value:
          description: The schema-validated value; null when status is 'notFound'. Never rewritten to the model's claim.
        status:
          $ref: '#/components/schemas/FieldStatus'
        confidence:
          type: string
          enum:
          - low
          - medium
          - high
        citations:
          type: array
          items:
            $ref: '#/components/schemas/EvidenceCitation'
    ParserSpec:
      type: object
      description: Document parser directive. Accepts string form ('pdf') or object form.
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - pdf
          description: Parser type (only 'pdf' is supported)
        mode:
          type: string
          enum:
          - auto
          - fast
          - ocr
          description: Parsing strategy (auto = text-first; ocr degrades to text extraction with a warning)
        maxPages:
          type: integer
          minimum: 1
          description: Optional cap on the number of pages to parse
    ExtractOptions:
      type: object
      description: Firecrawl-compatible extraction options sub-object
      properties:
        schema:
          type: object
          additionalProperties: true
          description: JSON Schema for structured extraction. Used as jsonSchema when jsonSchema is not set directly.
    ScrapeResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
        warning:
          type: string
          description: Top-level advisory (e.g. fallback render notice)
        data:
          type: object
          properties:
            markdown:
              type: string
            html:
              type: string
            rawHtml:
              type: string
            links:
              type: array
              items:
                type: string
                format: uri
            json:
              type: object
              additionalProperties: true
            metadata:
              $ref: '#/components/schemas/PageMetadata'
            warning:
              type: string
            warnings:
              type: array
              items:
                type: string
            renderDecision:
              type: object
              description: 'How the renderer was chosen. A tagged object: `kind` is one of `userPinned`, `autoDefault`, `autoPromoted`, `breakerSkipped`, `failover`, and the remaining fields depend on it.'
              properties:
                kind:
                  type: string
            creditCost:
              type: number
            basis:
              type: array
              items:
                $ref: '#/components/schemas/Basis'
              description: Per-field evidence for the 'json' format; present only when the request set basis:true.
            basisWarnings:
              type: array
              items:
                $ref: '#/components/schemas/BasisWarning'
            llmInputHash:
              type: string
              description: '''sha256:''-prefixed hash of the canonical text sent to the extraction LLM. The independent record a consumer checks a citation''s sourceHash against, so the check is not circular.'
            sourceHash:
              type: string
              description: Fingerprint of the canonical markdown, for dedup and caching.
            plainText:
              type: string
              description: Plain-text view; present when `formats` includes `plainText`.
            images:
              $ref: '#/components/schemas/ScrapedImages'
            summary:
              type: string
              description: LLM summary; present when `formats` includes `summary`.
            llmUsage:
              type: object
              description: Token usage for the LLM call, when one ran.
            chunks:
              type: array
              items:
                type: object
              description: Chunked content, when a `chunkStrategy` was requested.
            contentType:
              type: string
              description: MIME type of the fetched resource.
            changeTracking:
              type: object
              description: Diff result; present when `formats` includes `changeTracking`.
            screenshot:
              type: string
              description: PNG capture as a `data:image/png;base64,...` URL; present when `formats` includes `screenshot`.
            block:
              type: object
              description: Anti-bot verdict. Present only when the page was a block or challenge shell, in which case `success` is false.
            debugExtraction:
              type: object
              description: 'Extraction trace; present only when `debug: true`.'
    Error:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
          description: Human-readable error message
        errorCode:
          type: string
          description: Machine-readable error code (see docs/error-codes.md)
    ScrapeRequest:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
        formats:
          type: array
          items:
            $ref: '#/components/schemas/OutputFormat'
          default:
          - markdown
        onlyMainContent:
          type: boolean
          default: true
          description: Strip navigation, ads, and boilerplate; keep main article content only
        renderJs:
          type:
          - boolean
          - 'null'
          description: null = auto-detect, true = force JS rendering, false = skip JS rendering
        waitFor:
          type: integer
          minimum: 0
          description: Milliseconds to wait after JS rendering before extracting content
        includeTags:
          type: array
          items:
            type: string
          default: []
          description: CSS selectors / HTML tags to include in extraction
        excludeTags:
          type: array
          items:
            type: string
          default: []
          description: CSS selectors / HTML tags to remove before extraction
        jsonSchema:
          type: object
          additionalProperties: true
          description: JSON Schema describing the structured output shape for the 'json' format
        basis:
          type: boolean
          default: false
          description: 'Return per-field evidence alongside the ''json'' format: each top-level scalar schema property comes back as a Basis with an honest status. Requires a JSON schema; off by default, and when off the request sent to the model is unchanged.'
        headers:
          type: object
          additionalProperties:
            type: string
          description: Custom HTTP request headers forwarded to the target URL
        cssSelector:
          type: string
          description: CSS selector to narrow content extraction to a specific element
        xpath:
          type: string
          description: XPath expression to narrow content extraction to a specific element
        chunkStrategy:
          $ref: '#/components/schemas/ChunkStrategy'
          description: Strategy for chunking the extracted markdown
        query:
          type: string
          description: Query string for BM25/cosine chunk filtering (used with chunkStrategy)
        filterMode:
          type: string
          enum:
          - bm25
          - cosine
          description: Filtering algorithm to rank chunks against query
        topK:
          type: integer
          minimum: 1
          description: 'Number of top chunks to return after filtering (default: 5)'
        proxy:
          type: string
          description: Per-request proxy URL (http/https/socks5). Overrides global config.
        proxyList:
          type: array
          items:
            type: string
          default: []
          description: Per-request proxy pool to rotate among (BYOP). Takes precedence over proxy and server config.
        proxyRotation:
          type: string
          enum:
          - round_robin
          - random
          - sticky_per_host
          description: 'Rotation strategy for proxyList (default: sticky_per_host)'
        country:
          type: string
          description: 2-letter ISO 3166-1 alpha-2 country code for residential proxy egress (e.g. 'us', 'gb')
        stealth:
          type: boolean
          description: Override stealth mode for this request (null = use global config)
        actions:
          type: object
          additionalProperties: true
          description: Unsupported Firecrawl parameter — returns a clear error if supplied
        extract:
          $ref: '#/components/schemas/ExtractOptions'
          description: 'Firecrawl-compatible extract object (e.g. { schema: {...} })'
        llmApiKey:
          type: string
          description: 'BYOK: LLM provider API key for structured extraction (overrides server key)'
        llmProvider:
          type: string
          enum:
          - anthropic
          - openai
          - deepseek
          - azure
          - openai-compatible
          - openai-responses
          description: Per-request LLM provider override
        llmModel:
          type: string
          description: Per-request LLM model identifier override
        baseUrl:
          type: string
          description: Per-request LLM base URL override for Chat Completions-compatible or Responses-compatible providers (e.g. https://api.deepseek.com/v1)
        summaryPrompt:
          type: string
          maxLength: 500
          description: User-supplied instructions appended to the summary system prompt (capped at 500 chars)
        maxContentChars:
          type: integer
          minimum: 1
          description: Maximum bytes of scraped content sent to LLM for 'summary' format (capped at 200 KB)
        renderer:
          type: string
          enum:
          - auto
          - lightpanda
          - chrome
          - chrome_proxy
          - playwright
          - camoufox
          - impersonated-http
          description: Pin this request to a specific renderer. A non-auto browser tier implies renderJs:true unless renderJs:false is set. impersonated-http is a JS-less tier that presents a real Chrome TLS fingerprint; it never implies renderJs, and combining it with renderJs:true is rejected.
        deadlineMs:
          type: integer
          minimum: 1
          maximum: 60000
          description: 'End-to-end deadline budget in milliseconds (default: 8000, max: 60000)'
        debug:
          type: boolean
          description: When true, response includes debugExtraction trace with every candidate the extractor considered
        changeTracking:
          $ref: '#/components/schemas/ChangeTrackingOptions'
          description: Activated when formats includes 'changeTracking'. The format entry is the plain string; options ride on this sibling field.
        goal:
          type: string
          maxLength: 2048
          description: Plain-language monitor goal for the meaningful-change judge
        judgeEnabled:
          type: boolean
          description: Run the LLM meaningful-change judge on a changed page (requires goal)
        parsers:
          type: array
          items:
            $ref: '#/components/schemas/ParserSpec'
          description: Document parser directives. Omit = auto-parse PDFs. Empty array = disable parsing.
        screenshotFullPage:
          type: boolean
          default: false
          description: 'Capture the whole page rather than the viewport, for `formats: ["screenshot"]`.'
        maxAge:
          type: integer
          format: int64
          minimum: 0
          default: 3600000
          description: How old a cached copy of this fetch may be, in milliseconds. 0 always fetches. Clamped to a 24 hour ceiling. Extraction options (formats, schema, selectors) are not part of the cache key, so a second pass over the same page reuses the fetch.
        storeInCache:
          type: boolean
          default: true
          description: Set false to read the cache without writing to it.
    ChunkStrategy:
      type: object
      description: Strategy for chunking extracted markdown before query-based filtering
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - sentence
          - regex
          - topic
          description: 'Chunking algorithm: sentence = split on .!?, regex = split on pattern, topic = split on markdown headings'
        maxChars:
          type: integer
          minimum: 1
          description: Maximum characters per chunk (merges short chunks up to this limit)
        overlapChars:
          type: integer
          minimum: 0
          description: Character overlap between adjacent chunks
        dedupe:
          type: boolean
          description: Remove duplicate chunks
        pattern:
          type: string
          description: Regex pattern to split on (required when type = 'regex')
    ChangeTrackingSnapshot:
      type: object
      properties:
        markdown:
          type: string
          description: Present for gitDiff/mixed mode
        json:
          type: object
          additionalProperties: true
          description: Present for json/mixed mode
        contentHash:
          type: string
          description: Mode-aware hash; persist + supply on the next check
        capturedAt:
          type: string
          description: Caller-stamped capture time, echoed untouched
    OutputFormat:
      type: string
      enum:
      - markdown
      - html
      - rawHtml
      - plainText
      - links
      - images
      - json
      - summary
      - changeTracking
      - screenshot
      description: 'Aliases accepted in addition to these: `extract` and `llm-extract` for `json`, `change-tracking` for `changeTracking`, `screenshot@fullPage` for `screenshot`.'
    ScrapedImages:
      type: array
      description: Present when `formats` includes `images`.
      items:
        type: object
        properties:
          url:
            type: string
            format: uri
          alt:
            type: string
        required:
        - url
    FieldStatus:
      type: string
      enum:
      - supported
      - unverified
      - unsupported
      - notFound
      description: 'How well an extracted field is attributed to its source. Honest: a field whose attribution could not be verified is ''unverified''/''unsupported'' rather than given a fabricated citation.'
    ChangeTrackingOptions:
      type: object
      properties:
        modes:
          type: array
          items:
            type: string
            enum:
            - gitDiff
            - json
          description: Diff surfaces. gitDiff = markdown unified diff + AST; json = per-field diff; both = mixed.
        schema:
          type: object
          additionalProperties: true
          description: JSON schema of tracked fields (json/mixed mode)
        prompt:
          type: string
        previous:
          $ref: '#/components/schemas/ChangeTrackingSnapshot'
        tag:
          type: string
          description: Opaque caller tag echoed on the result
        contentType:
          type: string
          description: MIME type; non-text content is hashed, not diffed
    EvidenceCitation:
      type: object
      required:
      - url
      - sourceHash
      - sourceTextKind
      description: A citation backing an extracted value. Every field is server-produced; never a model-supplied url, hash or excerpt.
      properties:
        url:
          type: string
          description: The document the engine fetched.
        title:
          type: string
        excerpt:
          type: string
          description: Verbatim span from the canonical source text. Absent when the span could not be established (status 'unverified').
        sourceHash:
          type: string
          description: '''sha256:<hex>'' of the exact text sent to the model.'
        sourceTextKind:
          type: string
          description: Which text sourceHash covers. 'llmInput' for extraction basis (the truncated markdown sent to the model).
    PageMetadata:
      type: object
      additionalProperties: true
      properties:
        title:
          type: string
        description:
          type: string
        sourceURL:
          type: string
          format: uri
        statusCode:
          type: integer
    BasisWarning:
      type: object
      required:
      - field
      - code
      description: A coded reason a field's attribution was downgraded. Closed, crw-owned code set; never upstream text.
      properties:
        field:
          type: string
        code:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Hosted only. Get a key at https://fastcrw.com/register.