Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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 controller
wrap((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),
);