Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat(sdks): add parsers[].pages for per-page PDF markdown (#4353)
Abimael Martell66bc30849c9e
diff --git a/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs b/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.csindex da08b5638..ec8e9c71e 100644--- a/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs+++ b/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs@@ -145,6 +145,30 @@ public class ModelsTestsAssert.Null(doc.Warning);}+ [Fact]+ public void Document_DeserializesPagesCorrectly()+ {+ var json = """+ {+ "markdown": "# Annual Report 2025",+ "pages": [+ { "pageNumber": 1, "markdown": "# Cover" },+ { "pageNumber": 2, "markdown": "## Intro" }+ ]+ }+ """;++ var doc = JsonSerializer.Deserialize<Document>(json, JsonOptions);+ Assert.NotNull(doc);+ Assert.Equal("# Annual Report 2025", doc.Markdown);+ Assert.NotNull(doc.Pages);+ Assert.Equal(2, doc.Pages.Count);+ Assert.Equal(1, doc.Pages[0].PageNumber);+ Assert.Equal("# Cover", doc.Pages[0].Markdown);+ Assert.Equal(2, doc.Pages[1].PageNumber);+ Assert.Equal("## Intro", doc.Pages[1].Markdown);+ }+[Fact]public void Document_DeserializesBlocksCorrectly(){diff --git a/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj b/apps/dot-net-sdk/Firecrawl/Firecrawl.csprojindex a3b918db3..a1da00373 100644--- a/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj+++ b/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj@@ -8,7 +8,7 @@<!-- NuGet package metadata --><PackageId>firecrawl-sdk</PackageId>- <Version>1.11.0</Version>+ <Version>1.12.0</Version><Authors>Firecrawl</Authors><Company>Firecrawl</Company><Description>.NET SDK for the Firecrawl API - web scraping, crawling, and data extraction</Description>diff --git a/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs b/apps/dot-net-sdk/Firecrawl/FirecrawlClient.csindex 03b797d94..e3bcb1a65 100644--- a/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs+++ b/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs@@ -714,7 +714,7 @@ public class FirecrawlClient// INTERNAL UTILITIES// ================================================================- private const string SdkOrigin = "[email protected]";+ private const string SdkOrigin = "[email protected]";private static Dictionary<string, object> BuildBody(object? options){diff --git a/apps/dot-net-sdk/Firecrawl/Models/Document.cs b/apps/dot-net-sdk/Firecrawl/Models/Document.csindex 6852cb52c..ea8538ede 100644--- a/apps/dot-net-sdk/Firecrawl/Models/Document.cs+++ b/apps/dot-net-sdk/Firecrawl/Models/Document.cs@@ -64,6 +64,12 @@ public class Document[JsonPropertyName("menu")]public MenuProfile? Menu { get; set; }+ /// <summary>+ /// Physical PDF pages, present only when parsers[].pages is true.+ /// </summary>+ [JsonPropertyName("pages")]+ public List<PdfPage>? Pages { get; set; }+/// <summary>/// Typed PDF layout blocks, present only when parsers[].blocks is true./// </summary>diff --git a/apps/dot-net-sdk/Firecrawl/Models/PdfBlocks.cs b/apps/dot-net-sdk/Firecrawl/Models/PdfBlocks.csindex cca587b8f..9699d45df 100644--- a/apps/dot-net-sdk/Firecrawl/Models/PdfBlocks.cs+++ b/apps/dot-net-sdk/Firecrawl/Models/PdfBlocks.cs@@ -2,6 +2,18 @@ using System.Text.Json.Serialization;namespace Firecrawl.Models;+/// <summary>+/// Physical markdown for a single PDF page.+/// </summary>+public class PdfPage+{+ [JsonPropertyName("pageNumber")]+ public int PageNumber { get; set; }++ [JsonPropertyName("markdown")]+ public string Markdown { get; set; } = "";+}+/// <summary>/// Layout and OCR confidence scores for a PDF block./// </summary>diff --git a/apps/go-sdk/models.go b/apps/go-sdk/models.goindex 7408ecb17..be4077172 100644--- a/apps/go-sdk/models.go+++ b/apps/go-sdk/models.go@@ -24,17 +24,25 @@ type Document struct {Branding map[string]interface{} `json:"branding,omitempty"`Product *ProductProfile `json:"product,omitempty"`Menu *MenuProfile `json:"menu,omitempty"`+ // Pages is per-page PDF markdown, present only when parsers[].pages is true.+ Pages []PdfPage `json:"pages,omitempty"`// Blocks is typed PDF layout data, present only when parsers[].blocks is true.Blocks []PdfPageBlocks `json:"blocks,omitempty"`}// PDFParser configures PDF parsing. Use in ScrapeOptions.Parsers / ParseOptions.Parsers.type PDFParser struct {- Type string `json:"type"`- Mode string `json:"mode,omitempty"`- MaxPages *int `json:"maxPages,omitempty"`- PageMarkdown *bool `json:"pageMarkdown,omitempty"`- Blocks *bool `json:"blocks,omitempty"`+ Type string `json:"type"`+ Mode string `json:"mode,omitempty"`+ MaxPages *int `json:"maxPages,omitempty"`+ Pages *bool `json:"pages,omitempty"`+ Blocks *bool `json:"blocks,omitempty"`+}++// PdfPage is physical markdown for a single PDF page.+type PdfPage struct {+ PageNumber int `json:"pageNumber"`+ Markdown string `json:"markdown"`}// PdfBlockConfidence is layout and OCR confidence for a PDF block.diff --git a/apps/go-sdk/options_test.go b/apps/go-sdk/options_test.goindex d7679d59c..4f8db4013 100644--- a/apps/go-sdk/options_test.go+++ b/apps/go-sdk/options_test.go@@ -64,23 +64,48 @@ func TestScrapeOptionsPreservesStringFormats(t *testing.T) {}}-func TestScrapeOptionsSerializesPDFParserBlocks(t *testing.T) {+func TestScrapeOptionsSerializesPDFParserPagesAndBlocks(t *testing.T) {+ pages := trueblocks := truepayload, err := json.Marshal(ScrapeOptions{Parsers: []interface{}{- PDFParser{Type: "pdf", Mode: "auto", Blocks: &blocks},+ PDFParser{Type: "pdf", Mode: "auto", Pages: &pages, Blocks: &blocks},},})if err != nil {t.Fatalf("Marshal ScrapeOptions: %v", err)}- want := `"parsers":[{"type":"pdf","mode":"auto","blocks":true}]`+ want := `"parsers":[{"type":"pdf","mode":"auto","pages":true,"blocks":true}]`if !strings.Contains(string(payload), want) {t.Fatalf("serialized parsers = %s, want to contain %s", payload, want)}}+func TestDocumentDeserializesPages(t *testing.T) {+ raw := []byte(`{+ "markdown": "# Annual Report 2025",+ "pages": [+ {"pageNumber": 1, "markdown": "# Cover"},+ {"pageNumber": 2, "markdown": "## Intro"}+ ]+ }`)++ var doc Document+ if err := json.Unmarshal(raw, &doc); err != nil {+ t.Fatalf("Unmarshal Document: %v", err)+ }+ if len(doc.Pages) != 2 {+ t.Fatalf("pages len = %d, want 2", len(doc.Pages))+ }+ if doc.Pages[0].PageNumber != 1 || doc.Pages[0].Markdown != "# Cover" {+ t.Fatalf("page 0 = %+v", doc.Pages[0])+ }+ if doc.Pages[1].PageNumber != 2 || doc.Pages[1].Markdown != "## Intro" {+ t.Fatalf("page 1 = %+v", doc.Pages[1])+ }+}+func TestDocumentDeserializesBlocks(t *testing.T) {raw := []byte(`{"markdown": "# Annual Report 2025",diff --git a/apps/go-sdk/version.go b/apps/go-sdk/version.goindex 63c538b9b..c27aa2928 100644--- a/apps/go-sdk/version.go+++ b/apps/go-sdk/version.go@@ -9,4 +9,4 @@ package firecrawl// Bump this when preparing a new release. The publish-go-sdk GitHub workflow// reads this value and creates the corresponding monorepo-prefixed tag on// merge to main.-const Version = "1.10.0"+const Version = "1.11.0"diff --git a/apps/java-sdk/build.gradle.kts b/apps/java-sdk/build.gradle.ktsindex 465f54062..e9c98c03a 100644--- a/apps/java-sdk/build.gradle.kts+++ b/apps/java-sdk/build.gradle.kts@@ -4,7 +4,7 @@ plugins {}group = "com.firecrawl"-version = "1.13.0"+version = "1.14.0"java {sourceCompatibility = JavaVersion.VERSION_11diff --git a/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java b/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.javaindex 6c6598f1c..f0c9f8ada 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@@ -37,7 +37,7 @@ import java.util.concurrent.ForkJoinPool;public class FirecrawlClient {private static final String DEFAULT_API_URL = "https://api.firecrawl.dev";- private static final String SDK_ORIGIN = "[email protected]";+ private static final String SDK_ORIGIN = "[email protected]";private static final long DEFAULT_TIMEOUT_MS = 300_000; // 5 minutesprivate static final int DEFAULT_MAX_RETRIES = 3;private static final double DEFAULT_BACKOFF_FACTOR = 0.5;diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/Document.java b/apps/java-sdk/src/main/java/com/firecrawl/models/Document.javaindex 6d5a34e9b..eb8cbe277 100644--- a/apps/java-sdk/src/main/java/com/firecrawl/models/Document.java+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/Document.java@@ -30,6 +30,8 @@ public class Document {private Map<String, Object> branding;private Product product;private Menu menu;+ /** Physical PDF pages, present only when parsers[].pages is true. */+ private List<PdfPage> pages;/** Typed PDF layout blocks, present only when parsers[].blocks is true. */private List<PdfPageBlocks> blocks;@@ -53,6 +55,7 @@ public class Document {public Map<String, Object> getBranding() { return branding; }public Product getProduct() { return product; }public Menu getMenu() { return menu; }+ public List<PdfPage> getPages() { return pages; }public List<PdfPageBlocks> getBlocks() { return blocks; }@Overridediff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/PdfPage.java b/apps/java-sdk/src/main/java/com/firecrawl/models/PdfPage.javanew file mode 100644index 000000000..c4a1b0680--- /dev/null+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/PdfPage.java@@ -0,0 +1,22 @@+package com.firecrawl.models;++import com.fasterxml.jackson.annotation.JsonIgnoreProperties;++/**+ * Physical markdown for a single PDF page, returned when+ * {@code parsers} includes {@code {type: "pdf", pages: true}}.+ */+@JsonIgnoreProperties(ignoreUnknown = true)+public class PdfPage {++ private int pageNumber;+ private String markdown;++ public int getPageNumber() { return pageNumber; }+ public String getMarkdown() { return markdown; }++ @Override+ public String toString() {+ return "PdfPage{pageNumber=" + pageNumber + "}";+ }+}diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/ScrapeOptions.java b/apps/java-sdk/src/main/java/com/firecrawl/models/ScrapeOptions.javaindex 9b2e54a42..202c27214 100644--- a/apps/java-sdk/src/main/java/com/firecrawl/models/ScrapeOptions.java+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/ScrapeOptions.java@@ -145,7 +145,7 @@ public class ScrapeOptions {/** Scrape as a mobile device. */public Builder mobile(Boolean mobile) { this.mobile = mobile; return this; }- /** Parsers to use (e.g., "pdf" or {"type": "pdf", "maxPages": 10, "blocks": true}). */+ /** Parsers to use (e.g., "pdf" or {"type": "pdf", "maxPages": 10, "pages": true, "blocks": true}). */public Builder parsers(List<Object> parsers) { this.parsers = parsers; return this; }/** Actions to execute before/during scraping. */diff --git a/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.java b/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.javaindex fd010ed98..c2cff9d5c 100644--- a/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.java+++ b/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.java@@ -261,6 +261,24 @@ class FirecrawlClientTest {);}+ @Test+ void testDocumentDeserializesPages() throws Exception {+ String json = "{\"markdown\":\"# Annual Report 2025\",\"pages\":["+ + "{\"pageNumber\":1,\"markdown\":\"# Cover\"},"+ + "{\"pageNumber\":2,\"markdown\":\"## Intro\"}]}";++ com.fasterxml.jackson.databind.ObjectMapper mapper = new com.fasterxml.jackson.databind.ObjectMapper();+ Document doc = mapper.readValue(json, Document.class);++ assertEquals("# Annual Report 2025", doc.getMarkdown());+ assertNotNull(doc.getPages());+ assertEquals(2, doc.getPages().size());+ assertEquals(1, doc.getPages().get(0).getPageNumber());+ assertEquals("# Cover", doc.getPages().get(0).getMarkdown());+ assertEquals(2, doc.getPages().get(1).getPageNumber());+ assertEquals("## Intro", doc.getPages().get(1).getMarkdown());+ }+@Testvoid testDocumentDeserializesBlocks() throws Exception {String json = "{\"markdown\":\"# Annual Report 2025\",\"blocks\":[{"diff --git a/apps/js-sdk/firecrawl/package.json b/apps/js-sdk/firecrawl/package.jsonindex 87b7ef629..1c98a72be 100644--- a/apps/js-sdk/firecrawl/package.json+++ b/apps/js-sdk/firecrawl/package.json@@ -1,6 +1,6 @@{"name": "@mendable/firecrawl-js",- "version": "4.33.0",+ "version": "4.34.0","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",diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/validation.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/validation.test.tsindex ae349dc07..162558e4f 100644--- a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/validation.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/validation.test.ts@@ -89,16 +89,16 @@ describe("v2 utils: validation", () => {expect(options.parsers).toEqual(before);});- test("ensureValidScrapeOptions: leaves PDF parser blocks option untouched", () => {+ test("ensureValidScrapeOptions: leaves PDF parser pages and blocks options untouched", () => {const options = {- parsers: [{ type: "pdf", mode: "auto", blocks: true, pageMarkdown: true }],+ parsers: [{ type: "pdf", mode: "auto", blocks: true, pages: true }],} as any;expect(() => ensureValidScrapeOptions(options)).not.toThrow();expect(options.parsers[0]).toEqual({type: "pdf",mode: "auto",blocks: true,- pageMarkdown: true,+ pages: true,});});diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.tsindex 1f840d35b..120f41049 100644--- a/apps/js-sdk/firecrawl/src/v2/types.ts+++ b/apps/js-sdk/firecrawl/src/v2/types.ts@@ -191,12 +191,21 @@ export type PDFParser = {type: "pdf";mode?: "fast" | "auto" | "ocr";maxPages?: number;- /** Include physical per-page markdown alongside document markdown. */+ /** Include physical per-page markdown alongside document markdown. Populates `document.pages`. */+ pages?: boolean;+ /**+ * @deprecated Renamed to `pages`. The API still accepts this as a silent alias.+ */pageMarkdown?: boolean;/** Include per-page typed layout blocks (bounding boxes, block types, reading order). */blocks?: boolean;};+export interface PdfPage {+ pageNumber: number;+ markdown: string;+}+export interface PdfBlockConfidence {layout: number | null;ocr: number | null;@@ -680,6 +689,8 @@ export interface Document {branding?: BrandingProfile;product?: ProductProfile;menu?: MenuProfile;+ /** Physical PDF pages, present only when `parsers[].pages` is true. */+ pages?: PdfPage[];/** Typed PDF layout blocks, present only when `parsers[].blocks` is true. */blocks?: PdfPageBlocks[];}diff --git a/apps/php-sdk/CHANGELOG.md b/apps/php-sdk/CHANGELOG.mdindex 34e8fea85..96660ff6b 100644--- a/apps/php-sdk/CHANGELOG.md+++ b/apps/php-sdk/CHANGELOG.md@@ -5,6 +5,11 @@ All notable changes to the Firecrawl PHP SDK will be documented in this file.The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).+## [1.12.0] - 2026-08-19++### Added+- PDF parser `pages` option and `Document::getPages()` for per-page markdown.+## [1.11.0] - 2026-08-19### Addeddiff --git a/apps/php-sdk/src/Models/Document.php b/apps/php-sdk/src/Models/Document.phpindex 49187755e..dc32247c1 100644--- a/apps/php-sdk/src/Models/Document.php+++ b/apps/php-sdk/src/Models/Document.php@@ -14,6 +14,7 @@ final class Document* @param array<string, mixed>|null $actions* @param array<string, mixed>|null $changeTracking* @param array<string, mixed>|null $branding+ * @param list<array<string, mixed>>|null $pages* @param list<array<string, mixed>>|null $blocks*/public function __construct(@@ -37,6 +38,7 @@ final class Documentprivate readonly ?array $branding = null,private readonly ?Product $product = null,private readonly ?Menu $menu = null,+ private readonly ?array $pages = null,private readonly ?array $blocks = null,) {}@@ -68,6 +70,9 @@ final class Documentmenu: isset($data['menu']) && is_array($data['menu'])? Menu::fromArray($data['menu']): null,+ pages: isset($data['pages']) && is_array($data['pages'])+ ? $data['pages']+ : null,blocks: isset($data['blocks']) && is_array($data['blocks'])? $data['blocks']: null,@@ -181,6 +186,16 @@ final class Documentreturn $this->menu;}+ /**+ * Physical PDF pages, present only when parsers[].pages is true.+ *+ * @return list<array<string, mixed>>|null+ */+ public function getPages(): ?array+ {+ return $this->pages;+ }+/*** Typed PDF layout blocks, present only when parsers[].blocks is true.*diff --git a/apps/php-sdk/src/Version.php b/apps/php-sdk/src/Version.phpindex bf594c79a..15e2cf996 100644--- a/apps/php-sdk/src/Version.php+++ b/apps/php-sdk/src/Version.php@@ -6,5 +6,5 @@ namespace Firecrawl;final class Version{- public const SDK_VERSION = '1.11.0';+ public const SDK_VERSION = '1.12.0';}diff --git a/apps/php-sdk/tests/Unit/ModelsTest.php b/apps/php-sdk/tests/Unit/ModelsTest.phpindex 4301e4d63..8a11fd0c6 100644--- a/apps/php-sdk/tests/Unit/ModelsTest.php+++ b/apps/php-sdk/tests/Unit/ModelsTest.php@@ -103,6 +103,21 @@ it('preserves null creditsUsed in CrawlJob', function (): void {expect($job->getCreditsUsed())->toBeNull();});+it('hydrates PDF pages in Document', function (): void {+ $doc = Document::fromArray([+ 'markdown' => '# Annual Report 2025',+ 'pages' => [+ ['pageNumber' => 1, 'markdown' => '# Cover'],+ ['pageNumber' => 2, 'markdown' => '## Intro'],+ ],+ ]);++ expect($doc->getMarkdown())->toBe('# Annual Report 2025');+ expect($doc->getPages())->toHaveCount(2);+ expect($doc->getPages()[0]['pageNumber'])->toBe(1);+ expect($doc->getPages()[0]['markdown'])->toBe('# Cover');+});+it('hydrates PDF blocks in Document', function (): void {$doc = Document::fromArray(['markdown' => '# Annual Report 2025',diff --git a/apps/python-sdk/firecrawl/__init__.py b/apps/python-sdk/firecrawl/__init__.pyindex 7c31532c1..0174e915f 100644--- a/apps/python-sdk/firecrawl/__init__.py+++ b/apps/python-sdk/firecrawl/__init__.py@@ -18,7 +18,7 @@ from .v1 import (V1ChangeTrackingOptions,)-__version__ = "4.36.0"+__version__ = "4.37.0"# Define the logger for the Firecrawl projectlogger: logging.Logger = logging.getLogger("firecrawl")diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_document_blocks.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_document_blocks.pyindex c0293e8d4..3e5df29bb 100644--- a/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_document_blocks.py+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_document_blocks.py@@ -1,4 +1,4 @@-from firecrawl.v2.types import Document, PdfPageBlocks+from firecrawl.v2.types import Document, PdfPage, PdfPageBlocksfrom firecrawl.v2.utils.normalize import normalize_document_input@@ -48,3 +48,24 @@ class TestDocumentBlocks:def test_blocks_absent_when_not_requested(self):doc = Document(**normalize_document_input({"markdown": "# Hello"}))assert doc.blocks is None+ assert doc.pages is None+++class TestDocumentPages:+ def test_pages_hydrate_from_api_camel_case(self):+ raw = {+ "markdown": "# Annual Report 2025",+ "pages": [+ {"pageNumber": 1, "markdown": "# Cover"},+ {"pageNumber": 2, "markdown": "## Intro"},+ ],+ }++ doc = Document(**normalize_document_input(raw))+ assert doc.pages is not None+ assert len(doc.pages) == 2+ assert isinstance(doc.pages[0], PdfPage)+ assert doc.pages[0].page_number == 1+ assert doc.pages[0].markdown == "# Cover"+ assert doc.pages[1].page_number == 2+ assert doc.pages[1].markdown == "## Intro"diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_validation.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_validation.pyindex f4bec29cf..1f9c6f984 100644--- a/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_validation.py+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_validation.py@@ -389,9 +389,9 @@ class TestPrepareScrapeOptions:assert result["parsers"][0]["maxPages"] == 5- def test_prepare_parsers_blocks_and_page_markdown(self):- """PDF parser blocks and page_markdown are sent in API camelCase."""- parser = PDFParser(mode="auto", page_markdown=True, blocks=True)+ def test_prepare_parsers_blocks_and_pages(self):+ """PDF parser blocks and pages are forwarded to the API."""+ parser = PDFParser(mode="auto", pages=True, blocks=True)options = ScrapeOptions(parsers=[parser])result = prepare_scrape_options(options)@@ -399,7 +399,7 @@ class TestPrepareScrapeOptions:assert result["parsers"][0] == {"type": "pdf","mode": "auto",- "pageMarkdown": True,+ "pages": True,"blocks": True,}@@ -407,9 +407,17 @@ class TestPrepareScrapeOptions:parsers=[{"type": "pdf", "page_markdown": True, "blocks": True}])dict_result = prepare_scrape_options(dict_options)- assert dict_result["parsers"][0]["pageMarkdown"] is True+ assert dict_result["parsers"][0]["pages"] is Trueassert dict_result["parsers"][0]["blocks"] is Trueassert "page_markdown" not in dict_result["parsers"][0]+ assert "pageMarkdown" not in dict_result["parsers"][0]++ camel_options = ScrapeOptions(+ parsers=[{"type": "pdf", "pageMarkdown": True}]+ )+ camel_result = prepare_scrape_options(camel_options)+ assert camel_result["parsers"][0]["pages"] is True+ assert "pageMarkdown" not in camel_result["parsers"][0]def test_prepare_min_age_maps_to_camel_case(self):"""min_age must be sent as minAge; the server drops the snake_case key."""diff --git a/apps/python-sdk/firecrawl/types.py b/apps/python-sdk/firecrawl/types.pyindex c1b647fab..47dea6159 100644--- a/apps/python-sdk/firecrawl/types.py+++ b/apps/python-sdk/firecrawl/types.py@@ -15,6 +15,7 @@ from .v2.types import (PdfBlockConfidence,PdfBlockItem,PdfPageBlocks,+ PdfPage,# Scrape typesScrapeFormats,@@ -103,6 +104,7 @@ __all__ = ['PdfBlockConfidence','PdfBlockItem','PdfPageBlocks',+ 'PdfPage',# Scrape types'ScrapeFormats',diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.pyindex f4f1fcbe4..d97dc9391 100644--- a/apps/python-sdk/firecrawl/v2/types.py+++ b/apps/python-sdk/firecrawl/v2/types.py@@ -476,6 +476,15 @@ class PdfPageBlocks(BaseModel):items: List[PdfBlockItem] = Field(default_factory=list)+class PdfPage(BaseModel):+ """Physical PDF page markdown, present when parsers[].pages is true."""++ model_config = {"extra": "allow", "populate_by_name": True}++ page_number: int = Field(alias="pageNumber")+ markdown: str++class Document(BaseModel):"""A scraped document."""@@ -498,6 +507,7 @@ class Document(BaseModel):branding: Optional[BrandingProfile] = Noneproduct: Optional[ProductProfile] = Nonemenu: Optional[MenuProfile] = None+ pages: Optional[List[PdfPage]] = Noneblocks: Optional[List[PdfPageBlocks]] = None@property@@ -1656,9 +1666,23 @@ class PDFParser(BaseModel):type: Literal["pdf"] = "pdf"mode: Optional[Literal["fast", "auto", "ocr"]] = Nonemax_pages: Optional[int] = None- page_markdown: Optional[bool] = None+ pages: Optional[bool] = Noneblocks: Optional[bool] = None+ @model_validator(mode="before")+ @classmethod+ def _fold_deprecated_page_markdown(cls, data: Any) -> Any:+ """Accept the pre-rename pageMarkdown alias and fold it into pages."""+ if not isinstance(data, dict):+ return data+ folded = dict(data)+ alias = folded.pop("page_markdown", None)+ if alias is None:+ alias = folded.pop("pageMarkdown", None)+ if folded.get("pages") is None and alias is not None:+ folded["pages"] = alias+ return folded+# Location typesclass Location(BaseModel):diff --git a/apps/python-sdk/firecrawl/v2/utils/validation.py b/apps/python-sdk/firecrawl/v2/utils/validation.pyindex 73c2a89c0..f88dfa06e 100644--- a/apps/python-sdk/firecrawl/v2/utils/validation.py+++ b/apps/python-sdk/firecrawl/v2/utils/validation.py@@ -790,16 +790,17 @@ def prepare_scrape_options(options: Optional[ScrapeOptions]) -> Optional[Dict[stparser_data = dict(parser)if "max_pages" in parser_data:parser_data["maxPages"] = parser_data.pop("max_pages")+ # Deprecated alias from the pre-rename pageMarkdown option.if "page_markdown" in parser_data:- parser_data["pageMarkdown"] = parser_data.pop("page_markdown")+ parser_data.setdefault("pages", parser_data.pop("page_markdown"))+ if "pageMarkdown" in parser_data:+ parser_data.setdefault("pages", parser_data.pop("pageMarkdown"))converted_parsers.append(parser_data)else:parser_data = parser.model_dump(exclude_none=True)# Convert snake_case to camelCase for APIif "max_pages" in parser_data:parser_data["maxPages"] = parser_data.pop("max_pages")- if "page_markdown" in parser_data:- parser_data["pageMarkdown"] = parser_data.pop("page_markdown")converted_parsers.append(parser_data)scrape_data["parsers"] = converted_parserselif key == "location":diff --git a/apps/ruby-sdk/lib/firecrawl/models/document.rb b/apps/ruby-sdk/lib/firecrawl/models/document.rbindex 219bd3062..87c651308 100644--- a/apps/ruby-sdk/lib/firecrawl/models/document.rb+++ b/apps/ruby-sdk/lib/firecrawl/models/document.rb@@ -8,7 +8,7 @@ module Firecrawl:metadata, :links, :images, :screenshot, :audio,:video, :attributes, :actions, :answer, :highlights,:warning, :change_tracking, :branding, :product, :menu,- :blocks+ :pages, :blocksdef initialize(data)@markdown = data["markdown"]@@ -31,6 +31,7 @@ module Firecrawl@branding = data["branding"]@product = data["product"] && ProductProfile.new(data["product"])@menu = data["menu"] && MenuProfile.new(data["menu"])+ @pages = data["pages"]@blocks = data["blocks"]enddiff --git a/apps/ruby-sdk/lib/firecrawl/version.rb b/apps/ruby-sdk/lib/firecrawl/version.rbindex ff07525b9..ad3564572 100644--- a/apps/ruby-sdk/lib/firecrawl/version.rb+++ b/apps/ruby-sdk/lib/firecrawl/version.rb@@ -1,5 +1,5 @@# frozen_string_literal: truemodule Firecrawl- VERSION = "1.12.0"+ VERSION = "1.13.0"enddiff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rbindex b93718c23..644cf0c66 100644--- a/apps/ruby-sdk/test/firecrawl/client_test.rb+++ b/apps/ruby-sdk/test/firecrawl/client_test.rb@@ -85,6 +85,27 @@ class ClientTest < Minitest::Testassert_equal "Example", doc.metadata["title"]end+ def test_scrape_hydrates_pdf_pages+ stub_request(:post, "#{BASE_URL}/v2/scrape")+ .to_return(+ status: 200,+ body: JSON.generate(data: {+ markdown: "# Annual Report 2025",+ pages: [+ { pageNumber: 1, markdown: "# Cover" },+ { pageNumber: 2, markdown: "## Intro" }+ ]+ }),+ headers: { "Content-Type" => "application/json" }+ )++ doc = @client.scrape("https://example.com/report.pdf")+ assert_equal "# Annual Report 2025", doc.markdown+ assert_equal 2, doc.pages.length+ assert_equal 1, doc.pages[0]["pageNumber"]+ assert_equal "# Cover", doc.pages[0]["markdown"]+ end+def test_scrape_hydrates_pdf_blocksstub_request(:post, "#{BASE_URL}/v2/scrape").to_return(diff --git a/apps/rust-sdk/CHANGELOG.md b/apps/rust-sdk/CHANGELOG.mdindex 8bf4a283e..2f1996072 100644--- a/apps/rust-sdk/CHANGELOG.md+++ b/apps/rust-sdk/CHANGELOG.md@@ -1,5 +1,12 @@## CHANGELOG+## [2.14.0] - 2026-08-19++### Added++- Added `ParserConfig::Pdf.pages` to request per-page PDF markdown.+- Added `Document.pages` (`PdfPage`) for physical page markdown.+## [2.13.0] - 2026-08-19### Addeddiff --git a/apps/rust-sdk/Cargo.lock b/apps/rust-sdk/Cargo.lockindex b24df11aa..c00d6c2f9 100644--- a/apps/rust-sdk/Cargo.lock+++ b/apps/rust-sdk/Cargo.lock@@ -250,7 +250,7 @@ checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"[[package]]name = "firecrawl"-version = "2.13.0"+version = "2.14.0"dependencies = ["mockito","reqwest",diff --git a/apps/rust-sdk/Cargo.toml b/apps/rust-sdk/Cargo.tomlindex e56ecbc85..81db3eb7c 100644--- a/apps/rust-sdk/Cargo.toml+++ b/apps/rust-sdk/Cargo.toml@@ -1,6 +1,6 @@[package]name = "firecrawl"-version = "2.13.0"+version = "2.14.0"edition = "2021"license = "MIT"homepage = "https://www.firecrawl.dev/"diff --git a/apps/rust-sdk/src/scrape.rs b/apps/rust-sdk/src/scrape.rsindex 30c2828d5..29374e414 100644--- a/apps/rust-sdk/src/scrape.rs+++ b/apps/rust-sdk/src/scrape.rs@@ -119,8 +119,8 @@ pub enum ParserConfig {mode: Option<String>,#[serde(rename = "maxPages", skip_serializing_if = "Option::is_none")]max_pages: Option<u32>,- #[serde(rename = "pageMarkdown", skip_serializing_if = "Option::is_none")]- page_markdown: Option<bool>,+ #[serde(skip_serializing_if = "Option::is_none")]+ pages: Option<bool>,#[serde(skip_serializing_if = "Option::is_none")]blocks: Option<bool>,},@@ -531,7 +531,7 @@ mod tests {parser_type: "pdf".to_string(),mode: Some("auto".to_string()),max_pages: None,- page_markdown: Some(true),+ pages: Some(true),blocks: Some(true),}]),..Default::default()@@ -543,7 +543,7 @@ mod tests {json!({"type": "pdf","mode": "auto",- "pageMarkdown": true,+ "pages": true,"blocks": true}));diff --git a/apps/rust-sdk/src/types.rs b/apps/rust-sdk/src/types.rsindex 5768662d8..b05c911b1 100644--- a/apps/rust-sdk/src/types.rs+++ b/apps/rust-sdk/src/types.rs@@ -690,10 +690,21 @@ pub struct Document {pub product: Option<Product>,/// Menu extraction result.pub menu: Option<Menu>,+ /// Physical PDF page markdown, present only when `parsers[].pages` is true.+ pub pages: Option<Vec<PdfPage>>,/// Typed PDF layout blocks, present only when `parsers[].blocks` is true.pub blocks: Option<Vec<PdfPageBlocks>>,}+/// Physical markdown for a single PDF page.+#[serde_with::skip_serializing_none]+#[derive(Deserialize, Serialize, Debug, Default, Clone)]+#[serde(rename_all = "camelCase")]+pub struct PdfPage {+ pub page_number: u32,+ pub markdown: String,+}+/// Layout and OCR confidence scores for a PDF block.#[serde_with::skip_serializing_none]#[derive(Deserialize, Serialize, Debug, Default, Clone)]@@ -1206,4 +1217,22 @@ mod tests {assert_eq!(pages[0].items[0].confidence.layout, Some(0.97));assert_eq!(pages[0].items[0].confidence.ocr, None);}++ #[test]+ fn test_document_with_pages() {+ let json = json!({+ "markdown": "# Annual Report 2025",+ "pages": [+ { "pageNumber": 1, "markdown": "# Cover" },+ { "pageNumber": 2, "markdown": "## Intro" }+ ]+ });+ let doc: Document = serde_json::from_value(json).unwrap();+ let pages = doc.pages.expect("pages should be present");+ assert_eq!(pages.len(), 2);+ assert_eq!(pages[0].page_number, 1);+ assert_eq!(pages[0].markdown, "# Cover");+ assert_eq!(pages[1].page_number, 2);+ assert_eq!(pages[1].markdown, "## Intro");+ }}