Firecrawl v1-to-v2 Upgrade

Overview

Treat the version change as a behavior migration, not a search-and-replace. Inventory method, option, response, cache, extraction, pagination, and billing differences before switching traffic.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The source authorization, data classification, and environment policy.
• Current Firecrawl documentation, credentials only when needed, and an owner for approvals.

Current Contract

The current top-level SDK defaults to v2. Key mappings include scrapeUrl to scrape, crawlUrl to crawl, asyncCrawlUrl to startCrawl, checkCrawlStatus to getCrawlStatus, mapUrl to map, batchScrapeUrls to batchScrape, asyncBatchScrapeUrls to startBatchScrape, and checkBatchScrapeStatus to getBatchScrapeStatus. The legacy extract format became a json format object; v2 cache defaults and option shapes also changed.

Authentication

For authenticated Cloud operations, inject FIRECRAWL_API_KEY from an approved secret manager. REST requests use Authorization: Bearer with the key. Never print, commit, transmit, or place a key in a URL. Keyless access is suitable only where the current documentation explicitly allows it and the workload accepts its limits; production workflows should make identity and team ownership explicit.

Instructions

1. Pin the current dependency, routes, methods, options, response assumptions, fixtures, usage, and rollback release. Identify intentional feature-frozen v1 callers.
2. Read current migration, SDK, endpoint, billing, and error references; build a per-call mapping including renamed, removed, defaulted, and behavior-changing fields.
3. Add golden synthetic tests for requests, direct SDK versus REST responses, metadata fields, origin status, JSON extraction, crawl/batch jobs, pagination, errors, and cost-sensitive options.
4. Introduce a typed v2 adapter behind a feature flag. Keep v1 compatibility isolated and do not silently fall back from v2 on failure.
5. Run offline contract tests, then shadow approved canaries with content hashes, schema coverage, latency, cache state, and credits rather than raw body diffs.
6. Shift traffic gradually, monitor errors, partial results, quality, freshness, queue, and spend, and exercise rollback before removing the flag.
7. After the observation window, remove legacy packages/routes/secrets, update docs/fixtures, and verify no v0/v1 strings remain except migration evidence.

Tool Discipline

Use Read, Glob, and Grep to inspect code, configuration, tests, and evidence. Use Write/Edit only for approved implementation or documentation changes. Do not call Firecrawl, rotate keys, change account settings, scrape a target, or deploy merely because this skill was invoked.

Approval Boundaries

Require approval before changing the SDK major, accepting changed cache/retention behavior, increasing credits, switching production traffic, or removing the legacy rollback path.

Output

Return the exact before/after package and API surface, mapping table, changed defaults/options, parity tests, canary metrics, rollout state, rollback evidence, and cleanup results.

Error Handling

• No documented mapping exists: keep the old path and resolve against source/types.
• v2 output or cost is materially different: stop rollout and decide whether to adapt requirements.
• Fallback masks v2 failures: remove automatic fallback and make the version decision observable.

Examples

• "Replace scrapeUrl" also verifies options and returned document shape.
• "Upgrade the package and hope" is replaced with mapping, shadow parity, staged traffic, and rollback.

Resources

Read official Firecrawl evidence before relying on an endpoint, SDK method, plan limit, price, retention option, or self-hosted release.