firecrawl 4.31.1 → 4.32.1

package/README.md

@@ -166,6 +166,73 @@ const mapResult = await app.map('https://example.com');
 console.log(mapResult);
 ```
 
+### Search
+
+Use `search` to search the web and optionally scrape the results in the same call.
+
+```js
+const results = await app.search('what is retrieval augmented generation?', { limit: 5 });
+for (const result of results.web ?? []) {
+  console.log(result.url, '-', result.title);
+}
+
+// Scrape every result as part of the search:
+const scraped = await app.search('firecrawl changelog', {
+  limit: 3,
+  scrapeOptions: { formats: ['markdown'] },
+});
+```
+
+Results are grouped by source: `.web`, `.news`, `.images` and `.developer`.
+
+Use `categories` to narrow web search to a kind of site:
+
+```js
+const results = await app.search('nanopore basecalling accuracy', {
+  categories: ['research'],
+});
+```
+
+> **`categories: ['research']` is a website filter, not the paper index.** It
+> restricts ordinary web search to roughly 14 academic domains (arxiv.org,
+> pubmed.ncbi.nlm.nih.gov, nature.com, biorxiv.org, ...) and returns web page
+> results. To search papers themselves, use `research.searchPapers` below.
+
+### Research / paper search
+
+Use `app.research` to search Firecrawl's research paper index: ~43M paper
+abstracts, roughly 90% biomedical and life sciences (PubMed, bioRxiv, medRxiv),
+plus arXiv for physics, mathematics and computer science.
+
+```js
+// Search the paper index (semantic search over abstracts):
+const papers = await app.research.searchPapers(
+  'CRISPR base editing off-target effects in primary human T cells',
+  { k: 10 },
+);
+for (const paper of papers.results) {
+  console.log(paper.primaryId, '-', paper.title);
+}
+
+// Inspect one paper's metadata (accepts pmid:, pmcid:, doi: or arxiv: ids):
+const paper = await app.research.getPaper('pmid:<id>');
+
+// Read the passages inside a paper that answer a specific question:
+const read = await app.research.getPaper('pmid:<id>', {
+  query: 'what was the primary endpoint and the reported hazard ratio?',
+  k: 4,
+});
+
+// Expand along the citation graph, re-ranked for your stated intent:
+const related = await app.research.similarPapers('pmid:<id>', {
+  intent: 'replication attempts in larger cohorts',
+  k: 20,
+});
+```
+
+A companion `app.research.searchGithub` searches indexed GitHub issue/PR history
+and repository readmes.
+
 ### Scrape-bound interactive browsing (v2)
 
 Use a scrape job ID to keep interacting with the replayed browser context:

package/dist/{chunk-BEF2NAMB.js → chunk-S7CQ7Q2W.js}

@@ -12,8 +12,8 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.31.1",
-      description: "JavaScript SDK for Firecrawl API",
+      version: "4.32.1",
+      description: "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
       main: "dist/index.js",
       types: "dist/index.d.ts",
       exports: {
@@ -69,7 +69,21 @@ var require_package = __commonJS({
         "web",
         "scraper",
         "api",
-        "sdk"
+        "sdk",
+        "web-search",
+        "literature-search",
+        "research",
+        "scientific-papers",
+        "academic-search",
+        "biomedical",
+        "life-sciences",
+        "pubmed",
+        "biorxiv",
+        "medrxiv",
+        "arxiv",
+        "preprints",
+        "citations",
+        "bioinformatics"
       ],
       engines: {
         node: ">=22.0.0"

package/dist/index.cjs

@@ -39,8 +39,8 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.31.1",
-      description: "JavaScript SDK for Firecrawl API",
+      version: "4.32.1",
+      description: "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
       main: "dist/index.js",
       types: "dist/index.d.ts",
       exports: {
@@ -96,7 +96,21 @@ var require_package = __commonJS({
         "web",
         "scraper",
         "api",
-        "sdk"
+        "sdk",
+        "web-search",
+        "literature-search",
+        "research",
+        "scientific-papers",
+        "academic-search",
+        "biomedical",
+        "life-sciences",
+        "pubmed",
+        "biorxiv",
+        "medrxiv",
+        "arxiv",
+        "preprints",
+        "citations",
+        "bioinformatics"
       ],
       engines: {
         node: ">=22.0.0"
@@ -746,12 +760,16 @@ async function search(http, request) {
     if (data.news) out.news = transformArray(data.news);
     if (data.images)
       out.images = transformArray(data.images);
+    if (data.developer)
+      out.developer = transformArray(data.developer);
     Object.defineProperty(out, "data", {
       get() {
         const parts = [];
         if (out.web?.length) parts.push(`.web (${out.web.length} results)`);
         if (out.news?.length) parts.push(`.news (${out.news.length} results)`);
         if (out.images?.length) parts.push(`.images (${out.images.length} results)`);
+        if (out.developer?.length)
+          parts.push(`.developer (${out.developer.length} results)`);
         const available = parts.length ? parts.join(", ") : ".web, .news, or .images";
         throw new Error(
           `SearchData has no '.data'. Results are grouped by source: ${available}`
@@ -1515,9 +1533,20 @@ var ResearchClient = class {
   }
   http;
   /**
-   * Search papers by abstract relevance.
-   * @param query Natural-language search query.
-   * @param options Optional filters (k, authors, categories, from, to).
+   * Search the research paper index by abstract relevance.
+   *
+   * Queries ~43M paper abstracts: PubMed, bioRxiv and medRxiv (about 90% of the
+   * corpus — biomedical and life sciences) plus arXiv (physics, mathematics,
+   * computer science). Semantic search over abstracts, not keyword matching.
+   *
+   * This is **not** `search({ categories: ["research"] })`, which only narrows
+   * ordinary web search to ~14 academic websites.
+   *
+   * @param query Natural-language search query, e.g. `"CRISPR base editing
+   *   off-target effects in primary human T cells"`.
+   * @param options Optional filters (k, authors, categories, from, to). Note
+   *   `categories` here filters *paper* subject categories (e.g. `"q-bio.GN"`)
+   *   and is unrelated to the `categories` option of `search()`.
    */
   async searchPapers(query, options = {}) {
     if (!query || !query.trim()) throw new Error("query cannot be empty");
@@ -2067,8 +2096,19 @@ var FirecrawlClient = class {
   }
   // Research
   /**
-   * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).
-   * Example: `firecrawl.research.searchPapers("diffusion models")`.
+   * Access the v2 research endpoints — Firecrawl's **research paper index**
+   * (~43M paper abstracts) plus GitHub history/readmes.
+   *
+   * The paper corpus is roughly 90% biomedical and life sciences — PubMed,
+   * bioRxiv and medRxiv — with arXiv covering physics, mathematics and
+   * computer science.
+   *
+   * ⚠️ Not the same as `search({ categories: ["research"] })`, which is only a
+   * website/domain filter over ordinary web search (~14 academic domains,
+   * returning page snippets). Use `research.searchPapers()` for literature
+   * search.
+   *
+   * Example: `firecrawl.research.searchPapers("GLP-1 receptor agonists cardiovascular outcomes")`.
    */
   get research() {
     if (!this._research) this._research = new ResearchClient(this.http);
@@ -3259,7 +3299,7 @@ var FirecrawlApp = class {
    * @param onActivity - Optional callback to receive activity updates in real-time.
    * @param onSource - Optional callback to receive source updates in real-time.
    * @returns The final research results.
-   * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+   * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
    */
   async deepResearch(query, params, onActivity, onSource) {
     try {
@@ -3316,7 +3356,7 @@ var FirecrawlApp = class {
    * Initiates a deep research operation on a given query without polling.
    * @param params - Parameters for the deep research operation.
    * @returns The response containing the research job ID.
-   * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+   * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
    */
   async asyncDeepResearch(query, params) {
     const headers = this.prepareHeaders();
@@ -3354,7 +3394,7 @@ var FirecrawlApp = class {
    * Checks the status of a deep research operation.
    * @param id - The ID of the deep research operation.
    * @returns The current status and results of the research operation.
-   * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+   * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
    */
   async checkDeepResearchStatus(id) {
     const headers = this.prepareHeaders();

package/dist/index.d.cts

@@ -139,6 +139,10 @@ interface ScrapeOptions {
     useMock?: string;
     blockAds?: boolean;
     proxy?: "basic" | "stealth" | "enhanced" | "auto" | string;
+    /**
+     * Maximum age, in milliseconds, of indexed content that may be reused.
+     * Set to `0` to bypass index reuse.
+     */
     maxAge?: number;
     minAge?: number;
     storeInCache?: boolean;
@@ -423,6 +427,7 @@ interface MenuProfile {
 interface DocumentMetadata {
     title?: string;
     description?: string;
+    /** URL reported by the selected scrape engine. */
     url?: string;
     language?: string;
     keywords?: string | string[];
@@ -452,7 +457,9 @@ interface DocumentMetadata {
     publishedTime?: string;
     articleTag?: string;
     articleSection?: string;
+    /** URL requested for the scrape. */
     sourceURL?: string;
+    /** HTTP status code reported for the scrape response. */
     statusCode?: number;
     scrapeId?: string;
     numPages?: number;
@@ -508,6 +515,7 @@ interface SearchResultWeb {
     url: string;
     title?: string;
     description?: string;
+    position?: number;
     category?: string;
 }
 interface SearchResultNews {
@@ -531,16 +539,47 @@ interface SearchData {
     web?: Array<SearchResultWeb | Document>;
     news?: Array<SearchResultNews | Document>;
     images?: Array<SearchResultImages | Document>;
+    developer?: Array<SearchResultWeb | Document>;
 }
+/**
+ * Narrows ordinary **web search**. A category does not switch `search()` to a
+ * different index.
+ *
+ * - `github` — restrict web results to github.com (a `site:` filter).
+ * - `research` — restrict web results to a fixed list of ~14 academic
+ *   *websites* (arxiv.org, pubmed.ncbi.nlm.nih.gov, nature.com, science.org,
+ *   ieee.org, sciencedirect.com, biorxiv.org, medrxiv.org, ...). It returns
+ *   ordinary web page results from those domains, **not** paper records.
+ * - `pdf` — restrict results to PDFs (adds `filetype:pdf`).
+ * - `developer` — add developer results (issues, pull requests, READMEs and
+ *   documentation) under `.developer`.
+ *
+ * ⚠️ `categories: ["research"]` is **not** Firecrawl's research paper index.
+ * To search papers themselves — ~43M abstracts, roughly 90% biomedical
+ * (PubMed, bioRxiv, medRxiv) plus arXiv — with full abstracts, in-body passage
+ * reads and citation-graph expansion, use `firecrawl.research.searchPapers()`
+ * (plus `getPaper()` and `similarPapers()`), which call `/v2/search/research`.
+ *
+ * Rule of thumb: literature search → `research.searchPapers()`; web pages that
+ * happen to live on academic domains → `search({ categories: ["research"] })`.
+ */
 interface CategoryOption {
-    type: "github" | "research" | "pdf";
+    type: "github" | "research" | "pdf" | "developer";
 }
 interface SearchRequest {
     query: string;
     sources?: Array<"web" | "news" | "images" | {
         type: "web" | "news" | "images";
     }>;
-    categories?: Array<"github" | "research" | "pdf" | CategoryOption>;
+    /**
+     * Narrow web search by category. See {@link CategoryOption}.
+     *
+     * ⚠️ `"research"` is a website/domain filter over ordinary web search (~14
+     * academic domains), **not** the research paper index. For literature search
+     * over ~43M paper abstracts (PubMed / bioRxiv / medRxiv / arXiv) use
+     * `firecrawl.research.searchPapers()` instead.
+     */
+    categories?: Array<"github" | "research" | "pdf" | "developer" | CategoryOption>;
     includeDomains?: string[];
     excludeDomains?: string[];
     limit?: number;
@@ -1086,8 +1125,20 @@ interface BrowserListResponse {
     error?: string;
 }
 /**
- * Source identifiers grouped by namespace. Currently only `arxiv` is
- * populated; each value is an array of ids in that namespace.
+ * Source identifiers grouped by namespace. Each key is a namespace and each
+ * value is an array of ids in that namespace.
+ *
+ * Which namespaces appear depends on the paper's source. Biomedical records
+ * (PubMed, bioRxiv, medRxiv) typically carry `pmid`, `pmcid` and/or `doi`;
+ * arXiv records carry `arxiv`. The set is open — treat this as a lookup by
+ * namespace rather than a fixed schema, and prefer {@link PaperResult.primaryId}
+ * when you just need one citable identifier.
+ *
+ * @example
+ * ```ts
+ * const doi = paper.ids?.doi?.[0];
+ * const pmid = paper.ids?.pmid?.[0];
+ * ```
  */
 type IdMap = Record<string, string[]>;
 /** Per-candidate ranking signals (present on similarity results). */
@@ -1101,7 +1152,7 @@ interface PaperSignals {
     /** Number of distinct seeds connected to this candidate. */
     seedOverlap: number;
 }
-/** A ranked paper. `paperId` is canonical; arXiv lives in `ids`. */
+/** A ranked paper. `paperId` is canonical; source ids (pmid, pmcid, doi, arxiv, ...) live in `ids`. */
 interface PaperResult {
     /** Canonical paper id — the Milvus INT64 primary key as a decimal string. */
     paperId: string;
@@ -1173,7 +1224,7 @@ interface GitHubScoreBreakdown {
     rerank?: number;
 }
 interface GitHubSearchItem {
-    resultType: "github_history" | "repo_readme" | "web";
+    resultType?: "github_history" | "repo_readme" | "web";
     /** `owner/name`; empty for web results whose URL is not a repo page. */
     repo: string;
     url: string;
@@ -1324,23 +1375,55 @@ declare function listBrowsers(http: HttpClient, args?: {
 }): Promise<BrowserListResponse>;
 
 /**
- * Client for the v2 research endpoints (arXiv papers + GitHub history/readmes).
+ * Client for the v2 research endpoints — Firecrawl's **research paper index**
+ * (~43M paper abstracts) plus GitHub history/readmes.
+ *
+ * The paper corpus is roughly 90% biomedical and life sciences — PubMed,
+ * bioRxiv and medRxiv — with arXiv covering physics, mathematics and computer
+ * science. Supports abstract search, paper metadata, in-body passage reads and
+ * citation-graph expansion.
+ *
+ * ⚠️ This is **not** the same as `search({ categories: ["research"] })`. That
+ * option is a website/domain filter on ordinary web search: it narrows
+ * Google-style results to ~14 academic domains and returns page snippets. The
+ * methods here query the paper index itself and return ranked paper records.
+ *
  * Accessed via `firecrawl.research`.
+ *
+ * @example
+ * ```ts
+ * const res = await firecrawl.research.searchPapers(
+ *   "tau aggregation inhibitors in Alzheimer's disease",
+ *   { k: 10 },
+ * );
+ * ```
  */
 declare class ResearchClient {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Search papers by abstract relevance.
-     * @param query Natural-language search query.
-     * @param options Optional filters (k, authors, categories, from, to).
+     * Search the research paper index by abstract relevance.
+     *
+     * Queries ~43M paper abstracts: PubMed, bioRxiv and medRxiv (about 90% of the
+     * corpus — biomedical and life sciences) plus arXiv (physics, mathematics,
+     * computer science). Semantic search over abstracts, not keyword matching.
+     *
+     * This is **not** `search({ categories: ["research"] })`, which only narrows
+     * ordinary web search to ~14 academic websites.
+     *
+     * @param query Natural-language search query, e.g. `"CRISPR base editing
+     *   off-target effects in primary human T cells"`.
+     * @param options Optional filters (k, authors, categories, from, to). Note
+     *   `categories` here filters *paper* subject categories (e.g. `"q-bio.GN"`)
+     *   and is unrelated to the `categories` option of `search()`.
      */
     searchPapers(query: string, options?: SearchPapersOptions): Promise<SearchPapersResponse>;
     /**
      * Get paper metadata (detail mode), or read in-body passages (when `query` is
      * supplied). `k` is only valid together with `query`.
-     * @param id Paper reference: a canonical `paper_id`, an `arxiv:<id>` key, or a
-     *   bare arXiv id / URL.
+     * @param id Paper reference: a canonical `paperId`, or a namespaced id key
+     *   such as `pmid:<id>`, `pmcid:<id>`, `doi:<doi>` or `arxiv:<id>`. Bare
+     *   arXiv ids and arXiv URLs are also accepted.
      * @param options Optional `query` (switches to read mode) and `k`.
      */
     getPaper(id: string, options?: {
@@ -1495,8 +1578,19 @@ declare class FirecrawlClient {
      */
     searchFeedback(jobId: string, request: SearchFeedbackRequest): Promise<FeedbackResponse>;
     /**
-     * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).
-     * Example: `firecrawl.research.searchPapers("diffusion models")`.
+     * Access the v2 research endpoints — Firecrawl's **research paper index**
+     * (~43M paper abstracts) plus GitHub history/readmes.
+     *
+     * The paper corpus is roughly 90% biomedical and life sciences — PubMed,
+     * bioRxiv and medRxiv — with arXiv covering physics, mathematics and
+     * computer science.
+     *
+     * ⚠️ Not the same as `search({ categories: ["research"] })`, which is only a
+     * website/domain filter over ordinary web search (~14 academic domains,
+     * returning page snippets). Use `research.searchPapers()` for literature
+     * search.
+     *
+     * Example: `firecrawl.research.searchPapers("GLP-1 receptor agonists cardiovascular outcomes")`.
      */
     get research(): ResearchClient;
     /**
@@ -2525,7 +2619,7 @@ declare class FirecrawlApp {
      * @param onActivity - Optional callback to receive activity updates in real-time.
      * @param onSource - Optional callback to receive source updates in real-time.
      * @returns The final research results.
-     * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+     * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
      */
     deepResearch(query: string, params: DeepResearchParams<zt.ZodSchema>, onActivity?: (activity: {
         type: string;
@@ -2543,14 +2637,14 @@ declare class FirecrawlApp {
      * Initiates a deep research operation on a given query without polling.
      * @param params - Parameters for the deep research operation.
      * @returns The response containing the research job ID.
-     * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+     * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
      */
     asyncDeepResearch(query: string, params: DeepResearchParams<zt.ZodSchema>): Promise<DeepResearchResponse | ErrorResponse>;
     /**
      * Checks the status of a deep research operation.
      * @param id - The ID of the deep research operation.
      * @returns The current status and results of the research operation.
-     * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+     * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
      */
     checkDeepResearchStatus(id: string): Promise<DeepResearchStatusResponse | ErrorResponse>;
     /**

package/dist/index.d.ts

@@ -139,6 +139,10 @@ interface ScrapeOptions {
     useMock?: string;
     blockAds?: boolean;
     proxy?: "basic" | "stealth" | "enhanced" | "auto" | string;
+    /**
+     * Maximum age, in milliseconds, of indexed content that may be reused.
+     * Set to `0` to bypass index reuse.
+     */
     maxAge?: number;
     minAge?: number;
     storeInCache?: boolean;
@@ -423,6 +427,7 @@ interface MenuProfile {
 interface DocumentMetadata {
     title?: string;
     description?: string;
+    /** URL reported by the selected scrape engine. */
     url?: string;
     language?: string;
     keywords?: string | string[];
@@ -452,7 +457,9 @@ interface DocumentMetadata {
     publishedTime?: string;
     articleTag?: string;
     articleSection?: string;
+    /** URL requested for the scrape. */
     sourceURL?: string;
+    /** HTTP status code reported for the scrape response. */
     statusCode?: number;
     scrapeId?: string;
     numPages?: number;
@@ -508,6 +515,7 @@ interface SearchResultWeb {
     url: string;
     title?: string;
     description?: string;
+    position?: number;
     category?: string;
 }
 interface SearchResultNews {
@@ -531,16 +539,47 @@ interface SearchData {
     web?: Array<SearchResultWeb | Document>;
     news?: Array<SearchResultNews | Document>;
     images?: Array<SearchResultImages | Document>;
+    developer?: Array<SearchResultWeb | Document>;
 }
+/**
+ * Narrows ordinary **web search**. A category does not switch `search()` to a
+ * different index.
+ *
+ * - `github` — restrict web results to github.com (a `site:` filter).
+ * - `research` — restrict web results to a fixed list of ~14 academic
+ *   *websites* (arxiv.org, pubmed.ncbi.nlm.nih.gov, nature.com, science.org,
+ *   ieee.org, sciencedirect.com, biorxiv.org, medrxiv.org, ...). It returns
+ *   ordinary web page results from those domains, **not** paper records.
+ * - `pdf` — restrict results to PDFs (adds `filetype:pdf`).
+ * - `developer` — add developer results (issues, pull requests, READMEs and
+ *   documentation) under `.developer`.
+ *
+ * ⚠️ `categories: ["research"]` is **not** Firecrawl's research paper index.
+ * To search papers themselves — ~43M abstracts, roughly 90% biomedical
+ * (PubMed, bioRxiv, medRxiv) plus arXiv — with full abstracts, in-body passage
+ * reads and citation-graph expansion, use `firecrawl.research.searchPapers()`
+ * (plus `getPaper()` and `similarPapers()`), which call `/v2/search/research`.
+ *
+ * Rule of thumb: literature search → `research.searchPapers()`; web pages that
+ * happen to live on academic domains → `search({ categories: ["research"] })`.
+ */
 interface CategoryOption {
-    type: "github" | "research" | "pdf";
+    type: "github" | "research" | "pdf" | "developer";
 }
 interface SearchRequest {
     query: string;
     sources?: Array<"web" | "news" | "images" | {
         type: "web" | "news" | "images";
     }>;
-    categories?: Array<"github" | "research" | "pdf" | CategoryOption>;
+    /**
+     * Narrow web search by category. See {@link CategoryOption}.
+     *
+     * ⚠️ `"research"` is a website/domain filter over ordinary web search (~14
+     * academic domains), **not** the research paper index. For literature search
+     * over ~43M paper abstracts (PubMed / bioRxiv / medRxiv / arXiv) use
+     * `firecrawl.research.searchPapers()` instead.
+     */
+    categories?: Array<"github" | "research" | "pdf" | "developer" | CategoryOption>;
     includeDomains?: string[];
     excludeDomains?: string[];
     limit?: number;
@@ -1086,8 +1125,20 @@ interface BrowserListResponse {
     error?: string;
 }
 /**
- * Source identifiers grouped by namespace. Currently only `arxiv` is
- * populated; each value is an array of ids in that namespace.
+ * Source identifiers grouped by namespace. Each key is a namespace and each
+ * value is an array of ids in that namespace.
+ *
+ * Which namespaces appear depends on the paper's source. Biomedical records
+ * (PubMed, bioRxiv, medRxiv) typically carry `pmid`, `pmcid` and/or `doi`;
+ * arXiv records carry `arxiv`. The set is open — treat this as a lookup by
+ * namespace rather than a fixed schema, and prefer {@link PaperResult.primaryId}
+ * when you just need one citable identifier.
+ *
+ * @example
+ * ```ts
+ * const doi = paper.ids?.doi?.[0];
+ * const pmid = paper.ids?.pmid?.[0];
+ * ```
  */
 type IdMap = Record<string, string[]>;
 /** Per-candidate ranking signals (present on similarity results). */
@@ -1101,7 +1152,7 @@ interface PaperSignals {
     /** Number of distinct seeds connected to this candidate. */
     seedOverlap: number;
 }
-/** A ranked paper. `paperId` is canonical; arXiv lives in `ids`. */
+/** A ranked paper. `paperId` is canonical; source ids (pmid, pmcid, doi, arxiv, ...) live in `ids`. */
 interface PaperResult {
     /** Canonical paper id — the Milvus INT64 primary key as a decimal string. */
     paperId: string;
@@ -1173,7 +1224,7 @@ interface GitHubScoreBreakdown {
     rerank?: number;
 }
 interface GitHubSearchItem {
-    resultType: "github_history" | "repo_readme" | "web";
+    resultType?: "github_history" | "repo_readme" | "web";
     /** `owner/name`; empty for web results whose URL is not a repo page. */
     repo: string;
     url: string;
@@ -1324,23 +1375,55 @@ declare function listBrowsers(http: HttpClient, args?: {
 }): Promise<BrowserListResponse>;
 
 /**
- * Client for the v2 research endpoints (arXiv papers + GitHub history/readmes).
+ * Client for the v2 research endpoints — Firecrawl's **research paper index**
+ * (~43M paper abstracts) plus GitHub history/readmes.
+ *
+ * The paper corpus is roughly 90% biomedical and life sciences — PubMed,
+ * bioRxiv and medRxiv — with arXiv covering physics, mathematics and computer
+ * science. Supports abstract search, paper metadata, in-body passage reads and
+ * citation-graph expansion.
+ *
+ * ⚠️ This is **not** the same as `search({ categories: ["research"] })`. That
+ * option is a website/domain filter on ordinary web search: it narrows
+ * Google-style results to ~14 academic domains and returns page snippets. The
+ * methods here query the paper index itself and return ranked paper records.
+ *
  * Accessed via `firecrawl.research`.
+ *
+ * @example
+ * ```ts
+ * const res = await firecrawl.research.searchPapers(
+ *   "tau aggregation inhibitors in Alzheimer's disease",
+ *   { k: 10 },
+ * );
+ * ```
  */
 declare class ResearchClient {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * Search papers by abstract relevance.
-     * @param query Natural-language search query.
-     * @param options Optional filters (k, authors, categories, from, to).
+     * Search the research paper index by abstract relevance.
+     *
+     * Queries ~43M paper abstracts: PubMed, bioRxiv and medRxiv (about 90% of the
+     * corpus — biomedical and life sciences) plus arXiv (physics, mathematics,
+     * computer science). Semantic search over abstracts, not keyword matching.
+     *
+     * This is **not** `search({ categories: ["research"] })`, which only narrows
+     * ordinary web search to ~14 academic websites.
+     *
+     * @param query Natural-language search query, e.g. `"CRISPR base editing
+     *   off-target effects in primary human T cells"`.
+     * @param options Optional filters (k, authors, categories, from, to). Note
+     *   `categories` here filters *paper* subject categories (e.g. `"q-bio.GN"`)
+     *   and is unrelated to the `categories` option of `search()`.
      */
     searchPapers(query: string, options?: SearchPapersOptions): Promise<SearchPapersResponse>;
     /**
      * Get paper metadata (detail mode), or read in-body passages (when `query` is
      * supplied). `k` is only valid together with `query`.
-     * @param id Paper reference: a canonical `paper_id`, an `arxiv:<id>` key, or a
-     *   bare arXiv id / URL.
+     * @param id Paper reference: a canonical `paperId`, or a namespaced id key
+     *   such as `pmid:<id>`, `pmcid:<id>`, `doi:<doi>` or `arxiv:<id>`. Bare
+     *   arXiv ids and arXiv URLs are also accepted.
      * @param options Optional `query` (switches to read mode) and `k`.
      */
     getPaper(id: string, options?: {
@@ -1495,8 +1578,19 @@ declare class FirecrawlClient {
      */
     searchFeedback(jobId: string, request: SearchFeedbackRequest): Promise<FeedbackResponse>;
     /**
-     * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).
-     * Example: `firecrawl.research.searchPapers("diffusion models")`.
+     * Access the v2 research endpoints — Firecrawl's **research paper index**
+     * (~43M paper abstracts) plus GitHub history/readmes.
+     *
+     * The paper corpus is roughly 90% biomedical and life sciences — PubMed,
+     * bioRxiv and medRxiv — with arXiv covering physics, mathematics and
+     * computer science.
+     *
+     * ⚠️ Not the same as `search({ categories: ["research"] })`, which is only a
+     * website/domain filter over ordinary web search (~14 academic domains,
+     * returning page snippets). Use `research.searchPapers()` for literature
+     * search.
+     *
+     * Example: `firecrawl.research.searchPapers("GLP-1 receptor agonists cardiovascular outcomes")`.
      */
     get research(): ResearchClient;
     /**
@@ -2525,7 +2619,7 @@ declare class FirecrawlApp {
      * @param onActivity - Optional callback to receive activity updates in real-time.
      * @param onSource - Optional callback to receive source updates in real-time.
      * @returns The final research results.
-     * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+     * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
      */
     deepResearch(query: string, params: DeepResearchParams<zt.ZodSchema>, onActivity?: (activity: {
         type: string;
@@ -2543,14 +2637,14 @@ declare class FirecrawlApp {
      * Initiates a deep research operation on a given query without polling.
      * @param params - Parameters for the deep research operation.
      * @returns The response containing the research job ID.
-     * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+     * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
      */
     asyncDeepResearch(query: string, params: DeepResearchParams<zt.ZodSchema>): Promise<DeepResearchResponse | ErrorResponse>;
     /**
      * Checks the status of a deep research operation.
      * @param id - The ID of the deep research operation.
      * @returns The current status and results of the research operation.
-     * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+     * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
      */
     checkDeepResearchStatus(id: string): Promise<DeepResearchStatusResponse | ErrorResponse>;
     /**

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-BEF2NAMB.js";
+} from "./chunk-S7CQ7Q2W.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -629,12 +629,16 @@ async function search(http, request) {
     if (data.news) out.news = transformArray(data.news);
     if (data.images)
       out.images = transformArray(data.images);
+    if (data.developer)
+      out.developer = transformArray(data.developer);
     Object.defineProperty(out, "data", {
       get() {
         const parts = [];
         if (out.web?.length) parts.push(`.web (${out.web.length} results)`);
         if (out.news?.length) parts.push(`.news (${out.news.length} results)`);
         if (out.images?.length) parts.push(`.images (${out.images.length} results)`);
+        if (out.developer?.length)
+          parts.push(`.developer (${out.developer.length} results)`);
         const available = parts.length ? parts.join(", ") : ".web, .news, or .images";
         throw new Error(
           `SearchData has no '.data'. Results are grouped by source: ${available}`
@@ -1398,9 +1402,20 @@ var ResearchClient = class {
   }
   http;
   /**
-   * Search papers by abstract relevance.
-   * @param query Natural-language search query.
-   * @param options Optional filters (k, authors, categories, from, to).
+   * Search the research paper index by abstract relevance.
+   *
+   * Queries ~43M paper abstracts: PubMed, bioRxiv and medRxiv (about 90% of the
+   * corpus — biomedical and life sciences) plus arXiv (physics, mathematics,
+   * computer science). Semantic search over abstracts, not keyword matching.
+   *
+   * This is **not** `search({ categories: ["research"] })`, which only narrows
+   * ordinary web search to ~14 academic websites.
+   *
+   * @param query Natural-language search query, e.g. `"CRISPR base editing
+   *   off-target effects in primary human T cells"`.
+   * @param options Optional filters (k, authors, categories, from, to). Note
+   *   `categories` here filters *paper* subject categories (e.g. `"q-bio.GN"`)
+   *   and is unrelated to the `categories` option of `search()`.
    */
   async searchPapers(query, options = {}) {
     if (!query || !query.trim()) throw new Error("query cannot be empty");
@@ -1950,8 +1965,19 @@ var FirecrawlClient = class {
   }
   // Research
   /**
-   * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).
-   * Example: `firecrawl.research.searchPapers("diffusion models")`.
+   * Access the v2 research endpoints — Firecrawl's **research paper index**
+   * (~43M paper abstracts) plus GitHub history/readmes.
+   *
+   * The paper corpus is roughly 90% biomedical and life sciences — PubMed,
+   * bioRxiv and medRxiv — with arXiv covering physics, mathematics and
+   * computer science.
+   *
+   * ⚠️ Not the same as `search({ categories: ["research"] })`, which is only a
+   * website/domain filter over ordinary web search (~14 academic domains,
+   * returning page snippets). Use `research.searchPapers()` for literature
+   * search.
+   *
+   * Example: `firecrawl.research.searchPapers("GLP-1 receptor agonists cardiovascular outcomes")`.
    */
   get research() {
     if (!this._research) this._research = new ResearchClient(this.http);
@@ -2316,7 +2342,7 @@ var FirecrawlApp = class {
       if (typeof process !== "undefined" && process.env && process.env.npm_package_version) {
         return process.env.npm_package_version;
       }
-      const packageJson = await import("./package-GIVYQAT4.js");
+      const packageJson = await import("./package-KQCMZM5L.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);
@@ -3142,7 +3168,7 @@ var FirecrawlApp = class {
    * @param onActivity - Optional callback to receive activity updates in real-time.
    * @param onSource - Optional callback to receive source updates in real-time.
    * @returns The final research results.
-   * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+   * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
    */
   async deepResearch(query, params, onActivity, onSource) {
     try {
@@ -3199,7 +3225,7 @@ var FirecrawlApp = class {
    * Initiates a deep research operation on a given query without polling.
    * @param params - Parameters for the deep research operation.
    * @returns The response containing the research job ID.
-   * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+   * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
    */
   async asyncDeepResearch(query, params) {
     const headers = this.prepareHeaders();
@@ -3237,7 +3263,7 @@ var FirecrawlApp = class {
    * Checks the status of a deep research operation.
    * @param id - The ID of the deep research operation.
    * @returns The current status and results of the research operation.
-   * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+   * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
    */
   async checkDeepResearchStatus(id) {
     const headers = this.prepareHeaders();

package/dist/{package-GIVYQAT4.js → package-KQCMZM5L.js}

@@ -1,4 +1,4 @@
 import {
   require_package
-} from "./chunk-BEF2NAMB.js";
+} from "./chunk-S7CQ7Q2W.js";
 export default require_package();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "firecrawl",
-  "version": "4.31.1",
-  "description": "JavaScript SDK for Firecrawl API",
+  "version": "4.32.1",
+  "description": "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -49,7 +49,21 @@
     "web",
     "scraper",
     "api",
-    "sdk"
+    "sdk",
+    "web-search",
+    "literature-search",
+    "research",
+    "scientific-papers",
+    "academic-search",
+    "biomedical",
+    "life-sciences",
+    "pubmed",
+    "biorxiv",
+    "medrxiv",
+    "arxiv",
+    "preprints",
+    "citations",
+    "bioinformatics"
   ],
   "engines": {
     "node": ">=22.0.0"

package/pnpm-workspace.yaml

@@ -7,8 +7,9 @@ overrides:
   "rollup@<4.59.0": ">=4.59.0"
   "picomatch@<4.0.4": ">=4.0.4"
   handlebars: ">=4.7.9"
-  "brace-expansion@>=5.0.0 <5.0.8": "5.0.8"
-  "js-yaml@>=3.0.0 <3.15.0": "3.15.0"
+  "brace-expansion@>=5.0.0 <5.0.9": "5.0.9"
+  "js-yaml@>=3.0.0 <3.15.1": "3.15.1"
+  "js-yaml@>=4.0.0 <4.3.1": "4.3.1"
   "axios@>=1.0.0 <1.16.0": "1.16.1"
   "follow-redirects@<1.16.0": ">=1.16.0 <2.0.0"
   "form-data@>=4.0.0 <4.0.6": "4.0.6"

package/src/__tests__/unit/v2/search-developer.unit.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, jest, test } from "@jest/globals";
+import { search } from "../../../v2/methods/search";
+
+const developerResult = {
+  title: "https://github.com/firecrawl/firecrawl/issues/1",
+  url: "https://github.com/firecrawl/firecrawl/issues/1",
+  description: "passage",
+  position: 1,
+  category: "developer",
+};
+
+function httpWith(data: Record<string, unknown>) {
+  return {
+    post: jest.fn(async () => ({ status: 200, data: { success: true, data } })),
+  } as any;
+}
+
+describe("v2 search developer category", () => {
+  test("forwards the developer category", async () => {
+    const http = httpWith({});
+
+    await search(http, { query: "firecrawl", categories: ["developer"] });
+
+    expect(http.post).toHaveBeenCalledWith(
+      "/v2/search",
+      { query: "firecrawl", categories: ["developer"] },
+      {},
+    );
+  });
+
+  test("returns developer results", async () => {
+    const http = httpWith({
+      web: [{ title: "W", url: "http://a.com" }],
+      developer: [developerResult],
+    });
+
+    const result = await search(http, {
+      query: "firecrawl",
+      categories: [{ type: "developer" }],
+    });
+
+    expect(result.web).toHaveLength(1);
+    expect(result.developer).toHaveLength(1);
+    expect(result.developer?.[0]).toEqual(developerResult);
+  });
+
+  test("omits developer when the response has none", async () => {
+    const http = httpWith({ web: [] });
+
+    const result = await search(http, { query: "firecrawl" });
+
+    expect(result.developer).toBeUndefined();
+  });
+
+  test("lists developer in the .data error", async () => {
+    const http = httpWith({ developer: [developerResult] });
+
+    const result = await search(http, {
+      query: "firecrawl",
+      categories: ["developer"],
+    });
+
+    expect(() => (result as any).data).toThrow(/\.developer \(1 results\)/);
+  });
+});

package/src/v1/index.ts

@@ -1642,7 +1642,7 @@ export default class FirecrawlApp {
    * @param onActivity - Optional callback to receive activity updates in real-time.
    * @param onSource - Optional callback to receive source updates in real-time.
    * @returns The final research results.
-   * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+   * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
    */
   async deepResearch(
     query: string, 
@@ -1730,7 +1730,7 @@ export default class FirecrawlApp {
    * Initiates a deep research operation on a given query without polling.
    * @param params - Parameters for the deep research operation.
    * @returns The response containing the research job ID.
-   * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+   * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
    */
   async asyncDeepResearch(query: string, params: DeepResearchParams<zt.ZodSchema>): Promise<DeepResearchResponse | ErrorResponse> {
     const headers = this.prepareHeaders();
@@ -1772,7 +1772,7 @@ export default class FirecrawlApp {
    * Checks the status of a deep research operation.
    * @param id - The ID of the deep research operation.
    * @returns The current status and results of the research operation.
-   * @deprecated /v1/deep-research is deprecated. Use /v2/search instead.
+   * @deprecated /v1/deep-research is deprecated. Use /v2/search for web research, or research.searchPapers() for scientific literature.
    */
   async checkDeepResearchStatus(id: string): Promise<DeepResearchStatusResponse | ErrorResponse> {
     const headers = this.prepareHeaders();

package/src/v2/client.ts

@@ -261,8 +261,19 @@ export class FirecrawlClient {
 
   // Research
   /**
-   * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).
-   * Example: `firecrawl.research.searchPapers("diffusion models")`.
+   * Access the v2 research endpoints — Firecrawl's **research paper index**
+   * (~43M paper abstracts) plus GitHub history/readmes.
+   *
+   * The paper corpus is roughly 90% biomedical and life sciences — PubMed,
+   * bioRxiv and medRxiv — with arXiv covering physics, mathematics and
+   * computer science.
+   *
+   * ⚠️ Not the same as `search({ categories: ["research"] })`, which is only a
+   * website/domain filter over ordinary web search (~14 academic domains,
+   * returning page snippets). Use `research.searchPapers()` for literature
+   * search.
+   *
+   * Example: `firecrawl.research.searchPapers("GLP-1 receptor agonists cardiovascular outcomes")`.
    */
   get research(): ResearchClient {
     if (!this._research) this._research = new ResearchClient(this.http);

package/src/v2/methods/research.ts

@@ -63,16 +63,47 @@ function normalizeResearchError(err: any, action: string): never {
 }
 
 /**
- * Client for the v2 research endpoints (arXiv papers + GitHub history/readmes).
+ * Client for the v2 research endpoints — Firecrawl's **research paper index**
+ * (~43M paper abstracts) plus GitHub history/readmes.
+ *
+ * The paper corpus is roughly 90% biomedical and life sciences — PubMed,
+ * bioRxiv and medRxiv — with arXiv covering physics, mathematics and computer
+ * science. Supports abstract search, paper metadata, in-body passage reads and
+ * citation-graph expansion.
+ *
+ * ⚠️ This is **not** the same as `search({ categories: ["research"] })`. That
+ * option is a website/domain filter on ordinary web search: it narrows
+ * Google-style results to ~14 academic domains and returns page snippets. The
+ * methods here query the paper index itself and return ranked paper records.
+ *
  * Accessed via `firecrawl.research`.
+ *
+ * @example
+ * ```ts
+ * const res = await firecrawl.research.searchPapers(
+ *   "tau aggregation inhibitors in Alzheimer's disease",
+ *   { k: 10 },
+ * );
+ * ```
  */
 export class ResearchClient {
   constructor(private readonly http: HttpClient) {}
 
   /**
-   * Search papers by abstract relevance.
-   * @param query Natural-language search query.
-   * @param options Optional filters (k, authors, categories, from, to).
+   * Search the research paper index by abstract relevance.
+   *
+   * Queries ~43M paper abstracts: PubMed, bioRxiv and medRxiv (about 90% of the
+   * corpus — biomedical and life sciences) plus arXiv (physics, mathematics,
+   * computer science). Semantic search over abstracts, not keyword matching.
+   *
+   * This is **not** `search({ categories: ["research"] })`, which only narrows
+   * ordinary web search to ~14 academic websites.
+   *
+   * @param query Natural-language search query, e.g. `"CRISPR base editing
+   *   off-target effects in primary human T cells"`.
+   * @param options Optional filters (k, authors, categories, from, to). Note
+   *   `categories` here filters *paper* subject categories (e.g. `"q-bio.GN"`)
+   *   and is unrelated to the `categories` option of `search()`.
    */
   async searchPapers(
     query: string,
@@ -102,8 +133,9 @@ export class ResearchClient {
   /**
    * Get paper metadata (detail mode), or read in-body passages (when `query` is
    * supplied). `k` is only valid together with `query`.
-   * @param id Paper reference: a canonical `paper_id`, an `arxiv:<id>` key, or a
-   *   bare arXiv id / URL.
+   * @param id Paper reference: a canonical `paperId`, or a namespaced id key
+   *   such as `pmid:<id>`, `pmcid:<id>`, `doi:<doi>` or `arxiv:<id>`. Bare
+   *   arXiv ids and arXiv URLs are also accepted.
    * @param options Optional `query` (switches to read mode) and `k`.
    */
   async getPaper(

package/src/v2/methods/search.ts

@@ -102,12 +102,16 @@ export async function search(
     if (data.news) out.news = transformArray<SearchResultNews>(data.news);
     if (data.images)
       out.images = transformArray<SearchResultImages>(data.images);
+    if (data.developer)
+      out.developer = transformArray<SearchResultWeb>(data.developer);
     Object.defineProperty(out, "data", {
       get() {
         const parts: string[] = [];
         if (out.web?.length) parts.push(`.web (${out.web.length} results)`);
         if (out.news?.length) parts.push(`.news (${out.news.length} results)`);
         if (out.images?.length) parts.push(`.images (${out.images.length} results)`);
+        if (out.developer?.length)
+          parts.push(`.developer (${out.developer.length} results)`);
         const available = parts.length ? parts.join(", ") : ".web, .news, or .images";
         throw new Error(
           `SearchData has no '.data'. Results are grouped by source: ${available}`,

package/src/v2/types.ts

@@ -207,6 +207,10 @@ export interface ScrapeOptions {
   useMock?: string;
   blockAds?: boolean;
   proxy?: "basic" | "stealth" | "enhanced" | "auto" | string;
+  /**
+   * Maximum age, in milliseconds, of indexed content that may be reused.
+   * Set to `0` to bypass index reuse.
+   */
   maxAge?: number;
   minAge?: number;
   storeInCache?: boolean;
@@ -558,6 +562,7 @@ export interface DocumentMetadata {
   // Common metadata fields
   title?: string;
   description?: string;
+  /** URL reported by the selected scrape engine. */
   url?: string;
   language?: string;
   keywords?: string | string[];
@@ -594,7 +599,9 @@ export interface DocumentMetadata {
   articleSection?: string;
 
   // Response-level metadata
+  /** URL requested for the scrape. */
   sourceURL?: string;
+  /** HTTP status code reported for the scrape response. */
   statusCode?: number;
   scrapeId?: string;
   numPages?: number;
@@ -657,6 +664,7 @@ export interface SearchResultWeb {
   url: string;
   title?: string;
   description?: string;
+  position?: number;
   category?: string;
 }
 
@@ -683,10 +691,33 @@ export interface SearchData {
   web?: Array<SearchResultWeb | Document>;
   news?: Array<SearchResultNews | Document>;
   images?: Array<SearchResultImages | Document>;
+  developer?: Array<SearchResultWeb | Document>;
 }
 
+/**
+ * Narrows ordinary **web search**. A category does not switch `search()` to a
+ * different index.
+ *
+ * - `github` — restrict web results to github.com (a `site:` filter).
+ * - `research` — restrict web results to a fixed list of ~14 academic
+ *   *websites* (arxiv.org, pubmed.ncbi.nlm.nih.gov, nature.com, science.org,
+ *   ieee.org, sciencedirect.com, biorxiv.org, medrxiv.org, ...). It returns
+ *   ordinary web page results from those domains, **not** paper records.
+ * - `pdf` — restrict results to PDFs (adds `filetype:pdf`).
+ * - `developer` — add developer results (issues, pull requests, READMEs and
+ *   documentation) under `.developer`.
+ *
+ * ⚠️ `categories: ["research"]` is **not** Firecrawl's research paper index.
+ * To search papers themselves — ~43M abstracts, roughly 90% biomedical
+ * (PubMed, bioRxiv, medRxiv) plus arXiv — with full abstracts, in-body passage
+ * reads and citation-graph expansion, use `firecrawl.research.searchPapers()`
+ * (plus `getPaper()` and `similarPapers()`), which call `/v2/search/research`.
+ *
+ * Rule of thumb: literature search → `research.searchPapers()`; web pages that
+ * happen to live on academic domains → `search({ categories: ["research"] })`.
+ */
 export interface CategoryOption {
-  type: "github" | "research" | "pdf";
+  type: "github" | "research" | "pdf" | "developer";
 }
 
 export interface SearchRequest {
@@ -694,7 +725,17 @@ export interface SearchRequest {
   sources?: Array<
     "web" | "news" | "images" | { type: "web" | "news" | "images" }
   >;
-  categories?: Array<"github" | "research" | "pdf" | CategoryOption>;
+  /**
+   * Narrow web search by category. See {@link CategoryOption}.
+   *
+   * ⚠️ `"research"` is a website/domain filter over ordinary web search (~14
+   * academic domains), **not** the research paper index. For literature search
+   * over ~43M paper abstracts (PubMed / bioRxiv / medRxiv / arXiv) use
+   * `firecrawl.research.searchPapers()` instead.
+   */
+  categories?: Array<
+    "github" | "research" | "pdf" | "developer" | CategoryOption
+  >;
   includeDomains?: string[];
   excludeDomains?: string[];
   limit?: number;
@@ -1351,8 +1392,20 @@ export interface BrowserListResponse {
 // ---------- Research (v2) ----------
 
 /**
- * Source identifiers grouped by namespace. Currently only `arxiv` is
- * populated; each value is an array of ids in that namespace.
+ * Source identifiers grouped by namespace. Each key is a namespace and each
+ * value is an array of ids in that namespace.
+ *
+ * Which namespaces appear depends on the paper's source. Biomedical records
+ * (PubMed, bioRxiv, medRxiv) typically carry `pmid`, `pmcid` and/or `doi`;
+ * arXiv records carry `arxiv`. The set is open — treat this as a lookup by
+ * namespace rather than a fixed schema, and prefer {@link PaperResult.primaryId}
+ * when you just need one citable identifier.
+ *
+ * @example
+ * ```ts
+ * const doi = paper.ids?.doi?.[0];
+ * const pmid = paper.ids?.pmid?.[0];
+ * ```
  */
 export type IdMap = Record<string, string[]>;
 
@@ -1368,7 +1421,7 @@ export interface PaperSignals {
   seedOverlap: number;
 }
 
-/** A ranked paper. `paperId` is canonical; arXiv lives in `ids`. */
+/** A ranked paper. `paperId` is canonical; source ids (pmid, pmcid, doi, arxiv, ...) live in `ids`. */
 export interface PaperResult {
   /** Canonical paper id — the Milvus INT64 primary key as a decimal string. */
   paperId: string;
@@ -1448,7 +1501,7 @@ export interface GitHubScoreBreakdown {
 }
 
 export interface GitHubSearchItem {
-  resultType: "github_history" | "repo_readme" | "web";
+  resultType?: "github_history" | "repo_readme" | "web";
   /** `owner/name`; empty for web results whose URL is not a repo page. */
   repo: string;
   url: string;