Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat(api): deprecation notices on every v1 route (#5604)
Gergő Móricz52ecbfc0766b
diff --git a/apps/api/src/__tests__/routes/v1-deprecations.routes.test.ts b/apps/api/src/__tests__/routes/v1-deprecations.routes.test.tsnew file mode 100644index 000000000..a677f60f9--- /dev/null+++ b/apps/api/src/__tests__/routes/v1-deprecations.routes.test.ts@@ -0,0 +1,134 @@+import express from "express";+import request from "supertest";++vi.mock("../../controllers/auth", () => ({ getApiKeyTeamFlags: vi.fn() }));++import { deprecationMiddleware } from "../../lib/deprecations";++const V1_DEPRECATED_AT = "@1793923200";+const GUIDE = "https://docs.firecrawl.dev/migrate-to-v2";+const V1_SUNSET = "Thu, 10 Dec 2026 15:00:00 GMT";+const BEFORE_SUNSET = new Date("2026-11-07T00:00:00Z");+const AFTER_SUNSET = new Date("2026-12-11T00:00:00Z");++const V1 = {+ v1_scrape: "/v2/scrape",+ v1_scrape_status: "/v2/scrape/:jobId",+ v1_crawl: "/v2/crawl",+ v1_crawl_status: "/v2/crawl/:jobId",+ v1_crawl_cancel: "/v2/crawl/:jobId",+ v1_crawl_errors: "/v2/crawl/:jobId/errors",+ v1_crawl_active: "/v2/crawl/active",+ v1_crawl_ongoing: "/v2/crawl/active",+ v1_batch_scrape: "/v2/batch/scrape",+ v1_batch_scrape_status: "/v2/batch/scrape/:jobId",+ v1_batch_scrape_cancel: "/v2/batch/scrape/:jobId",+ v1_batch_scrape_errors: "/v2/batch/scrape/:jobId/errors",+ v1_search: "/v2/search",+ v1_map: "/v2/map",+ v1_concurrency_check: "/v2/concurrency-check",+ v1_team_credit_usage: "/v2/team/credit-usage",+ v1_team_credit_usage_historical: "/v2/team/credit-usage/historical",+ v1_team_token_usage: "/v2/team/token-usage",+ v1_team_token_usage_historical: "/v2/team/token-usage/historical",+ v1_team_queue_status: "/v2/team/queue-status",+} as const;++type Key = keyof typeof V1;++function appFor(key: Key, flags: unknown = null) {+ const app = express();+ app.get(+ "/probe",+ (req: any, _res, next) => {+ req.acuc = { flags };+ next();+ },+ deprecationMiddleware(key),+ (_req, res) => {+ res.status(200).json({ success: true, data: { markdown: "# hi" } });+ },+ );+ return app;+}++function extendedOn(surface: string) {+ return { deprecationExtensions: { [surface]: "2027-01-31T00:00:00Z" } };+}++beforeEach(() => {+ vi.useFakeTimers({ toFake: ["Date"] });+});++afterEach(() => {+ vi.useRealTimers();+});++describe("v1 route deprecations", () => {+ beforeEach(() => {+ vi.setSystemTime(BEFORE_SUNSET);+ });++ for (const key of Object.keys(V1) as Key[]) {+ it(`${key} points at ${V1[key]} and the migration guide, with the v1 sunset`, async () => {+ const res = await request(appFor(key)).get("/probe");++ expect(res.headers["deprecation"]).toBe(V1_DEPRECATED_AT);+ expect(res.headers["sunset"]).toBe(V1_SUNSET);+ expect(res.headers["link"]).toBe(+ `<${GUIDE}>; rel="deprecation", <${V1[key]}>; rel="successor-version"`,+ );+ expect(res.headers["warning"]).toMatch(+ /^299 - "(?:DELETE )?\/v1\/.* is deprecated\./,+ );+ expect(res.body.success).toBe(true);+ expect(res.body.data).toEqual({ markdown: "# hi" });+ expect(res.body.replacement).toBe(V1[key]);+ expect(res.body.warnings).toHaveLength(1);+ expect(res.body.warnings[0]).toContain(GUIDE);+ });+ }+});++describe("v1 sunset", () => {+ beforeEach(() => {+ vi.setSystemTime(AFTER_SUNSET);+ });++ for (const key of Object.keys(V1) as Key[]) {+ it(`${key} answers 410 after the sunset`, async () => {+ const res = await request(appFor(key)).get("/probe");++ expect(res.status).toBe(410);+ expect(res.body).toMatchObject({+ success: false,+ code: "ENDPOINT_REMOVED",+ replacement: V1[key],+ });+ expect(res.headers["sunset"]).toBe(V1_SUNSET);+ });++ it(`${key} keeps serving a team extended on the v1 surface`, async () => {+ const res = await request(appFor(key, extendedOn("v1"))).get("/probe");++ expect(res.status).toBe(200);+ expect(res.body.data).toEqual({ markdown: "# hi" });+ });+ }++ it("does not extend v1 for a team extended on another surface", async () => {+ const res = await request(appFor("v1_scrape", extendedOn("v0"))).get(+ "/probe",+ );++ expect(res.status).toBe(410);+ });++ it("does not extend v1 for a flag under a single route key", async () => {+ const res = await request(appFor("v1_scrape", extendedOn("v1_scrape"))).get(+ "/probe",+ );++ expect(res.status).toBe(410);+ });+});diff --git a/apps/api/src/__tests__/snips/v1/deprecation.test.ts b/apps/api/src/__tests__/snips/v1/deprecation.test.tsindex 0e153706a..dca867ad3 100644--- a/apps/api/src/__tests__/snips/v1/deprecation.test.ts+++ b/apps/api/src/__tests__/snips/v1/deprecation.test.ts@@ -76,13 +76,57 @@ describe("Deprecation warnings on legacy endpoints", () => {expect(res.body.replacement).toBe("/v2/search");}, 30000);- it("non-deprecated endpoints do not emit Deprecation header or warnings", async () => {+ it("POST /v1/scrape points at /v2/scrape and the migration guide", async () => {const res = await request(TEST_API_URL).post("/v1/scrape").set("Authorization", `Bearer ${identity.apiKey}`).set("Content-Type", "application/json").send({ url: "https://firecrawl.dev" });+ expect(res.statusCode).toBe(200);+ expect(res.headers["deprecation"]).toBe("@1793923200");+ expect(res.headers["sunset"]).toBe("Thu, 10 Dec 2026 15:00:00 GMT");+ expect(res.headers["warning"]).toMatch(/\/v1\/scrape is deprecated/);+ expect(res.headers["link"]).toBe(+ '<https://docs.firecrawl.dev/migrate-to-v2>; rel="deprecation", </v2/scrape>; rel="successor-version"',+ );+ expect(res.body.warnings.some((w: string) => /\/v2\/scrape/.test(w))).toBe(+ true,+ );+ expect(res.body.replacement).toBe("/v2/scrape");+ }, 60000);++ it("GET /v1/team/credit-usage points at its v2 route", async () => {+ const res = await request(TEST_API_URL)+ .get("/v1/team/credit-usage")+ .set("Authorization", `Bearer ${identity.apiKey}`);++ // Self-hosted has no billing client, so the status varies; the notice must not.+ expect(res.headers["deprecation"]).toBe("@1793923200");+ expect(res.headers["link"]).toContain(+ '</v2/team/credit-usage>; rel="successor-version"',+ );+ expect(res.body.replacement).toBe("/v2/team/credit-usage");+ }, 30000);++ it("GET /v1/concurrency-check points at its v2 route", async () => {+ const res = await request(TEST_API_URL)+ .get("/v1/concurrency-check")+ .set("Authorization", `Bearer ${identity.apiKey}`);++ expect(res.statusCode).toBe(200);+ expect(res.headers["deprecation"]).toBe("@1793923200");+ expect(res.headers["link"]).toContain(+ '</v2/concurrency-check>; rel="successor-version"',+ );+ expect(res.body.replacement).toBe("/v2/concurrency-check");+ }, 30000);++ it("non-deprecated endpoints do not emit Deprecation header or warnings", async () => {+ const res = await request(TEST_API_URL)+ .get("/v2/team/credit-usage")+ .set("Authorization", `Bearer ${identity.apiKey}`);+expect(res.headers["deprecation"]).toBeUndefined();expect(res.headers["warning"]).toBeUndefined();if (res.body && typeof res.body === "object") {diff --git a/apps/api/src/lib/deprecations.ts b/apps/api/src/lib/deprecations.tsindex 7616ea23f..4b04e1fb0 100644--- a/apps/api/src/lib/deprecations.ts+++ b/apps/api/src/lib/deprecations.ts@@ -25,6 +25,14 @@ export interface Notice {replacement?: string;}+// Every v1 route below shares one deprecation date, sunset and extension flag.+const V1 = {+ docs: "https://docs.firecrawl.dev/migrate-to-v2",+ deprecatedAt: "@1793923200",+ sunset: "Thu, 10 Dec 2026 15:00:00 GMT",+ surface: "v1",+};+// Every legacy entry shipped together in #3469, so they share one date.const DEPRECATIONS = {v1_extract: {@@ -122,6 +130,126 @@ const DEPRECATIONS = {deprecatedAt: "@1778025600",surface: "v0",},+ v1_scrape: {+ message:+ "/v1/scrape is deprecated. Use /v2/scrape instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/scrape",+ ...V1,+ },+ v1_scrape_status: {+ message:+ "/v1/scrape/:jobId is deprecated. Use /v2/scrape/:jobId instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/scrape/:jobId",+ ...V1,+ },+ v1_crawl: {+ message:+ "/v1/crawl is deprecated. Use /v2/crawl instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/crawl",+ ...V1,+ },+ v1_crawl_status: {+ message:+ "/v1/crawl/:jobId is deprecated. Use /v2/crawl/:jobId instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/crawl/:jobId",+ ...V1,+ },+ v1_crawl_cancel: {+ message:+ "DELETE /v1/crawl/:jobId is deprecated. Use DELETE /v2/crawl/:jobId instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/crawl/:jobId",+ ...V1,+ },+ v1_crawl_errors: {+ message:+ "/v1/crawl/:jobId/errors is deprecated. Use /v2/crawl/:jobId/errors instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/crawl/:jobId/errors",+ ...V1,+ },+ v1_crawl_active: {+ message:+ "/v1/crawl/active is deprecated. Use /v2/crawl/active instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/crawl/active",+ ...V1,+ },+ v1_crawl_ongoing: {+ message:+ "/v1/crawl/ongoing is deprecated. Use /v2/crawl/active instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/crawl/active",+ ...V1,+ },+ v1_batch_scrape: {+ message:+ "/v1/batch/scrape is deprecated. Use /v2/batch/scrape instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/batch/scrape",+ ...V1,+ },+ v1_batch_scrape_status: {+ message:+ "/v1/batch/scrape/:jobId is deprecated. Use /v2/batch/scrape/:jobId instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/batch/scrape/:jobId",+ ...V1,+ },+ v1_batch_scrape_cancel: {+ message:+ "DELETE /v1/batch/scrape/:jobId is deprecated. Use DELETE /v2/batch/scrape/:jobId instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/batch/scrape/:jobId",+ ...V1,+ },+ v1_batch_scrape_errors: {+ message:+ "/v1/batch/scrape/:jobId/errors is deprecated. Use /v2/batch/scrape/:jobId/errors instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/batch/scrape/:jobId/errors",+ ...V1,+ },+ v1_search: {+ message:+ "/v1/search is deprecated. Use /v2/search instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/search",+ ...V1,+ },+ v1_map: {+ message:+ "/v1/map is deprecated. Use /v2/map instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/map",+ ...V1,+ },+ v1_concurrency_check: {+ message:+ "/v1/concurrency-check is deprecated. Use /v2/concurrency-check instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/concurrency-check",+ ...V1,+ },+ v1_team_credit_usage: {+ message:+ "/v1/team/credit-usage is deprecated. Use /v2/team/credit-usage instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/team/credit-usage",+ ...V1,+ },+ v1_team_credit_usage_historical: {+ message:+ "/v1/team/credit-usage/historical is deprecated. Use /v2/team/credit-usage/historical instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/team/credit-usage/historical",+ ...V1,+ },+ v1_team_token_usage: {+ message:+ "/v1/team/token-usage is deprecated. Use /v2/team/token-usage instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/team/token-usage",+ ...V1,+ },+ v1_team_token_usage_historical: {+ message:+ "/v1/team/token-usage/historical is deprecated. Use /v2/team/token-usage/historical instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/team/token-usage/historical",+ ...V1,+ },+ v1_team_queue_status: {+ message:+ "/v1/team/queue-status is deprecated. Use /v2/team/queue-status instead. See https://docs.firecrawl.dev/migrate-to-v2.",+ replacement: "/v2/team/queue-status",+ ...V1,+ },} as const satisfies Record<string, Deprecation>;type DeprecationKey = keyof typeof DEPRECATIONS;diff --git a/apps/api/src/routes/v1.ts b/apps/api/src/routes/v1.tsindex a731dada9..195fcb032 100644--- a/apps/api/src/routes/v1.ts+++ b/apps/api/src/routes/v1.ts@@ -51,6 +51,7 @@ v1Router.use(requestTimingMiddleware("v1"));v1Router.post("/scrape",authMiddleware(RateLimiterMode.Scrape, { allowKeyless: true }),+ deprecationMiddleware("v1_scrape"),inferIntegrationMiddleware,restrictedOptionsCountryCheck,checkCreditsMiddleware(1),@@ -61,6 +62,7 @@ v1Router.post(v1Router.post("/crawl",authMiddleware(RateLimiterMode.Crawl),+ deprecationMiddleware("v1_crawl"),inferIntegrationMiddleware,restrictedOptionsCountryCheck,checkCreditsMiddleware(),@@ -72,6 +74,7 @@ v1Router.post(v1Router.post("/batch/scrape",authMiddleware(RateLimiterMode.Scrape),+ deprecationMiddleware("v1_batch_scrape"),inferIntegrationMiddleware,restrictedOptionsCountryCheck,checkCreditsMiddleware(),@@ -83,6 +86,7 @@ v1Router.post(v1Router.post("/search",authMiddleware(RateLimiterMode.Search, { allowKeyless: true }),+ deprecationMiddleware("v1_search"),inferIntegrationMiddleware,restrictedOptionsCountryCheck,checkCreditsMiddleware(undefined, SEARCH_CREDITS_FEATURE_ID),@@ -92,6 +96,7 @@ v1Router.post(v1Router.post("/map",authMiddleware(RateLimiterMode.Map),+ deprecationMiddleware("v1_map"),inferIntegrationMiddleware,checkCreditsMiddleware(1),blocklistMiddleware,@@ -101,6 +106,7 @@ v1Router.post(v1Router.get("/crawl/ongoing",authMiddleware(RateLimiterMode.CrawlStatus),+ deprecationMiddleware("v1_crawl_ongoing"),wrap(ongoingCrawlsController),);@@ -108,12 +114,14 @@ v1Router.get(v1Router.get("/crawl/active",authMiddleware(RateLimiterMode.CrawlStatus),+ deprecationMiddleware("v1_crawl_active"),wrap(ongoingCrawlsController),);v1Router.get("/crawl/:jobId",authMiddleware(RateLimiterMode.CrawlStatus),+ deprecationMiddleware("v1_crawl_status"),validateJobIdParam,wrap(crawlStatusController),);@@ -121,6 +129,7 @@ v1Router.get(v1Router.get("/batch/scrape/:jobId",authMiddleware(RateLimiterMode.CrawlStatus),+ deprecationMiddleware("v1_batch_scrape_status"),validateJobIdParam,// Yes, it uses the same controller as the normal crawl status controllerwrap((req: any, res): any => crawlStatusController(req, res, true)),@@ -129,24 +138,28 @@ v1Router.get(v1Router.get("/crawl/:jobId/errors",authMiddleware(RateLimiterMode.CrawlStatus),+ deprecationMiddleware("v1_crawl_errors"),wrap(crawlErrorsController),);v1Router.get("/batch/scrape/:jobId/errors",authMiddleware(RateLimiterMode.CrawlStatus),+ deprecationMiddleware("v1_batch_scrape_errors"),wrap(crawlErrorsController),);v1Router.get("/scrape/:jobId",authMiddleware(RateLimiterMode.CrawlStatus),+ deprecationMiddleware("v1_scrape_status"),wrap(scrapeStatusController),);v1Router.get("/concurrency-check",authMiddleware(RateLimiterMode.CrawlStatus),+ deprecationMiddleware("v1_concurrency_check"),wrap(concurrencyCheckController),);@@ -207,12 +220,14 @@ v1Router.get(v1Router.delete("/crawl/:jobId",authMiddleware(RateLimiterMode.CrawlStatus),+ deprecationMiddleware("v1_crawl_cancel"),crawlCancelController,);v1Router.delete("/batch/scrape/:jobId",authMiddleware(RateLimiterMode.CrawlStatus),+ deprecationMiddleware("v1_batch_scrape_cancel"),crawlCancelController,);// v1Router.get("/checkJobStatus/:jobId", crawlJobStatusPreviewController);@@ -237,29 +252,34 @@ v1Router.post(v1Router.get("/team/credit-usage",authMiddleware(RateLimiterMode.Account),+ deprecationMiddleware("v1_team_credit_usage"),wrap(creditUsageController),);v1Router.get("/team/credit-usage/historical",authMiddleware(RateLimiterMode.Account),+ deprecationMiddleware("v1_team_credit_usage_historical"),wrap(creditUsageHistoricalController),);v1Router.get("/team/token-usage",authMiddleware(RateLimiterMode.Account),+ deprecationMiddleware("v1_team_token_usage"),wrap(tokenUsageController),);v1Router.get("/team/token-usage/historical",authMiddleware(RateLimiterMode.Account),+ deprecationMiddleware("v1_team_token_usage_historical"),wrap(tokenUsageHistoricalController),);v1Router.get("/team/queue-status",authMiddleware(RateLimiterMode.Account),+ deprecationMiddleware("v1_team_queue_status"),wrap(queueStatusController),);