fastcrw-com Change Tracking API

openapi: 3.2.0
info:
  title: CRW REST Change Tracking 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: change-tracking
  description: Stateless diff of a scrape against a caller-supplied previous snapshot (monitor primitive)
paths:
  /v1/change-tracking/diff:
    post:
      tags:
      - change-tracking
      summary: Diff current scrape content against a previous snapshot
      description: 'Stateless: opencore stores nothing — the caller supplies the `previous` snapshot. Accepts a single body or a `batch` array (presence of `batch` selects batch mode). The crawl-path workhorse for monitors.'
      operationId: changeTrackingDiff
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeTrackingDiffRequest'
            examples:
              single_gitdiff:
                summary: Single page, markdown git-diff
                value:
                  modes:
                  - gitDiff
                  previous:
                    markdown: Starter $19
                    contentHash: abc
                  current:
                    markdown: Starter $24
              batch_json:
                summary: Batch, json per-field mode
                value:
                  modes:
                  - json
                  batch:
                  - url: https://example.com/pricing
                    previous:
                      json:
                        price: $19
                      contentHash: abc
                    current:
                      json:
                        price: $24
      responses:
        '200':
          description: Diff result (object for single, array for batch) wrapped in the standard envelope
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                  data:
                    oneOf:
                    - $ref: '#/components/schemas/ChangeTrackingResult'
                    - type: array
                      items:
                        $ref: '#/components/schemas/ChangeTrackingResult'
        '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:
    ChangeTrackingResult:
      type: object
      required:
      - status
      - contentHash
      properties:
        status:
          type: string
          enum:
          - same
          - changed
          description: Per-page status. Set-level new/removed are computed by the caller's reconciler.
        firstObservation:
          type: boolean
          description: True when no previous was supplied — caller maps to 'new'
        contentHash:
          type: string
        snapshot:
          $ref: '#/components/schemas/ChangeTrackingSnapshot'
        diff:
          $ref: '#/components/schemas/ChangeDiff'
        judgment:
          $ref: '#/components/schemas/ChangeJudgment'
        tag:
          type: string
        truncated:
          type: boolean
    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)
    ChangeTrackingDiffRequest:
      type: object
      description: Single body (provide 'current') OR batch (provide 'batch'). Top-level modes/schema/prompt/contentType act as shared defaults in batch mode.
      properties:
        batch:
          type: array
          items:
            $ref: '#/components/schemas/ChangeTrackingDiffItem'
        current:
          type: object
          properties:
            markdown:
              type: string
            json:
              type: object
              additionalProperties: true
        previous:
          $ref: '#/components/schemas/ChangeTrackingSnapshot'
        modes:
          type: array
          items:
            type: string
            enum:
            - gitDiff
            - json
        schema:
          type: object
          additionalProperties: true
        prompt:
          type: string
        contentType:
          type: string
    ChangeTrackingDiffItem:
      type: object
      required:
      - current
      properties:
        url:
          type: string
          format: uri
        current:
          type: object
          properties:
            markdown:
              type: string
            json:
              type: object
              additionalProperties: true
        previous:
          $ref: '#/components/schemas/ChangeTrackingSnapshot'
        modes:
          type: array
          items:
            type: string
            enum:
            - gitDiff
            - json
        schema:
          type: object
          additionalProperties: true
        prompt:
          type: string
        contentType:
          type: string
        tag:
          type: string
    ChangeJudgment:
      type: object
      required:
      - meaningful
      - confidence
      - reason
      properties:
        meaningful:
          type: boolean
        confidence:
          type: string
          enum:
          - low
          - medium
          - high
        reason:
          type: string
        meaningfulChanges:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - added
                - removed
                - changed
              before:
                type: string
              after:
                type: string
              reason:
                type: string
    ChangeDiff:
      type: object
      properties:
        text:
          type: string
          description: Unified markdown diff (gitDiff/mixed)
        json:
          type: object
          additionalProperties: true
          description: Parse-diff AST (gitDiff-only) OR per-field path map {previous,current} (json/mixed)
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Hosted only. Get a key at https://fastcrw.com/register.