Skip to content

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

fix(api): follow-ups to the GitHub search removal (#5570)

Kris Oeia666d87be901
diff --git a/apps/api/openapi.json b/apps/api/openapi.json
index 4d3a7220c..f387b8539 100644
--- a/apps/api/openapi.json
+++ b/apps/api/openapi.json
@@ -6102,10 +6102,10 @@
},
"example": {
"success": true,
+ "partial": false,
"results": [
{
"id": "issue:firecrawl/firecrawl#1234",
- "type": "issue",
"url": "https://github.com/firecrawl/firecrawl/issues/1234",
"title": "Retries are not applied to 429 responses",
"passages": [
@@ -6114,14 +6114,7 @@
}
]
}
- ],
- "coverage": {
- "doc": "ok",
- "issue": "ok",
- "pull_request": "ok",
- "readme": "ok"
- },
- "reranked": true
+ ]
}
}
}
@@ -11942,14 +11935,9 @@
"properties": {
"id": {
"type": "string",
- "description": "Stable result id, such as `issue:owner/repo#123`.",
+ "description": "Stable result id. Its prefix names the result kind, such as `issue:owner/repo#123` or `doc:<page URL>`.",
"example": "issue:firecrawl/firecrawl#1234"
},
- "type": {
- "type": "string",
- "enum": ["doc", "issue", "pull_request", "readme"],
- "description": "Result kind."
- },
"url": {
"type": "string",
"format": "uri"
@@ -11966,9 +11954,42 @@
"properties": {
"text": {
"type": "string"
+ },
+ "citation_url": {
+ "type": "string",
+ "format": "uri",
+ "description": "Link to the passage's own location, such as a section anchor, when it differs from the result `url`."
+ },
+ "truncated": {
+ "type": "boolean",
+ "description": "True when `text` omits part of the full passage. Absent when false."
+ },
+ "served_span": {
+ "type": "object",
+ "description": "Byte offsets of `text` within the full passage, present when `text` is one contiguous span.",
+ "required": ["start", "end"],
+ "properties": {
+ "start": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "end": {
+ "type": "integer",
+ "minimum": 0
+ }
+ }
+ },
+ "full_tokens_est": {
+ "type": "integer",
+ "minimum": 0,
+ "description": "Approximate token count of the full passage."
}
}
}
+ },
+ "license": {
+ "type": "string",
+ "description": "SPDX license id, verbatim, including `NOASSERTION`. Absent when the license is not known."
}
}
},
@@ -11978,38 +11999,16 @@
"success": {
"type": "boolean"
},
+ "partial": {
+ "type": "boolean",
+ "description": "True when the deadline passed before every best-effort stage finished, so the response holds the work completed by then."
+ },
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DeveloperSearchResult"
}
},
- "coverage": {
- "type": "object",
- "description": "Outcome for each result type. Check this when an expected result type is missing: `skipped` means your `types` value did not ask for that type, while `degraded` or `unavailable` means the gap came from the index or from a filter, not from the query. A repository filter is one such cause — see [how the repository filters scope a search](/api-reference/endpoint/developer-search#how-the-repository-filters-scope-a-search).",
- "properties": {
- "doc": {
- "type": "string",
- "enum": ["ok", "degraded", "unavailable", "skipped"]
- },
- "issue": {
- "type": "string",
- "enum": ["ok", "degraded", "unavailable", "skipped"]
- },
- "pull_request": {
- "type": "string",
- "enum": ["ok", "degraded", "unavailable", "skipped"]
- },
- "readme": {
- "type": "string",
- "enum": ["ok", "degraded", "unavailable", "skipped"]
- }
- }
- },
- "reranked": {
- "type": "boolean",
- "description": "Whether the ranked list went through the reranking stage."
- },
"repos": {
"type": "array",
"description": "Present only when `repos` was sent. Echoes each slug with whether it is indexed, plus a per-type breakdown under `types`.",
@@ -12019,6 +12018,10 @@
"repo": {
"type": "string"
},
+ "canonicalRepo": {
+ "type": "string",
+ "description": "The current indexed slug when `repo` is a superseded alias. Absent otherwise."
+ },
"indexed": {
"type": "boolean"
},
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
index 401a08f97..cd8f46046 100644
--- a/apps/api/src/__tests__/routes/research-github-deprecation.routes.test.ts
+++ b/apps/api/src/__tests__/routes/research-github-deprecation.routes.test.ts
@@ -86,7 +86,7 @@ describe.each([
replacement: "/v2/search/developer",
documentation_url: "https://docs.firecrawl.dev/features/developer",
});
- expect(res.body.error).toContain("removed after 2026-11-03");
+ expect(res.body.error).toContain("removed on 2026-11-03");
});
it("keeps the deprecation headers", async () => {
diff --git a/apps/api/src/controllers/v2/search.ts b/apps/api/src/controllers/v2/search.ts
index e8987d027..6f7e924eb 100644
--- a/apps/api/src/controllers/v2/search.ts
+++ b/apps/api/src/controllers/v2/search.ts
@@ -80,7 +80,7 @@ const RESEARCH_CATEGORY_NOTICE: Notice = {
};
const GITHUB_CATEGORY_REMOVED =
- "The 'github' search category was removed. To search GitHub issues, pull requests and READMEs, use the 'developer' category or GET or POST /v2/search/developer (https://docs.firecrawl.dev/features/developer). To keep web results from github.com, use includeDomains: [\"github.com\"].";
+ "The 'github' search category was removed. To search GitHub issues, pull requests and READMEs, send the 'developer' category on its own (it can't be combined with other categories), or call GET or POST /v2/search/developer (https://docs.firecrawl.dev/features/developer). To keep web results from github.com, use includeDomains: [\"github.com\"].";
// Ahead of auth and validation so rejected requests carry the notice too.
export function researchCategoryNoticeMiddleware(
@@ -176,7 +176,10 @@ async function searchControllerInner(
});
return res.status(400).json({
success: false,
+ code: "CATEGORY_REMOVED",
error: GITHUB_CATEGORY_REMOVED,
+ replacement: "developer",
+ documentation_url: "https://docs.firecrawl.dev/features/developer",
});
}
const sourcesOmitted =
diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.ts
index f65ce2c75..72787e4c5 100644
--- a/apps/api/src/controllers/v2/types.ts
+++ b/apps/api/src/controllers/v2/types.ts
@@ -1657,6 +1657,8 @@ export type ErrorResponse = {
details?: any;
sponsor_status?: string;
login_url?: string;
+ replacement?: string;
+ documentation_url?: string;
};
export type ScrapeResponse =
diff --git a/apps/api/src/lib/deprecations.ts b/apps/api/src/lib/deprecations.ts
index 16881a91c..f74a17553 100644
--- a/apps/api/src/lib/deprecations.ts
+++ b/apps/api/src/lib/deprecations.ts
@@ -46,7 +46,7 @@ const DEPRECATIONS = {
},
v2_research_github_search: {
message:
- "The research index GitHub search (GET /v2/search/research/github, legacy GET /v2/research/github) was removed after 2026-11-03. Send the same query and k to GET or POST /v2/search/developer instead. See https://docs.firecrawl.dev/features/developer.",
+ "The research index GitHub search (GET /v2/search/research/github, legacy GET /v2/research/github) was removed on 2026-11-03. Send the same query and k to GET or POST /v2/search/developer instead. See https://docs.firecrawl.dev/features/developer.",
replacement: "/v2/search/developer",
docs: "https://docs.firecrawl.dev/features/developer",
deprecatedAt: "@1788393600",
diff --git a/apps/api/src/lib/error-serde.ts b/apps/api/src/lib/error-serde.ts
index d76dea91e..31fb73971 100644
--- a/apps/api/src/lib/error-serde.ts
+++ b/apps/api/src/lib/error-serde.ts
@@ -105,6 +105,7 @@ const errorMap: Record<ErrorCodes, any> = {
// Zod errors
BAD_REQUEST: null,
BAD_REQUEST_INVALID_JSON: null,
+ CATEGORY_REMOVED: null,
INDEX_DAILY_LIMIT: null,
TOOL_DISCOVERY_UNAVAILABLE: null,
PARSE_UNSUPPORTED_OPTIONS: null,
diff --git a/apps/api/src/lib/error.ts b/apps/api/src/lib/error.ts
index fa4c991bc..f3952e70b 100644
--- a/apps/api/src/lib/error.ts
+++ b/apps/api/src/lib/error.ts
@@ -50,6 +50,7 @@ export type ErrorCodes =
| "MAP_FAILED"
| "BAD_REQUEST_INVALID_JSON"
| "BAD_REQUEST"
+ | "CATEGORY_REMOVED"
| "CONCURRENCY_QUEUE_TIMEOUT"
| "SAFE_MODE_BLOCKED"
| "SCRAPE_SITE_RESTRICTION_BLOCKED"
diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.ts
index 771d472db..e38ec9184 100644
--- a/apps/api/src/routes/v2.ts
+++ b/apps/api/src/routes/v2.ts
@@ -735,13 +735,13 @@ v2Router.post(
wrap(supportProxyController),
);
-if (config.RESEARCH_PROXY_URL) {
- // Register before the /search/research and /research mounts so the 410 answers ahead of their auth.
- v2Router.get(
- ["/search/research/github", "/research/github"],
- removedEndpointHandler("v2_research_github_search"),
- );
+// Outside the research proxy check so the 410 outlives the backend, and ahead of the research mounts' auth.
+v2Router.get(
+ ["/search/research/github", "/research/github"],
+ removedEndpointHandler("v2_research_github_search"),
+);
+if (config.RESEARCH_PROXY_URL) {
v2Router.use(
"/search/research",
authMiddleware(RateLimiterMode.Research, {