Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.cs
index 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.exs
index 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 do
IO.puts("Fetching OpenAPI spec...")
{:ok, spec} = fetch_spec()
@@ -51,6 +55,14 @@ defmodule Firecrawl.Generator do
defp fetch_spec do
Application.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 do
case 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 do
methods
|> 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 do
defmodule 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 do
query_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 do
body_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 do
options_part_text =
cond do
has_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 do
parts = [
" @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: parts
parts =
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 do
properties
|> 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 do
parts = [
" @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: parts
parts =
if path_params != [] do
param_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 do
if has_query_schema do
param_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 do
end
end
- 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 do
if Regex.match?(~r/^[a-zA-Z_][a-zA-Z0-9_]*$/, value) do
":#{value}"
else
- ":\"#{value}\""
+ ":" <> inspect(to_string(value))
end
end
@@ -1111,4 +1167,4 @@ defmodule Firecrawl.Generator do
end
end
-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.exs
new file mode 100644
index 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
+end
diff --git a/apps/go-sdk/firecrawl.go b/apps/go-sdk/firecrawl.go
index 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.java
index 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.
+ */
+ @Deprecated
public 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.
+ */
+ @Deprecated
public 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.
+ */
+ @Deprecated
public 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.md
index 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.ts
index 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.ts
index 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.ts
index 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.php
index 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.md
index 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 typed
diff --git a/apps/python-sdk/firecrawl/v2/methods/aio/research.py b/apps/python-sdk/firecrawl/v2/methods/aio/research.py
index 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, Optional
from urllib.parse import quote
+import warnings
from ...utils import handle_response_error
from ...utils.http_client_async import AsyncHttpClient
from ...utils.get_version import get_version
from ..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.py
index 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, Optional
from urllib.parse import quote
+import warnings
from ..utils import HttpClient, handle_response_error
from ..utils.get_version import get_version
from .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.py
index 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 and
are **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.rb
index 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.rs
index 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>,