Skip to content

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

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.cs
index 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 ModelsTests
Assert.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.csproj
index 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.cs
index 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.cs
index 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.cs
index 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.go
index 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.go
index 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 := true
blocks := true
payload, 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.go
index 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.kts
index 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_11
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 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 minutes
private 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.java
index 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; }
@Override
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/PdfPage.java b/apps/java-sdk/src/main/java/com/firecrawl/models/PdfPage.java
new file mode 100644
index 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.java
index 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.java
index 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());
+ }
+
@Test
void 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.json
index 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.ts
index 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.ts
index 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.md
index 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
### Added
diff --git a/apps/php-sdk/src/Models/Document.php b/apps/php-sdk/src/Models/Document.php
index 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 Document
private 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 Document
menu: 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 Document
return $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.php
index 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.php
index 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__.py
index 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 project
logger: 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.py
index 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, PdfPageBlocks
from 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.py
index 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 True
assert dict_result["parsers"][0]["blocks"] is True
assert "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.py
index 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 types
ScrapeFormats,
@@ -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.py
index 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] = None
product: Optional[ProductProfile] = None
menu: Optional[MenuProfile] = None
+ pages: Optional[List[PdfPage]] = None
blocks: Optional[List[PdfPageBlocks]] = None
@property
@@ -1656,9 +1666,23 @@ class PDFParser(BaseModel):
type: Literal["pdf"] = "pdf"
mode: Optional[Literal["fast", "auto", "ocr"]] = None
max_pages: Optional[int] = None
- page_markdown: Optional[bool] = None
+ pages: Optional[bool] = None
blocks: 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 types
class Location(BaseModel):
diff --git a/apps/python-sdk/firecrawl/v2/utils/validation.py b/apps/python-sdk/firecrawl/v2/utils/validation.py
index 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[st
parser_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 API
if "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_parsers
elif key == "location":
diff --git a/apps/ruby-sdk/lib/firecrawl/models/document.rb b/apps/ruby-sdk/lib/firecrawl/models/document.rb
index 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, :blocks
def 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"]
end
diff --git a/apps/ruby-sdk/lib/firecrawl/version.rb b/apps/ruby-sdk/lib/firecrawl/version.rb
index 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: true
module Firecrawl
- VERSION = "1.12.0"
+ VERSION = "1.13.0"
end
diff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rb
index 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::Test
assert_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_blocks
stub_request(:post, "#{BASE_URL}/v2/scrape")
.to_return(
diff --git a/apps/rust-sdk/CHANGELOG.md b/apps/rust-sdk/CHANGELOG.md
index 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
### Added
diff --git a/apps/rust-sdk/Cargo.lock b/apps/rust-sdk/Cargo.lock
index 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.toml
index 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.rs
index 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.rs
index 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");
+ }
}