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): deprecate research index github search for the developer index (#4522)
Kris Oei13d06aaf1e25
diff --git a/apps/api/src/__tests__/routes/deprecations-existing-routes.routes.test.ts b/apps/api/src/__tests__/routes/deprecations-existing-routes.routes.test.tsnew file mode 100644index 000000000..60847f4a9--- /dev/null+++ b/apps/api/src/__tests__/routes/deprecations-existing-routes.routes.test.ts@@ -0,0 +1,97 @@+import express from "express";+import request from "supertest";+import { deprecationMiddleware } from "../../lib/deprecations";++// Every pre-existing deprecation entry and its replacement. Pinned so the+// github entry cannot change anyone else's wire output. All 13 shipped in+// #3469 on 2026-05-06, which is the date they now emit.+const LEGACY_DEPRECATED_AT = "@1778025600";++const EXISTING = {+ v1_extract: "/v2/scrape",+ v1_extract_status: "/v2/scrape",+ v2_extract: "/v2/scrape",+ v2_extract_status: "/v2/scrape",+ v1_deep_research: "/v2/search",+ v1_deep_research_status: "/v2/search",+ v1_llmstxt: undefined,+ v1_llmstxt_status: undefined,+ v0_scrape: "/v2/scrape",+ v0_crawl: "/v2/crawl",+ v0_crawl_status: "/v2/crawl/:jobId",+ v0_crawl_cancel: "/v2/crawl/:jobId",+ v0_search: "/v2/search",+} as const;++type Key = keyof typeof EXISTING;++// What the old middleware did, replayed on a copy, so we can compare bytes.+function legacyAnnotate(body: any, message: string, replacement?: string) {+ const copy = JSON.parse(JSON.stringify(body));+ const existing = Array.isArray(copy.warnings) ? copy.warnings : [];+ copy.warnings = [...existing, message];+ if (replacement && copy.replacement === undefined) {+ copy.replacement = replacement;+ }+ return JSON.stringify(copy);+}++function appFor(key: Key, body: unknown) {+ const app = express();+ app.get("/probe", deprecationMiddleware(key), (_req, res) => {+ res.status(200).json(body);+ });+ return app;+}++const BODIES: Record<string, unknown> = {+ plain: { success: true, id: "abc" },+ "with existing warnings": { success: true, warnings: ["upstream note"] },+ "with existing replacement": { success: true, replacement: "/keep/me" },+ "warnings first": { warnings: [], success: true },+};++describe("pre-existing deprecated routes are unchanged", () => {+ for (const key of Object.keys(EXISTING) as Key[]) {+ describe(key, () => {+ it("emits the shared 2026-05-06 Deprecation date and no Sunset", async () => {+ const res = await request(appFor(key, BODIES.plain)).get("/probe");++ expect(res.headers["deprecation"]).toBe(LEGACY_DEPRECATED_AT);+ expect(res.headers["sunset"]).toBeUndefined();+ expect(res.headers["warning"]).toMatch(/^299 - "/);+ if (EXISTING[key]) {+ expect(res.headers["link"]).toBe(+ `<${EXISTING[key]}>; rel="successor-version"`,+ );+ } else {+ expect(res.headers["link"]).toBeUndefined();+ }+ });++ for (const [label, body] of Object.entries(BODIES)) {+ it(`serialises a ${label} body byte-for-byte as before`, async () => {+ const res = await request(appFor(key, body)).get("/probe");+ const message = res.headers["warning"].replace(/^299 - "|"$/g, "");++ expect(res.text).toBe(legacyAnnotate(body, message, EXISTING[key]));+ });+ }++ it("no longer mutates the object the controller passed in", async () => {+ const body: any = { success: true };+ await request(appFor(key, body)).get("/probe");++ expect(body.warnings).toBeUndefined();+ expect(body.replacement).toBeUndefined();+ });+ });+ }++ it("arrays and strings pass straight through", async () => {+ const arr = await request(appFor("v0_search", [1, 2])).get("/probe");+ expect(arr.text).toBe("[1,2]");+ const str = await request(appFor("v0_search", "hello")).get("/probe");+ expect(str.text).toBe('"hello"');+ });+});diff --git a/apps/api/src/__tests__/routes/research-github-deprecation.routes.test.ts b/apps/api/src/__tests__/routes/research-github-deprecation.routes.test.tsnew file mode 100644index 000000000..cd8cf4ab9--- /dev/null+++ b/apps/api/src/__tests__/routes/research-github-deprecation.routes.test.ts@@ -0,0 +1,185 @@+import express from "express";+import request from "supertest";+import { createResearchRouter } from "../../controllers/v2/research-proxy";++// Mounts the real research router against a stubbed upstream, so the+// deprecation contract is exercised through the actual controller rather than+// a fake. The one thing only this test can reach is the logged payload: on the+// canonical mount the controller responds with the same object it later writes+// to Postgres, so a mutating res.json would leak the notice into the+// research_github_searches row.+const upstreamCalls: string[] = [];+const loggedRows: any[] = [];++let upstreamBody: any = {+ success: true,+ results: [+ {+ resultType: "github_history",+ repo: "milvus-io/milvus",+ url: "https://github.com/milvus-io/milvus/issues/1",+ pageType: "issue",+ number: 1,+ snippet: "hybrid search",+ contentMd: "# hybrid search",+ segmentCount: 2,+ scores: { rrf: 0.5 },+ },+ ],+};+let upstreamStatus = 200;++vi.mock("../../lib/research-upstream", () => ({+ fetchResearchUpstream: async (options: { path: string }) => {+ upstreamCalls.push(options.path);+ return {+ status: upstreamStatus,+ ok: upstreamStatus >= 200 && upstreamStatus < 300,+ headers: new Headers(),+ text: async () => JSON.stringify(upstreamBody),+ };+ },+}));++vi.mock("../../services/logging/log_job", () => ({+ logRequest: async () => {},+ logResearchEndpoint: async (row: any) => {+ loggedRows.push(row);+ },+}));++vi.mock("../../lib/keyless", () => ({+ chargeKeylessCredits: async () => {},+}));++vi.mock("../../services/billing/credit_billing", () => ({+ billTeam: async () => {},+}));++function appWith(legacy: boolean) {+ const app = express();+ app.use((req: any, _res, next) => {+ req.auth = { team_id: "team-test", plan: "standard" };+ req.acuc = { api_key_id: null };+ next();+ });+ app.use(+ legacy ? "/v2/research" : "/v2/search/research",+ createResearchRouter(legacy ? { legacy: true } : {}),+ );+ return app;+}++const canonical = appWith(false);+const legacy = appWith(true);++beforeEach(() => {+ upstreamCalls.length = 0;+ loggedRows.length = 0;+ upstreamStatus = 200;+});++describe("github search deprecation, canonical mount", () => {+ it("sets every deprecation header", async () => {+ const res = await request(canonical).get(+ "/v2/search/research/github?query=milvus+hybrid+search&k=3",+ );++ expect(res.statusCode).toBe(200);+ expect(res.headers["deprecation"]).toBe("@1788393600");+ expect(res.headers["sunset"]).toBe("Tue, 03 Nov 2026 23:59:59 GMT");+ expect(res.headers["link"]).toContain(+ '<https://docs.firecrawl.dev/features/developer>; rel="deprecation"',+ );+ expect(res.headers["link"]).toContain(+ '</v2/search/developer>; rel="successor-version"',+ );+ expect(res.headers["warning"]).toMatch(/^299 - "/);+ expect(res.headers["warning"]).toContain("2026-11-03");+ });++ it("adds warnings and replacement to the body without losing the results", async () => {+ const res = await request(canonical).get(+ "/v2/search/research/github?query=x",+ );++ expect(res.body.success).toBe(true);+ expect(res.body.results).toHaveLength(1);+ expect(res.body.results[0].repo).toBe("milvus-io/milvus");+ expect(res.body.replacement).toBe("/v2/search/developer");+ expect(res.body.warnings).toHaveLength(1);+ expect(res.body.warnings[0]).toContain("/v2/search/developer");+ expect(res.body.warnings[0]).toContain("2026-11-03");+ });++ it("keeps the deprecation notice out of the logged row", async () => {+ await request(canonical).get("/v2/search/research/github?query=x");++ expect(loggedRows).toHaveLength(1);+ const logged = loggedRows[0].response;+ expect(logged.success).toBe(true);+ expect(logged.results).toHaveLength(1);+ expect(logged.warnings).toBeUndefined();+ expect(logged.replacement).toBeUndefined();+ expect(JSON.stringify(logged)).not.toContain("deprecated");+ });++ it("still proxies to the unchanged upstream path", async () => {+ await request(canonical).get("/v2/search/research/github?query=x");++ expect(upstreamCalls).toEqual(["/v2/research/github"]);+ });++ it("warns on a rejected request too", async () => {+ const res = await request(canonical).get("/v2/search/research/github");++ expect(res.statusCode).toBe(400);+ expect(res.body.success).toBe(false);+ expect(res.headers["deprecation"]).toBe("@1788393600");+ expect(res.body.warnings).toHaveLength(1);+ });++ it("leaves the paper routes on the same router alone", async () => {+ const res = await request(canonical).get(+ "/v2/search/research/papers?query=rag",+ );++ expect(res.statusCode).toBe(200);+ expect(res.headers["deprecation"]).toBeUndefined();+ expect(res.headers["sunset"]).toBeUndefined();+ expect(res.headers["link"]).toBeUndefined();+ expect(res.headers["warning"]).toBeUndefined();+ expect(res.body.warnings).toBeUndefined();+ expect(res.body.replacement).toBeUndefined();+ expect(loggedRows[0].response.warnings).toBeUndefined();+ });+});++describe("github search deprecation, legacy mount", () => {+ it("keeps the snake_case aliases alongside the notice", async () => {+ const res = await request(legacy).get("/v2/research/github?query=x");++ expect(res.statusCode).toBe(200);+ expect(res.headers["deprecation"]).toBe("@1788393600");+ expect(res.body.results[0].result_type).toBe("github_history");+ expect(res.body.results[0].page_type).toBe("issue");+ expect(res.body.results[0].content_md).toBe("# hybrid search");+ expect(res.body.results[0].segment_count).toBe(2);+ expect(res.body.warnings).toHaveLength(1);+ expect(res.body.replacement).toBe("/v2/search/developer");+ });++ it("does not grow a snake_case twin of the injected keys", async () => {+ const res = await request(legacy).get("/v2/research/github?query=x");++ expect(res.body).not.toHaveProperty("warnings_");+ expect(res.body).not.toHaveProperty("replacement_");+ });++ it("keeps the notice out of the logged row here as well", async () => {+ await request(legacy).get("/v2/research/github?query=x");++ expect(loggedRows[0].response.warnings).toBeUndefined();+ expect(loggedRows[0].response.replacement).toBeUndefined();+ });+});diff --git a/apps/api/src/__tests__/routes/research-keyless.routes.test.ts b/apps/api/src/__tests__/routes/research-keyless.routes.test.tsindex d5276f91c..26b0097ec 100644--- a/apps/api/src/__tests__/routes/research-keyless.routes.test.ts+++ b/apps/api/src/__tests__/routes/research-keyless.routes.test.ts@@ -112,6 +112,20 @@ describe("RESEARCH_KEYLESS_DISABLED parsing", () => {expect(config.RESEARCH_KEYLESS_DISABLED).toEqual(["inspect", "similar"]);});+ it("accepts the deprecated github operation only when it is named", async () => {+ const { config } = await loadWithFlag("github");++ expect(config.RESEARCH_KEYLESS_DISABLED).toEqual(["github"]);+ });++ it("keeps github out of the true/all shorthand and out of the default", async () => {+ for (const flag of [undefined, "true", "all", "on", "1", "yes"]) {+ const { config } = await loadWithFlag(flag);++ expect(config.RESEARCH_KEYLESS_DISABLED).not.toContain("github");+ }+ });+it("refuses an unknown operation at boot instead of silently ignoring it", async () => {await expect(loadWithFlag("inspect,papers")).rejects.toThrow();});@@ -142,6 +156,33 @@ describe("Research Index paper operation gate", () => {).toBe(false);});+ it("blocks the deprecated github operation once the flag names it", async () => {+ const { isResearchKeylessDisabled } = await loadWithFlag("github");++ expect(+ isResearchKeylessDisabled(fakeRequest("/github", { query: "x" })),+ ).toBe(true);+ expect(+ isResearchKeylessDisabled(+ fakeRequest("/v2/search/research/github", { query: "x" }),+ ),+ ).toBe(true);+ expect(+ isResearchKeylessDisabled(fakeRequest("/papers", { query: "rag" })),+ ).toBe(false);+ });++ it("does not mistake a paper path for the github route", async () => {+ const { isResearchKeylessDisabled } = await loadWithFlag("github");++ expect(isResearchKeylessDisabled(fakeRequest("/papers/github"))).toBe(+ false,+ );+ expect(+ isResearchKeylessDisabled(fakeRequest("/papers/github/similar")),+ ).toBe(false);+ });+it("blocks only the named operation when the scope is narrowed", async () => {const { isResearchKeylessDisabled } = await loadWithFlag("inspect");diff --git a/apps/api/src/__tests__/snips/v1/deprecation.test.ts b/apps/api/src/__tests__/snips/v1/deprecation.test.tsindex ed2dd69ec..0e153706a 100644--- a/apps/api/src/__tests__/snips/v1/deprecation.test.ts+++ b/apps/api/src/__tests__/snips/v1/deprecation.test.ts@@ -23,7 +23,7 @@ describe("Deprecation warnings on legacy endpoints", () => {expect(res.statusCode).toBe(200);expect(res.body.success).toBe(true);- expect(res.headers["deprecation"]).toBe("true");+ expect(res.headers["deprecation"]).toBe("@1778025600");expect(res.headers["warning"]).toMatch(/^299 - "/);expect(res.headers["warning"]).toMatch(/llmstxt/i);expect(Array.isArray(res.body.warnings)).toBe(true);@@ -43,7 +43,7 @@ describe("Deprecation warnings on legacy endpoints", () => {.set("Authorization", `Bearer ${identity.apiKey}`);expect(res.statusCode).toBe(404);- expect(res.headers["deprecation"]).toBe("true");+ expect(res.headers["deprecation"]).toBe("@1778025600");expect(res.headers["warning"]).toMatch(/deprecated/i);expect(Array.isArray(res.body.warnings)).toBe(true);expect(res.body.warnings.some((w: string) => /deprecated/i.test(w))).toBe(@@ -64,7 +64,7 @@ describe("Deprecation warnings on legacy endpoints", () => {});expect(res.statusCode).toBe(200);- expect(res.headers["deprecation"]).toBe("true");+ expect(res.headers["deprecation"]).toBe("@1778025600");expect(res.headers["warning"]).toMatch(/deep-research/i);expect(res.headers["link"]).toContain('</v2/search>; rel="successor-version"',diff --git a/apps/api/src/__tests__/snips/v2/research.test.ts b/apps/api/src/__tests__/snips/v2/research.test.tsindex 6815f5cab..64a433b09 100644--- a/apps/api/src/__tests__/snips/v2/research.test.ts+++ b/apps/api/src/__tests__/snips/v2/research.test.ts@@ -101,9 +101,10 @@ async function snapshotKeylessCounts(): Promise<Map<string, number>> {// our snapshot window resets the counters. Ambiguity retries the whole probe// (the requests under test are idempotent zero-credit GETs) instead of// asserting on a poisoned window.-async function issueAndResolveKeylessIp<- T extends { statusCode: number },->(forwardedIp: string, issue: () => Promise<T>): Promise<{ res: T; ip: string }> {+async function issueAndResolveKeylessIp<T extends { statusCode: number }>(+ forwardedIp: string,+ issue: () => Promise<T>,+): Promise<{ res: T; ip: string }> {if (KEYLESS_PROXY_SECRET) {return { res: await issue(), ip: forwardedIp };}@@ -116,7 +117,9 @@ async function issueAndResolveKeylessIp<.filter(([ip, count]) => count > (before.get(ip) ?? 0)).map(([ip]) => ip);if (bumped.length === 1) return { res, ip: bumped[0] };- attempts.push(bumped.length === 0 ? "none" : `multiple[${bumped.join(", ")}]`);+ attempts.push(+ bumped.length === 0 ? "none" : `multiple[${bumped.join(", ")}]`,+ );}// Distinguish the two failure modes: "none" means the request was never// counted against any candidate key (not treated as keyless, or the server@@ -536,3 +539,94 @@ describeIf(HAS_RESEARCH)("Research API", () => {}, 180000);});});++const GITHUB_DEPRECATED_AT = "@1788393600";+const GITHUB_SUNSET = "Tue, 03 Nov 2026 23:59:59 GMT";++describeIf(HAS_RESEARCH)("Research API github search deprecation", () => {+ it("carries the deprecation headers and body warning on the canonical mount", async () => {+ const identity = await idmux({+ name: "research/github deprecation canonical",+ credits: 100,+ });++ const res = await researchRaw(+ "/v2/search/research/github",+ { query: "milvus hybrid search", k: 3 },+ identity,+ );++ expect(res.statusCode).toBe(200);+ expect(res.body.success).toBe(true);++ expect(res.headers["deprecation"]).toBe(GITHUB_DEPRECATED_AT);+ expect(res.headers["sunset"]).toBe(GITHUB_SUNSET);+ expect(res.headers["link"]).toContain('rel="deprecation"');+ expect(res.headers["link"]).toContain(+ '</v2/search/developer>; rel="successor-version"',+ );+ expect(res.headers["warning"]).toMatch(/^299 - "/);++ expect(Array.isArray(res.body.warnings)).toBe(true);+ expect(+ res.body.warnings.some((w: string) => /\/v2\/search\/developer/.test(w)),+ ).toBe(true);+ expect(res.body.replacement).toBe("/v2/search/developer");+ }, 120000);++ it("leaves the paper routes on the same router undeprecated", async () => {+ const identity = await idmux({+ name: "research/github deprecation scope",+ credits: 100,+ });++ const res = await researchRaw(+ "/v2/search/research/papers",+ { query: "retrieval augmented generation", k: 1 },+ identity,+ );++ expect(res.statusCode).toBe(200);+ expect(res.headers["deprecation"]).toBeUndefined();+ expect(res.headers["sunset"]).toBeUndefined();+ expect(res.body.warnings).toBeUndefined();+ expect(res.body.replacement).toBeUndefined();+ }, 120000);++ it("keeps the legacy snake_case aliases alongside the new warning", async () => {+ const identity = await idmux({+ name: "research/github deprecation legacy",+ credits: 100,+ });++ const res = await researchRaw(+ "/v2/research/github",+ { query: "milvus hybrid search", k: 3 },+ identity,+ );++ expect(res.statusCode).toBe(200);+ expect(res.headers["deprecation"]).toBe(GITHUB_DEPRECATED_AT);+ expect(Array.isArray(res.body.warnings)).toBe(true);+ expect(res.body.results.length).toBeGreaterThan(0);+ // resultType is optional, so only assert the alias when the camel key is set.+ const first = res.body.results[0];+ if (first.resultType !== undefined) {+ expect(first.result_type).toBe(first.resultType);+ }+ }, 120000);++ it("still warns when the request is rejected", async () => {+ const identity = await idmux({+ name: "research/github deprecation 400",+ credits: 100,+ });++ const res = await researchRaw("/v2/search/research/github", {}, identity);++ expect(res.statusCode).toBe(400);+ expect(res.body.success).toBe(false);+ expect(res.headers["deprecation"]).toBe(GITHUB_DEPRECATED_AT);+ expect(Array.isArray(res.body.warnings)).toBe(true);+ }, 60000);+});diff --git a/apps/api/src/config.ts b/apps/api/src/config.tsindex a42870fb8..568c8380d 100644--- a/apps/api/src/config.ts+++ b/apps/api/src/config.ts@@ -23,7 +23,16 @@ const RESEARCH_PAPER_OPERATIONS = ["similar",] as const;-export type ResearchPaperOperation = (typeof RESEARCH_PAPER_OPERATIONS)[number];+// "github" is out of the default and the true/all shorthand, so keyless+// behaviour is unchanged until someone names it. An explicit list replaces the+// default, so closing it means RESEARCH_KEYLESS_DISABLED=search,inspect,read,similar,github+const RESEARCH_KEYLESS_OPERATIONS = [+ ...RESEARCH_PAPER_OPERATIONS,+ "github",+] as const;++export type ResearchKeylessOperation =+ (typeof RESEARCH_KEYLESS_OPERATIONS)[number];const researchKeylessDisabled = z.preprocess(value => {@@ -40,7 +49,7 @@ const researchKeylessDisabled = z.preprocess(.filter(Boolean);},z- .array(z.enum(RESEARCH_PAPER_OPERATIONS))+ .array(z.enum(RESEARCH_KEYLESS_OPERATIONS)).default([...RESEARCH_PAPER_OPERATIONS]),);diff --git a/apps/api/src/controllers/v2/research-proxy.ts b/apps/api/src/controllers/v2/research-proxy.tsindex 764925e97..3a0eef589 100644--- a/apps/api/src/controllers/v2/research-proxy.ts+++ b/apps/api/src/controllers/v2/research-proxy.ts@@ -17,6 +17,7 @@ import type {} from "../../services/logging/log_job";import type { RequestWithAuth } from "../v1/types";import { wrap } from "../../routes/shared";+import { deprecationMiddleware } from "../../lib/deprecations";import { integrationSchema } from "../../utils/integration";import { requestOrigin } from "../../lib/request-origin";@@ -521,8 +522,10 @@ export function createResearchRouter(options: { legacy?: boolean } = {}) {}),);+ // On the route, not the mounts, so the paper routes stay undeprecated.router.get("/github",+ deprecationMiddleware("v2_research_github_search"),wrap(createResearchController(githubSearchSchema,diff --git a/apps/api/src/lib/deprecations.ts b/apps/api/src/lib/deprecations.tsindex 02ede0a01..752599543 100644--- a/apps/api/src/lib/deprecations.ts+++ b/apps/api/src/lib/deprecations.ts@@ -3,66 +3,90 @@ import { NextFunction, Request, Response } from "express";interface Deprecation {message: string;replacement?: string;+ // RFC 9745 requires a Date here, e.g. "@1788393600".+ deprecatedAt: string;sunset?: string;docs?: string;}+// Every legacy entry shipped together in #3469, so they share one date.const DEPRECATIONS = {v1_extract: {message:"/v1/extract is deprecated. Use /v2/scrape with formats including a 'json' format object.",replacement: "/v2/scrape",+ deprecatedAt: "@1778025600",},v1_extract_status: {message:"/v1/extract/:jobId is deprecated. Use /v2/scrape with formats including a 'json' format object.",replacement: "/v2/scrape",+ deprecatedAt: "@1778025600",},v2_extract: {message:"/v2/extract is deprecated. Use /v2/scrape with formats including a 'json' format object.",replacement: "/v2/scrape",+ deprecatedAt: "@1778025600",},v2_extract_status: {message:"/v2/extract/:jobId is deprecated. Use /v2/scrape with formats including a 'json' format object.",replacement: "/v2/scrape",+ deprecatedAt: "@1778025600",+ },+ v2_research_github_search: {+ message:+ "The research index GitHub search (GET /v2/search/research/github, legacy GET /v2/research/github) is deprecated and stops responding after 2026-11-03. Use GET or POST /v2/search/developer instead: it searches GitHub issues, pull requests and READMEs plus curated documentation sources, returns matched passages, and adds filters for repo, language, license and stars. Response changes: 'snippet' becomes 'passages', results gain an 'id', and there is no score breakdown and no web fallback result type.",+ replacement: "/v2/search/developer",+ docs: "https://docs.firecrawl.dev/features/developer",+ deprecatedAt: "@1788393600",+ sunset: "Tue, 03 Nov 2026 23:59:59 GMT",},v1_deep_research: {message: "/v1/deep-research is deprecated. Use /v2/search instead.",replacement: "/v2/search",+ deprecatedAt: "@1778025600",},v1_deep_research_status: {message: "/v1/deep-research/:jobId is deprecated. Use /v2/search instead.",replacement: "/v2/search",+ deprecatedAt: "@1778025600",},v1_llmstxt: {message: "/v1/llmstxt is deprecated and will not be replaced.",+ deprecatedAt: "@1778025600",},v1_llmstxt_status: {message: "/v1/llmstxt/:jobId is deprecated and will not be replaced.",+ deprecatedAt: "@1778025600",},v0_scrape: {message: "/v0/scrape is deprecated. Use /v2/scrape instead.",replacement: "/v2/scrape",+ deprecatedAt: "@1778025600",},v0_crawl: {message: "/v0/crawl is deprecated. Use /v2/crawl instead.",replacement: "/v2/crawl",+ deprecatedAt: "@1778025600",},v0_crawl_status: {message:"/v0/crawl/status/:jobId is deprecated. Use /v2/crawl/:jobId instead.",replacement: "/v2/crawl/:jobId",+ deprecatedAt: "@1778025600",},v0_crawl_cancel: {message:"/v0/crawl/cancel/:jobId is deprecated. Use DELETE /v2/crawl/:jobId instead.",replacement: "/v2/crawl/:jobId",+ deprecatedAt: "@1778025600",},v0_search: {message: "/v0/search is deprecated. Use /v2/search instead.",replacement: "/v2/search",+ deprecatedAt: "@1778025600",},} as const satisfies Record<string, Deprecation>;@@ -77,7 +101,7 @@ export function deprecationMiddleware(key: DeprecationKey) {const dep: Deprecation = DEPRECATIONS[key];return (req: Request, res: Response, next: NextFunction) => {// RFC 9745 Deprecation header.- res.setHeader("Deprecation", "true");+ res.setHeader("Deprecation", dep.deprecatedAt);// RFC 8594 Sunset header.if (dep.sunset) res.setHeader("Sunset", dep.sunset);@@ -96,11 +120,16 @@ export function deprecationMiddleware(key: DeprecationKey) {const originalJson = res.json.bind(res);res.json = (body: any) => {if (body && typeof body === "object" && !Array.isArray(body)) {+ // Copy: the research controllers log the same object after responding.const existing = Array.isArray(body.warnings) ? body.warnings : [];- body.warnings = [...existing, dep.message];- if (dep.replacement && body.replacement === undefined) {- body.replacement = dep.replacement;+ const annotated: any = {+ ...body,+ warnings: [...existing, dep.message],+ };+ if (dep.replacement && annotated.replacement === undefined) {+ annotated.replacement = dep.replacement;}+ return originalJson(annotated);}return originalJson(body);};diff --git a/apps/api/src/lib/research-keyless.ts b/apps/api/src/lib/research-keyless.tsindex 45ca7f6ea..43a2ebd51 100644--- a/apps/api/src/lib/research-keyless.ts+++ b/apps/api/src/lib/research-keyless.ts@@ -1,10 +1,15 @@import type { Request } from "express";-import { config, type ResearchPaperOperation } from "../config";+import { config, type ResearchKeylessOperation } from "../config";-function researchPaperOperation(req: Request): ResearchPaperOperation | null {+function researchKeylessOperation(+ req: Request,+): ResearchKeylessOperation | null {const segments = req.path.toLowerCase().split("/").filter(Boolean);const papersIndex = segments.indexOf("papers");- if (papersIndex === -1) return null;+ // Paper paths win, so a paper id of "github" is not the github route.+ if (papersIndex === -1) {+ return segments.includes("github") ? "github" : null;+ }const rest = segments.slice(papersIndex + 1);if (rest.length === 0) return "search";@@ -19,6 +24,6 @@ export function isResearchKeylessDisabled(req: Request): boolean {const disabledOperations = config.RESEARCH_KEYLESS_DISABLED;if (disabledOperations.length === 0) return false;- const operation = researchPaperOperation(req);+ const operation = researchKeylessOperation(req);return operation !== null && disabledOperations.includes(operation);}diff --git a/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs b/apps/dot-net-sdk/Firecrawl/FirecrawlClient.csindex 7bbaf6f5d..4e478c531 100644--- a/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs+++ b/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs@@ -551,6 +551,7 @@ public class FirecrawlClient/// <summary>/// Searches GitHub research content./// </summary>+ [Obsolete("Stops responding after 2026-11-03. Use the developer index at GET or POST /v2/search/developer; this SDK does not wrap it yet, so call it directly. It does not carry over the score breakdown or the web fallback results.")]public async Task<GitHubSearchResponse> SearchGitHubAsync(string query,SearchGitHubOptions? options = null,diff --git a/apps/elixir-sdk/generate.exs b/apps/elixir-sdk/generate.exsindex eb21afc26..959b825b9 100644--- a/apps/elixir-sdk/generate.exs+++ b/apps/elixir-sdk/generate.exs@@ -23,6 +23,10 @@ defmodule Firecrawl.Generator do"getHistoricalTokenUsage"])+ # The method key becomes the Req function name in generated code, a position+ # no escaping can protect, so anything else stops generation outright.+ @http_methods ~w(get post put patch delete head options)+def run doIO.puts("Fetching OpenAPI spec..."){:ok, spec} = fetch_spec()@@ -51,6 +55,14 @@ defmodule Firecrawl.Generator dodefp fetch_spec doApplication.ensure_all_started(:req)+ # Set FIRECRAWL_OPENAPI_SPEC to a local file to generate without the network.+ case System.get_env("FIRECRAWL_OPENAPI_SPEC") do+ nil -> fetch_remote_spec()+ path -> {:ok, path |> File.read!() |> Jason.decode!()}+ end+ end++ defp fetch_remote_spec docase Req.get(@openapi_url) do{:ok, %Req.Response{status: 200, body: body}} when is_map(body) ->{:ok, body}@@ -88,6 +100,10 @@ defmodule Firecrawl.Generator domethods|> Enum.reject(fn {key, _} -> key == "parameters" end)|> Enum.map(fn {method, operation} ->+ unless method in @http_methods do+ raise ArgumentError, "refusing unknown HTTP method #{inspect(method)} at #{inspect(path)}"+ end+{method, path, operation, path_level_params}end)end)@@ -107,7 +123,7 @@ defmodule Firecrawl.Generator dodefmodule Firecrawl do@moduledoc \"\"\"- Auto-generated Firecrawl API #{api_version} client.+ Auto-generated Firecrawl API #{escape_source_text(api_version)} client.Generated from the OpenAPI spec at:#{@openapi_url}@@ -144,7 +160,7 @@ defmodule Firecrawl.Generator do@type response :: {:ok, Req.Response.t()} | {:error, Exception.t() | Firecrawl.Error.t()}- @base_url "#{base_url}"+ @base_url #{inspect(base_url)}# Sourced from mix.exs at compile time so the origin header cannot drift# from the published package version.@version Mix.Project.config()[:version]@@ -349,6 +365,7 @@ defmodule Firecrawl.Generator do)# Build typespecs+ deprecated_code = build_deprecated(operation)spec_code = build_typespec(func_name, path_params, has_body || has_query_schema, false)bang_spec_code = build_typespec(func_name, path_params, has_body || has_query_schema, true)@@ -358,11 +375,13 @@ defmodule Firecrawl.Generator doquery_schema_code,query_key_mapping_code,doc,+ deprecated_code,spec_code," #{sig}",body,"",doc_bang(func_name),+ deprecated_code,bang_spec_code," #{bang_sig}",bang_body,@@ -434,6 +453,7 @@ defmodule Firecrawl.Generator do{sig, body} = build_multipart_function_body(func_name, method, path, meta, has_options?, false){bang_sig, bang_body} = build_multipart_function_body(func_name, method, path, meta, has_options?, true)+ deprecated_code = build_deprecated(operation)spec_code = build_multipart_typespec(func_name, has_options?, false)bang_spec_code = build_multipart_typespec(func_name, has_options?, true)@@ -441,11 +461,13 @@ defmodule Firecrawl.Generator dobody_schema_code,body_key_mapping_code,doc,+ deprecated_code,spec_code," #{sig}",body,"",doc_bang(func_name),+ deprecated_code,bang_spec_code," #{bang_sig}",bang_body,@@ -472,13 +494,13 @@ defmodule Firecrawl.Generator dooptions_part_text =cond dohas_options? and not is_nil(options_field) ->- "{\"#{options_field}\", Jason.encode!(to_body(params, @#{func_name}_key_mapping))}, "+ "{#{inspect(options_field)}, Jason.encode!(to_body(params, @#{func_name}_key_mapping))}, "true ->""end- file_part_text = "{\"#{file_field}\", file_part}"+ file_part_text = "{#{inspect(file_field)}, file_part}"indent = if not bang? and has_options?, do: " ", else: " "@@ -503,7 +525,7 @@ defmodule Firecrawl.Generator do"","#{indent}multipart = [#{options_part_text}#{file_part_text}]","",- "#{indent}Req.#{req_fn}(client(opts), url: \"#{path}\", form_multipart: multipart)"+ "#{indent}Req.#{req_fn}(client(opts), url: \"#{escape_string_literal(path)}\", form_multipart: multipart)"]core = Enum.join(core_lines, "\n")@@ -542,14 +564,14 @@ defmodule Firecrawl.Generator doparts = [" @doc \"\"\"",- " #{summary}",+ " #{escape_source_text(summary)}","",- " #{bt}#{http_method} #{path}#{bt}",+ " #{bt}#{escape_source_text(http_method)} #{escape_source_text(path)}#{bt}",""," Sends a #{bt}multipart/form-data#{bt} request."]- parts = if tag != "", do: parts ++ ["", " Tag: #{tag}"], else: parts+ parts = if tag != "", do: parts ++ ["", " Tag: #{escape_source_text(tag)}"], else: partsparts =parts ++@@ -572,7 +594,7 @@ defmodule Firecrawl.Generator do" ## Parameters",""," Validated by #{bt}NimbleOptions#{bt}. Pass options as a keyword list with snake_case keys.",- " These are JSON-encoded and sent as the #{bt}#{meta.options_field}#{bt} multipart field.",+ " These are JSON-encoded and sent as the #{bt}#{escape_source_text(meta.options_field)}#{bt} multipart field."," See #{bt}@#{func_name}_schema#{bt} for the full schema."]else@@ -685,7 +707,7 @@ defmodule Firecrawl.Generator doproperties|> Enum.map(fn {name, _} ->snake = to_snake_case(name)- "#{snake}: \"#{name}\""+ "#{snake}: #{inspect(name)}"end)|> Enum.join(", ")@@ -724,7 +746,7 @@ defmodule Firecrawl.Generator do|> Enum.map(fn param ->name = Map.get(param, "name")snake = to_snake_case(name)- "#{snake}: \"#{name}\""+ "#{snake}: #{inspect(name)}"end)|> Enum.join(", ")@@ -797,6 +819,40 @@ defmodule Firecrawl.Generator do# Doc Generation# ---------------------------------------------------------------------------+ # OpenAPI marks a retiring operation with `deprecated: true`. Elixir's+ # @deprecated turns that into a compiler warning at the caller.+ def build_deprecated(operation) do+ if Map.get(operation, "deprecated", false) do+ note =+ Map.get(operation, "x-deprecation-note") ||+ "Deprecated in the Firecrawl API. See the function docs for the replacement."++ " @deprecated #{inspect(to_string(note))}"+ end+ end++ # Spec text is fetched from the network and lands inside generated heredocs,+ # where Elixir would run #{} as code at compile time. Neutralise that, the+ # heredoc terminator, and stray backslashes.+ def escape_source_text(text) do+ text+ |> to_string()+ |> String.replace("\\", "\\\\")+ |> String.replace(~S(#{), ~S(\#{))+ |> String.replace(~S("""), ~S(\"\"\"))+ end++ # Same job for text that lands inside a generated "..." literal, where a+ # quote or #{} would end or execute it. Path templates keep their {param}+ # holes untouched so build_elixir_path can turn them into interpolations.+ def escape_string_literal(text) do+ text+ |> to_string()+ |> String.replace("\\", "\\\\")+ |> String.replace("\"", "\\\"")+ |> String.replace(~S(#{), ~S(\#{))+ end+defp build_doc(summary,http_method,@@ -812,18 +868,18 @@ defmodule Firecrawl.Generator doparts = [" @doc \"\"\"",- " #{summary}",+ " #{escape_source_text(summary)}","",- " #{bt}#{http_method} #{path}#{bt}"+ " #{bt}#{escape_source_text(http_method)} #{escape_source_text(path)}#{bt}"]- parts = if tag != "", do: parts ++ ["", " Tag: #{tag}"], else: parts+ parts = if tag != "", do: parts ++ ["", " Tag: #{escape_source_text(tag)}"], else: partsparts =if path_params != [] doparam_docs =Enum.map(path_params, fn p ->- " * #{bt}#{to_snake_case(p)}#{bt} - Path parameter #{bt}#{p}#{bt}"+ " * #{bt}#{to_snake_case(p)}#{bt} - Path parameter #{bt}#{escape_source_text(p)}#{bt}"end)parts ++ ["", " ## Path Parameters", ""] ++ param_docs@@ -849,7 +905,7 @@ defmodule Firecrawl.Generator doif has_query_schema doparam_docs =Enum.map(query_param_names, fn p ->- " * #{bt}#{to_snake_case(p)}#{bt} β query parameter #{bt}#{p}#{bt}"+ " * #{bt}#{to_snake_case(p)}#{bt} β query parameter #{bt}#{escape_source_text(p)}#{bt}"end)parts ++ ["", " ## Query Parameters", ""] ++ param_docs@@ -1018,10 +1074,10 @@ defmodule Firecrawl.Generator doendend- defp build_elixir_path(path, []), do: path+ defp build_elixir_path(path, []), do: escape_string_literal(path)defp build_elixir_path(path, path_params) do- Enum.reduce(path_params, path, fn param, acc ->+ Enum.reduce(path_params, escape_string_literal(path), fn param, acc ->snake = to_snake_case(param)String.replace(acc, "{#{param}}", "\#{#{snake}}")end)@@ -1036,7 +1092,7 @@ defmodule Firecrawl.Generator doif Regex.match?(~r/^[a-zA-Z_][a-zA-Z0-9_]*$/, value) do":#{value}"else- ":\"#{value}\""+ ":" <> inspect(to_string(value))endend@@ -1111,4 +1167,4 @@ defmodule Firecrawl.Generator doendend-Firecrawl.Generator.run()+unless Code.ensure_loaded?(Mix) and Mix.env() == :test, do: Firecrawl.Generator.run()diff --git a/apps/elixir-sdk/test/generator_test.exs b/apps/elixir-sdk/test/generator_test.exsnew file mode 100644index 000000000..e6018d8bd--- /dev/null+++ b/apps/elixir-sdk/test/generator_test.exs@@ -0,0 +1,162 @@+Code.require_file("../generate.exs", __DIR__)++defmodule Firecrawl.GeneratorTest do+ use ExUnit.Case, async: false+ import ExUnit.CaptureIO++ # The generator pulls the OpenAPI spec over the network and writes its text+ # into Elixir source. Anything that reaches a string literal or heredoc must+ # arrive as data, never as code that runs while the SDK compiles.+ @marker Path.join(System.tmp_dir!(), "firecrawl_generator_test_pwned")++ # No double quotes anywhere, so an escaper that only handles quotes leaves+ # the interpolation intact.+ @hostile "see \#{File.write!(~c'#{@marker}', ~c'x')} for details"++ setup do+ File.rm(@marker)+ on_exit(fn -> File.rm(@marker) end)+ :ok+ end++ defp compile_quietly(source) do+ capture_io(:stderr, fn -> Code.compile_string(source) end)+ end++ describe "build_deprecated/1" do+ test "emits nothing when the operation is not deprecated" do+ assert Firecrawl.Generator.build_deprecated(%{}) == nil+ assert Firecrawl.Generator.build_deprecated(%{"deprecated" => false}) == nil+ end++ test "falls back to a generic note" do+ line = Firecrawl.Generator.build_deprecated(%{"deprecated" => true})+ assert line =~ ~r/^ @deprecated "Deprecated in the Firecrawl API/+ end++ test "a hostile note is carried as data and cannot run at compile time" do+ line =+ Firecrawl.Generator.build_deprecated(%{+ "deprecated" => true,+ "x-deprecation-note" => @hostile+ })++ warnings =+ compile_quietly("""+ defmodule Firecrawl.GeneratorTest.Hostile do+ #{line}+ def f, do: :ok+ end++ defmodule Firecrawl.GeneratorTest.HostileCaller do+ def g, do: Firecrawl.GeneratorTest.Hostile.f()+ end+ """)++ refute File.exists?(@marker), "the note was evaluated while compiling"+ # The caller's deprecation warning must quote the note verbatim, which+ # proves it survived as a plain string rather than being interpreted.+ assert warnings =~ "is deprecated. " <> @hostile+ end++ test "quotes, backslashes and newlines cannot break out of the literal" do+ note = ~S(a "quoted" note with a \ backslash) <> "\nand a newline"++ line =+ Firecrawl.Generator.build_deprecated(%{+ "deprecated" => true,+ "x-deprecation-note" => note+ })++ warnings =+ compile_quietly("""+ defmodule Firecrawl.GeneratorTest.Escapes do+ #{line}+ def f, do: :ok+ end++ defmodule Firecrawl.GeneratorTest.EscapesCaller do+ def g, do: Firecrawl.GeneratorTest.Escapes.f()+ end+ """)++ assert warnings =~ "is deprecated. " <> note+ end+ end++ test "the hostile payload really is a live interpolation, not a reference to @marker" do+ assert String.contains?(@hostile, @marker)+ refute String.contains?(@hostile, "@marker")++ # Unescaped, it must fire, or none of the tests below prove anything.+ compile_quietly("""+ defmodule Firecrawl.GeneratorTest.Unescaped do+ @doc "#{@hostile}"+ def f, do: :ok+ end+ """)++ assert File.exists?(@marker)+ end++ describe "escape_string_literal/1" do+ test "leaves an ordinary path untouched" do+ assert Firecrawl.Generator.escape_string_literal("/search/research/papers/{id}") ==+ "/search/research/papers/{id}"+ end++ test "a hostile path inside a url literal cannot run or break out" do+ path = Firecrawl.Generator.escape_string_literal(~S(/x" <> ) <> @hostile <> ~S( <> "/y))++ [{mod, _}] =+ Code.compile_string("""+ defmodule Firecrawl.GeneratorTest.HostilePath do+ def url, do: "#{path}"+ end+ """)++ refute File.exists?(@marker), "the path was evaluated while compiling"+ assert mod.url() =~ "firecrawl_generator_test_pwned"+ end+ end++ describe "escape_source_text/1" do+ test "leaves ordinary spec text untouched" do+ assert Firecrawl.Generator.escape_source_text("Scrape a single URL") ==+ "Scrape a single URL"+ end++ test "a hostile summary inside a @doc heredoc cannot run at compile time" do+ summary = Firecrawl.Generator.escape_source_text(@hostile)++ compile_quietly("""+ defmodule Firecrawl.GeneratorTest.HostileDoc do+ @doc \"\"\"+ #{summary}+ \"\"\"+ def f, do: :ok+ end+ """)++ refute File.exists?(@marker), "the summary was evaluated while compiling"+ end++ test "a heredoc terminator in the summary does not end the docstring early" do+ summary =+ Firecrawl.Generator.escape_source_text(~S(ends the doc """ def injected, do: :owned))++ [{mod, _}] =+ Code.compile_string("""+ defmodule Firecrawl.GeneratorTest.Terminator do+ @doc \"\"\"+ #{summary}+ \"\"\"+ def f, do: :ok+ end+ """)++ refute function_exported?(mod, :injected, 0)+ assert function_exported?(mod, :f, 0)+ end+ end+enddiff --git a/apps/go-sdk/firecrawl.go b/apps/go-sdk/firecrawl.goindex b6dda544b..1f85d2ced 100644--- a/apps/go-sdk/firecrawl.go+++ b/apps/go-sdk/firecrawl.go@@ -672,6 +672,11 @@ func (c *Client) RelatedPapers(ctx context.Context, paperID, intent string, opts}// SearchGitHub searches GitHub research content.+//+// Deprecated: stops responding after 2026-11-03. Use the developer index at+// GET or POST /v2/search/developer. This SDK does not wrap it yet, so call it+// directly. It does not carry over the score breakdown or the web fallback+// results.func (c *Client) SearchGitHub(ctx context.Context, query string, opts *SearchGitHubOptions) (*GitHubSearchResponse, error) {if query == "" {return nil, &FirecrawlError{Message: "query is required"}diff --git a/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java b/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.javaindex a04498dc6..c6506a0c2 100644--- a/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java+++ b/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java@@ -602,10 +602,24 @@ public class FirecrawlClient {return http.get("/v2/search/research/papers/" + urlEncode(paperId) + "/similar" + researchQuery(params), ResearchModels.SimilarPapersResponse.class);}+ /**+ * @deprecated Stops responding after 2026-11-03. Use the developer index at+ * GET or POST /v2/search/developer, which this SDK does not wrap+ * yet, so call it directly. It does not carry over the score+ * breakdown or the web fallback results.+ */+ @Deprecatedpublic ResearchModels.GitHubSearchResponse searchGitHub(String query) {return searchGitHub(query, null);}+ /**+ * @deprecated Stops responding after 2026-11-03. Use the developer index at+ * GET or POST /v2/search/developer, which this SDK does not wrap+ * yet, so call it directly. It does not carry over the score+ * breakdown or the web fallback results.+ */+ @Deprecatedpublic ResearchModels.GitHubSearchResponse searchGitHub(String query, ResearchModels.SearchGitHubOptions options) {Objects.requireNonNull(query, "Query is required");Map<String, Object> params = new LinkedHashMap<>();@@ -1056,6 +1070,13 @@ public class FirecrawlClient {return CompletableFuture.supplyAsync(() -> relatedPapers(paperId, intent, options), asyncExecutor);}+ /**+ * @deprecated Stops responding after 2026-11-03. Use the developer index at+ * GET or POST /v2/search/developer, which this SDK does not wrap+ * yet, so call it directly. It does not carry over the score+ * breakdown or the web fallback results.+ */+ @Deprecatedpublic CompletableFuture<ResearchModels.GitHubSearchResponse> searchGitHubAsync(String query, ResearchModels.SearchGitHubOptions options) {return CompletableFuture.supplyAsync(() -> searchGitHub(query, options), asyncExecutor);}diff --git a/apps/js-sdk/firecrawl/README.md b/apps/js-sdk/firecrawl/README.mdindex a0b034a04..54ccc7f43 100644--- a/apps/js-sdk/firecrawl/README.md+++ b/apps/js-sdk/firecrawl/README.md@@ -261,8 +261,13 @@ const related = await app.research.similarPapers('pmid:<id>', {});```-A companion `app.research.searchGithub` searches indexed GitHub issue/PR history-and repository readmes.+> **`app.research.searchGithub` is deprecated.** The research index GitHub+> endpoint stops responding after 2026-11-03. Use `app.developerSearch`+> instead: it searches GitHub issues, pull requests and readmes plus curated+> documentation sources, returns matched passages, and adds filters for repo,+> language, license and stars. It does not carry over the `scores` breakdown+> or the `resultType: "web"` fallback results. See+> [the developer index docs](https://docs.firecrawl.dev/features/developer).### Scrape-bound interactive browsing (v2)diff --git a/apps/js-sdk/firecrawl/src/v2/client.ts b/apps/js-sdk/firecrawl/src/v2/client.tsindex 8c3091286..e6a85b64b 100644--- a/apps/js-sdk/firecrawl/src/v2/client.ts+++ b/apps/js-sdk/firecrawl/src/v2/client.ts@@ -285,6 +285,9 @@ export class FirecrawlClient {* Access the v2 research endpoints β Firecrawl's **research paper index*** (~43M paper abstracts) plus GitHub history/readmes.*+ * `research.searchGithub()` is deprecated and stops responding after+ * 2026-11-03. Use `developerSearch()` instead.+ ** The paper corpus is roughly 90% biomedical and life sciences β PubMed,* bioRxiv and medRxiv β with arXiv covering physics, mathematics and* computer science.diff --git a/apps/js-sdk/firecrawl/src/v2/methods/research.ts b/apps/js-sdk/firecrawl/src/v2/methods/research.tsindex a05d32249..5292b2997 100644--- a/apps/js-sdk/firecrawl/src/v2/methods/research.ts+++ b/apps/js-sdk/firecrawl/src/v2/methods/research.ts@@ -159,9 +159,9 @@ export class ResearchClient {appendParam(params, "query", options.query);appendParam(params, "k", options.k);try {- const res = await this.http.get<PaperMetadataResponse | ReadPaperResponse>(- withQuery(`${BASE}/papers/${encodeURIComponent(id)}`, params),- );+ const res = await this.http.get<+ PaperMetadataResponse | ReadPaperResponse+ >(withQuery(`${BASE}/papers/${encodeURIComponent(id)}`, params));if (res.status !== 200) throwForBadResponse(res, "get paper");return res.data;} catch (err) {@@ -191,10 +191,7 @@ export class ResearchClient {appendParam(params, "anchor", options.anchor);try {const res = await this.http.get<SimilarPapersResponse>(- withQuery(- `${BASE}/papers/${encodeURIComponent(id)}/similar`,- params,- ),+ withQuery(`${BASE}/papers/${encodeURIComponent(id)}/similar`, params),);if (res.status !== 200) throwForBadResponse(res, "find similar papers");return res.data;@@ -204,7 +201,16 @@ export class ResearchClient {}/**- * Search GitHub issue/PR history and repository readmes.+ * Search the research index GitHub slice: issue/PR history and repository+ * readmes.+ *+ * @deprecated Use `developerSearch()` on the client instead. This+ * endpoint stops responding after 2026-11-03. The developer index searches+ * GitHub issues, pull requests and readmes plus curated documentation+ * sources, returns matched passages, and adds filters for repo, language,+ * license and stars. It does not carry over the `scores` breakdown or the+ * `resultType: "web"` fallback results. See+ * https://docs.firecrawl.dev/features/developer.* @param query Search query.* @param options Optional `k`.*/diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.tsindex b6b750558..a7d16d490 100644--- a/apps/js-sdk/firecrawl/src/v2/types.ts+++ b/apps/js-sdk/firecrawl/src/v2/types.ts@@ -1917,7 +1917,14 @@ export interface SimilarPapersResponse {note?: string | null;}-/** Component scores; each field is present only when that signal contributed. */+/**+ * Component scores; each field is present only when that signal contributed.+ *+ * @deprecated Use the developer index instead. The research index GitHub+ * search stops responding after 2026-11-03. The developer index does not+ * expose a score breakdown. See+ * https://docs.firecrawl.dev/features/developer.+ */export interface GitHubScoreBreakdown {rrf?: number;semantic?: number;@@ -1926,6 +1933,11 @@ export interface GitHubScoreBreakdown {rerank?: number;}+/**+ * @deprecated Use the developer index instead. The research index GitHub+ * search stops responding after 2026-11-03. See+ * https://docs.firecrawl.dev/features/developer.+ */export interface GitHubSearchItem {resultType?: "github_history" | "repo_readme" | "web";/** `owner/name`; empty for web results whose URL is not a repo page. */@@ -1948,9 +1960,18 @@ export interface GitHubSearchItem {scores: GitHubScoreBreakdown;}+/**+ * @deprecated Use the developer index instead. The research index GitHub+ * search stops responding after 2026-11-03. See+ * https://docs.firecrawl.dev/features/developer.+ */export interface GitHubSearchResponse {success: boolean;results: GitHubSearchItem[];+ /** Deprecation notice while the sunset window is live. */+ warnings?: string[];+ /** Replacement endpoint path, while the sunset window is live. */+ replacement?: string;}/** Options for `research.searchPapers`. */@@ -1989,7 +2010,13 @@ export interface SimilarPapersOptions {anchor?: string[];}-/** Options for `research.searchGithub`. */+/**+ * Options for `research.searchGithub`.+ *+ * @deprecated Use the developer index instead. The research index GitHub+ * search stops responding after 2026-11-03. See+ * https://docs.firecrawl.dev/features/developer.+ */export interface SearchGithubOptions {/** Number of results to return (1β100, default 20). */k?: number;diff --git a/apps/php-sdk/src/Client/FirecrawlClient.php b/apps/php-sdk/src/Client/FirecrawlClient.phpindex 36a82a9b7..836f5dbcd 100644--- a/apps/php-sdk/src/Client/FirecrawlClient.php+++ b/apps/php-sdk/src/Client/FirecrawlClient.php@@ -181,6 +181,10 @@ final class FirecrawlClient/*** Search GitHub research content.*+ * @deprecated Stops responding after 2026-11-03. Use the developer index at+ * GET or POST /v2/search/developer, which this SDK does not wrap yet, so+ * call it directly. It does not carry over the score breakdown or the web+ * fallback results.* @param array<string, mixed> $options* @return array<string, mixed>*/diff --git a/apps/python-sdk/README.md b/apps/python-sdk/README.mdindex 91d9d4e4e..d3a2b40eb 100644--- a/apps/python-sdk/README.md+++ b/apps/python-sdk/README.md@@ -273,8 +273,13 @@ related = firecrawl.related_papers()```-A companion `search_github` searches indexed GitHub issue/PR history and repo-readmes.+> **`search_github` is deprecated.** The research index GitHub endpoint stops+> responding after 2026-11-03. Use `developer_search` instead: it searches+> GitHub issues, pull requests and readmes plus curated documentation sources,+> returns matched passages, and adds filters for repo, language, license and+> stars. It does not carry over the `scores` breakdown or the+> `resultType: "web"` fallback results. See+> [the developer index docs](https://docs.firecrawl.dev/features/developer).> **Response keys are camelCase.** Unlike the rest of the SDK, the research> methods return the raw JSON body as a `dict` β they are not parsed into typeddiff --git a/apps/python-sdk/firecrawl/v2/methods/aio/research.py b/apps/python-sdk/firecrawl/v2/methods/aio/research.pyindex e8725987a..33980e7be 100644--- a/apps/python-sdk/firecrawl/v2/methods/aio/research.py+++ b/apps/python-sdk/firecrawl/v2/methods/aio/research.py@@ -29,11 +29,13 @@ covering physics, mathematics and computer science.from typing import Any, Dict, List, Optionalfrom urllib.parse import quote+import warningsfrom ...utils import handle_response_errorfrom ...utils.http_client_async import AsyncHttpClientfrom ...utils.get_version import get_versionfrom ..research_docs import (+ GITHUB_SEARCH_DEPRECATION_MSG,AIO_INSPECT_PAPER_DOC,AIO_READ_PAPER_DOC,AIO_RELATED_PAPERS_DOC,@@ -152,6 +154,9 @@ async def search_github(*,k: Optional[int] = None,) -> Dict[str, Any]:+ # FutureWarning, not DeprecationWarning: the default filters hide the latter+ # outside __main__, and every entry point here is several SDK frames deep.+ warnings.warn(GITHUB_SEARCH_DEPRECATION_MSG, FutureWarning, stacklevel=2)return await _get(client,BASE + "/github" + _query({"query": query, "k": k, "origin": ORIGIN}),diff --git a/apps/python-sdk/firecrawl/v2/methods/research.py b/apps/python-sdk/firecrawl/v2/methods/research.pyindex 79d4d92cc..6bf51b8b4 100644--- a/apps/python-sdk/firecrawl/v2/methods/research.py+++ b/apps/python-sdk/firecrawl/v2/methods/research.py@@ -29,10 +29,12 @@ covering physics, mathematics and computer science.from typing import Any, Dict, List, Optionalfrom urllib.parse import quote+import warningsfrom ..utils import HttpClient, handle_response_errorfrom ..utils.get_version import get_versionfrom .research_docs import (+ GITHUB_SEARCH_DEPRECATION_MSG,INSPECT_PAPER_DOC,READ_PAPER_DOC,RELATED_PAPERS_DOC,@@ -151,6 +153,9 @@ def search_github(*,k: Optional[int] = None,) -> Dict[str, Any]:+ # FutureWarning, not DeprecationWarning: the default filters hide the latter+ # outside __main__, and every entry point here is several SDK frames deep.+ warnings.warn(GITHUB_SEARCH_DEPRECATION_MSG, FutureWarning, stacklevel=2)return _get(client,BASE + "/github" + _query({"query": query, "k": k, "origin": ORIGIN}),diff --git a/apps/python-sdk/firecrawl/v2/methods/research_docs.py b/apps/python-sdk/firecrawl/v2/methods/research_docs.pyindex 57a4d9c43..5d0d1c5fd 100644--- a/apps/python-sdk/firecrawl/v2/methods/research_docs.py+++ b/apps/python-sdk/firecrawl/v2/methods/research_docs.py@@ -55,6 +55,18 @@ _ASYNC_CLIENT_ARG = "client: Async HTTP client."# Implementation functions (``research.py`` / ``aio/research.py``)# ---------------------------------------------------------------------------+GITHUB_SEARCH_DEPRECATION_MSG = (+ "search_github() is deprecated and the research index GitHub endpoint "+ "stops responding after 2026-11-03. Use developer_search() instead: it "+ "searches GitHub issues, pull requests and READMEs plus curated "+ "documentation sources, returns matched passages, and adds filters for "+ "repo, language, license and stars. Response changes: 'snippet' becomes "+ "'passages', results gain an 'id', and there is no score breakdown and no "+ "web fallback result type. See "+ "https://docs.firecrawl.dev/features/developer."+)++_SEARCH_PAPERS_TEMPLATE = """Search the research paper index by abstract relevance.@@ -169,12 +181,21 @@ Note:"""_SEARCH_GITHUB_TEMPLATE = """-Search the developer index: GitHub issue/PR history and repository readmes.+Search the **research index** GitHub slice: GitHub issue/PR history and+repository readmes.++.. deprecated::+ Use ``developer_search()`` instead. This endpoint stops responding after+ 2026-11-03. The developer index searches GitHub issues, pull requests and+ readmes plus curated documentation sources, returns matched passages, and+ adds filters for repo, language, license and stars. It does **not** carry+ over the ``scores`` breakdown or the ``resultType: "web"`` fallback+ results. See https://docs.firecrawl.dev/features/developer.This is the code-and-discussion companion to ``search_papers`` and is served-by the same ``/v2/search/research`` surface. It searches indexed GitHub-history and readmes β it does **not** search the paper corpus, and it is not-the same as ``search(categories=["github"])`` (which is a ``site:github.com``+by the same ``/v2/search/research`` surface. It is a separate index from the+developer index, it does **not** search the paper corpus, and it is not the+same as ``search(categories=["github"])`` (which is a ``site:github.com``filter on ordinary web search).Args:@@ -185,7 +206,9 @@ Args:Returns:Raw API ``dict`` with ``success`` and ``results``. Keys are camelCase andare **not** normalized to snake_case β expect ``resultType``, ``repo``,- ``url``, ``pageType``, ``number`` and a ``scoreBreakdown`` object.+ ``url``, ``pageType``, ``number`` and a ``scores`` object. The response+ also carries a ``warnings`` list and a ``replacement`` field while the+ deprecation is live."""SEARCH_PAPERS_DOC = _SEARCH_PAPERS_TEMPLATE.replace(_CLIENT_ARG, _SYNC_CLIENT_ARG)@@ -287,12 +310,22 @@ Note:"""_CLIENT_SEARCH_GITHUB_TEMPLATE = """-Search the developer index: GitHub issue/PR history and repo readmes.+Search the **research index** GitHub slice: issue/PR history and repo+readmes.++.. deprecated::+ Use ``developer_search()`` instead. This endpoint stops responding+ after 2026-11-03. The developer index searches GitHub issues, pull+ requests and readmes plus curated documentation sources, and returns+ matched passages. It does **not** carry over the ``scores`` breakdown+ or the ``resultType: "web"`` fallback results. See+ https://docs.firecrawl.dev/features/developer.The code-and-discussion companion to ``search_papers``, served by the-same ``/v2/search/research`` surface. It does not search the paper-corpus, and it is not ``search(categories=["github"])`` (which is just a-``site:github.com`` filter on ordinary web search).+same ``/v2/search/research`` surface. A separate index from the developer+index. It does not search the paper corpus, and it is not+``search(categories=["github"])`` (which is just a ``site:github.com``+filter on ordinary web search).Args:query: Natural-language query, e.g. ``"pysam VCF parsing memory leak"``.diff --git a/apps/ruby-sdk/lib/firecrawl/client.rb b/apps/ruby-sdk/lib/firecrawl/client.rbindex 9182ae013..25b9b334d 100644--- a/apps/ruby-sdk/lib/firecrawl/client.rb+++ b/apps/ruby-sdk/lib/firecrawl/client.rb@@ -129,6 +129,10 @@ module Firecrawl# Search GitHub research content.#+ # @deprecated Stops responding after 2026-11-03. Use the developer index at+ # GET or POST /v2/search/developer, which this SDK does not wrap yet, so+ # call it directly. It does not carry over the score breakdown or the+ # web fallback results.# @param query_text [String] GitHub query# @param options [Hash] optional query parameters# @return [Hash]diff --git a/apps/rust-sdk/src/research.rs b/apps/rust-sdk/src/research.rsindex 232c523eb..a735edc65 100644--- a/apps/rust-sdk/src/research.rs+++ b/apps/rust-sdk/src/research.rs@@ -289,6 +289,11 @@ impl Client {self.handle_response(response, "related papers").await}+ /// Search the research index GitHub slice.+ ///+ /// Stops responding after 2026-11-03. Call `/v2/search/developer` directly;+ /// this SDK does not wrap it yet.+ #[deprecated(note = "Use the developer index at /v2/search/developer; sunset 2026-11-03")]pub async fn search_github(&self,query_text: impl AsRef<str>,