Skip to content

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

feat(sdks): add parsers[].pageMarkers for PDF page attribution (#4379)

Abimael Martell35a461f03da5
diff --git a/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs b/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs
index ec8e9c71e..612fbe99c 100644
--- a/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs
+++ b/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs
@@ -426,6 +426,25 @@ public class ModelsTests
Assert.Equal(2, job.Data.Count);
}
+ [Fact]
+ public void PdfParser_SerializesPageMarkers()
+ {
+ var parser = new PdfParser
+ {
+ Mode = "auto",
+ Pages = true,
+ Blocks = true,
+ PageMarkers = true
+ };
+
+ var json = JsonSerializer.Serialize(parser, JsonOptions);
+ Assert.Contains("\"type\":\"pdf\"", json);
+ Assert.Contains("\"mode\":\"auto\"", json);
+ Assert.Contains("\"pages\":true", json);
+ Assert.Contains("\"blocks\":true", json);
+ Assert.Contains("\"pageMarkers\":true", json);
+ }
+
[Fact]
public void JsonFormat_HasCorrectType()
{
diff --git a/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj b/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj
index a1da00373..7bc41f43a 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.12.0</Version>
+ <Version>1.13.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 e3bcb1a65..169db89f8 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/PdfParser.cs b/apps/dot-net-sdk/Firecrawl/Models/PdfParser.cs
new file mode 100644
index 000000000..f8f393c78
--- /dev/null
+++ b/apps/dot-net-sdk/Firecrawl/Models/PdfParser.cs
@@ -0,0 +1,45 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// PDF parser configuration for use in <see cref="ScrapeOptions.Parsers"/> /
+/// <see cref="ParseOptions.Parsers"/>.
+/// </summary>
+public class PdfParser
+{
+ [JsonPropertyName("type")]
+ public string Type { get; } = "pdf";
+
+ [JsonPropertyName("mode")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Mode { get; set; }
+
+ [JsonPropertyName("maxPages")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public int? MaxPages { get; set; }
+
+ /// <summary>
+ /// Include physical per-page markdown. Populates <c>document.pages</c>.
+ /// </summary>
+ [JsonPropertyName("pages")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? Pages { get; set; }
+
+ /// <summary>
+ /// Include per-page typed layout blocks. Populates <c>document.blocks</c>.
+ /// </summary>
+ [JsonPropertyName("blocks")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? Blocks { get; set; }
+
+ /// <summary>
+ /// Join PDF pages in <c>document.markdown</c> with
+ /// <c>\n\n---\n\n&lt;!-- page N --&gt;\n\n</c>. Markers appear between
+ /// pages only; numbering may skip pages merged by cross-page stitching β€”
+ /// use <see cref="Pages"/> when every physical page is needed.
+ /// </summary>
+ [JsonPropertyName("pageMarkers")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public bool? PageMarkers { get; set; }
+}
diff --git a/apps/go-sdk/models.go b/apps/go-sdk/models.go
index be4077172..f65ff0918 100644
--- a/apps/go-sdk/models.go
+++ b/apps/go-sdk/models.go
@@ -37,6 +37,11 @@ type PDFParser struct {
MaxPages *int `json:"maxPages,omitempty"`
Pages *bool `json:"pages,omitempty"`
Blocks *bool `json:"blocks,omitempty"`
+ // PageMarkers joins PDF pages in document.markdown with
+ // `\n\n---\n\n<!-- page N -->\n\n`. Markers appear between pages only;
+ // numbering may skip pages merged by cross-page stitching β€” use Pages
+ // when every physical page is needed. No new response field.
+ PageMarkers *bool `json:"pageMarkers,omitempty"`
}
// PdfPage is physical markdown for a single PDF page.
@@ -76,12 +81,12 @@ type PdfPageBlocks struct {
// ProductProfile represents structured product data extracted from a page
// via the `product` scrape format.
type ProductProfile struct {
- Title string `json:"title"`
- Brand string `json:"brand,omitempty"`
- Category string `json:"category,omitempty"`
- URL string `json:"url"`
- Description string `json:"description,omitempty"`
- Variants []ProductVariant `json:"variants,omitempty"`
+ Title string `json:"title"`
+ Brand string `json:"brand,omitempty"`
+ Category string `json:"category,omitempty"`
+ URL string `json:"url"`
+ Description string `json:"description,omitempty"`
+ Variants []ProductVariant `json:"variants,omitempty"`
}
// ProductImage is a single product image.
diff --git a/apps/go-sdk/options_test.go b/apps/go-sdk/options_test.go
index 4f8db4013..40c80df09 100644
--- a/apps/go-sdk/options_test.go
+++ b/apps/go-sdk/options_test.go
@@ -67,16 +67,17 @@ func TestScrapeOptionsPreservesStringFormats(t *testing.T) {
func TestScrapeOptionsSerializesPDFParserPagesAndBlocks(t *testing.T) {
pages := true
blocks := true
+ pageMarkers := true
payload, err := json.Marshal(ScrapeOptions{
Parsers: []interface{}{
- PDFParser{Type: "pdf", Mode: "auto", Pages: &pages, Blocks: &blocks},
+ PDFParser{Type: "pdf", Mode: "auto", Pages: &pages, Blocks: &blocks, PageMarkers: &pageMarkers},
},
})
if err != nil {
t.Fatalf("Marshal ScrapeOptions: %v", err)
}
- want := `"parsers":[{"type":"pdf","mode":"auto","pages":true,"blocks":true}]`
+ want := `"parsers":[{"type":"pdf","mode":"auto","pages":true,"blocks":true,"pageMarkers":true}]`
if !strings.Contains(string(payload), want) {
t.Fatalf("serialized parsers = %s, want to contain %s", payload, want)
}
diff --git a/apps/go-sdk/version.go b/apps/go-sdk/version.go
index c27aa2928..186497366 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.11.0"
+const Version = "1.12.0"
diff --git a/apps/java-sdk/build.gradle.kts b/apps/java-sdk/build.gradle.kts
index e9c98c03a..3d268db2a 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.14.0"
+version = "1.15.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 f0c9f8ada..3b725f3b3 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/ParseOptions.java b/apps/java-sdk/src/main/java/com/firecrawl/models/ParseOptions.java
index 01b133df1..ff88c6f5f 100644
--- a/apps/java-sdk/src/main/java/com/firecrawl/models/ParseOptions.java
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/ParseOptions.java
@@ -127,6 +127,7 @@ public class ParseOptions {
public Builder excludeTags(List<String> excludeTags) { this.excludeTags = excludeTags; return this; }
public Builder onlyMainContent(Boolean onlyMainContent) { this.onlyMainContent = onlyMainContent; return this; }
public Builder timeout(Integer timeout) { this.timeout = timeout; return this; }
+ /** Parsers to use (e.g., "pdf" or PdfParser with maxPages, pages, blocks, pageMarkers). */
public Builder parsers(List<Object> parsers) { this.parsers = parsers; return this; }
public Builder skipTlsVerification(Boolean skipTlsVerification) { this.skipTlsVerification = skipTlsVerification; return this; }
public Builder removeBase64Images(Boolean removeBase64Images) { this.removeBase64Images = removeBase64Images; return this; }
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/PdfParser.java b/apps/java-sdk/src/main/java/com/firecrawl/models/PdfParser.java
new file mode 100644
index 000000000..a32db3f82
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/PdfParser.java
@@ -0,0 +1,84 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * PDF parser configuration for use in {@code ScrapeOptions.parsers} /
+ * {@code ParseOptions.parsers}.
+ *
+ * <p>Usage:
+ * <pre>{@code
+ * PdfParser pdf = PdfParser.builder()
+ * .mode("auto")
+ * .pages(true)
+ * .blocks(true)
+ * .pageMarkers(true)
+ * .build();
+ * }</pre>
+ */
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class PdfParser {
+
+ private final String type = "pdf";
+ private String mode;
+ @JsonProperty("maxPages")
+ private Integer maxPages;
+ private Boolean pages;
+ private Boolean blocks;
+ @JsonProperty("pageMarkers")
+ private Boolean pageMarkers;
+
+ private PdfParser() {}
+
+ public String getType() { return type; }
+ public String getMode() { return mode; }
+ @JsonProperty("maxPages")
+ public Integer getMaxPages() { return maxPages; }
+ public Boolean getPages() { return pages; }
+ public Boolean getBlocks() { return blocks; }
+ @JsonProperty("pageMarkers")
+ public Boolean getPageMarkers() { return pageMarkers; }
+
+ public static Builder builder() { return new Builder(); }
+
+ public static final class Builder {
+ private String mode;
+ private Integer maxPages;
+ private Boolean pages;
+ private Boolean blocks;
+ private Boolean pageMarkers;
+
+ private Builder() {}
+
+ /** PDF processing mode: {@code "fast"}, {@code "auto"}, or {@code "ocr"}. */
+ public Builder mode(String mode) { this.mode = mode; return this; }
+
+ /** Maximum number of PDF pages to process. */
+ public Builder maxPages(Integer maxPages) { this.maxPages = maxPages; return this; }
+
+ /** Include physical per-page markdown. Populates {@code document.pages}. */
+ public Builder pages(Boolean pages) { this.pages = pages; return this; }
+
+ /** Include per-page typed layout blocks. Populates {@code document.blocks}. */
+ public Builder blocks(Boolean blocks) { this.blocks = blocks; return this; }
+
+ /**
+ * Join PDF pages in {@code document.markdown} with
+ * {@code \n\n---\n\n<!-- page N -->\n\n}. Markers appear between pages
+ * only; numbering may skip pages merged by cross-page stitching β€” use
+ * {@code pages(true)} when every physical page is needed.
+ */
+ public Builder pageMarkers(Boolean pageMarkers) { this.pageMarkers = pageMarkers; return this; }
+
+ public PdfParser build() {
+ PdfParser p = new PdfParser();
+ p.mode = this.mode;
+ p.maxPages = this.maxPages;
+ p.pages = this.pages;
+ p.blocks = this.blocks;
+ p.pageMarkers = this.pageMarkers;
+ return p;
+ }
+ }
+}
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 202c27214..8381b554a 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, "pages": true, "blocks": true}). */
+ /** Parsers to use (e.g., "pdf" or PdfParser with maxPages, pages, blocks, pageMarkers). */
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 c2cff9d5c..1cefffcdd 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,25 @@ class FirecrawlClientTest {
);
}
+ @Test
+ void testPdfParserSerializesPageMarkers() throws Exception {
+ PdfParser parser = PdfParser.builder()
+ .mode("auto")
+ .pages(true)
+ .blocks(true)
+ .pageMarkers(true)
+ .build();
+
+ com.fasterxml.jackson.databind.ObjectMapper mapper = new com.fasterxml.jackson.databind.ObjectMapper();
+ String json = mapper.writeValueAsString(parser);
+
+ assertTrue(json.contains("\"type\":\"pdf\""));
+ assertTrue(json.contains("\"mode\":\"auto\""));
+ assertTrue(json.contains("\"pages\":true"));
+ assertTrue(json.contains("\"blocks\":true"));
+ assertTrue(json.contains("\"pageMarkers\":true"));
+ }
+
@Test
void testDocumentDeserializesPages() throws Exception {
String json = "{\"markdown\":\"# Annual Report 2025\",\"pages\":["
diff --git a/apps/js-sdk/firecrawl/package.json b/apps/js-sdk/firecrawl/package.json
index a301ffd2f..276ed946b 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.34.2",
+ "version": "4.35.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 162558e4f..542078e87 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,9 +89,9 @@ describe("v2 utils: validation", () => {
expect(options.parsers).toEqual(before);
});
- test("ensureValidScrapeOptions: leaves PDF parser pages and blocks options untouched", () => {
+ test("ensureValidScrapeOptions: leaves PDF parser pages, blocks, and pageMarkers options untouched", () => {
const options = {
- parsers: [{ type: "pdf", mode: "auto", blocks: true, pages: true }],
+ parsers: [{ type: "pdf", mode: "auto", blocks: true, pages: true, pageMarkers: true }],
} as any;
expect(() => ensureValidScrapeOptions(options)).not.toThrow();
expect(options.parsers[0]).toEqual({
@@ -99,6 +99,7 @@ describe("v2 utils: validation", () => {
mode: "auto",
blocks: true,
pages: true,
+ pageMarkers: true,
});
});
diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.ts
index 1c6b76e2f..a3a9d4eea 100644
--- a/apps/js-sdk/firecrawl/src/v2/types.ts
+++ b/apps/js-sdk/firecrawl/src/v2/types.ts
@@ -199,6 +199,14 @@ export type PDFParser = {
pageMarkdown?: boolean;
/** Include per-page typed layout blocks (bounding boxes, block types, reading order). */
blocks?: boolean;
+ /**
+ * Join PDF pages in `document.markdown` with `\n\n---\n\n<!-- page N -->\n\n`,
+ * where N is the 1-based physical page of the content that follows. Markers
+ * appear between pages only (no leading marker for page 1), and numbering may
+ * skip pages merged by cross-page stitching β€” use `pages: true` when every
+ * physical page is needed. No new response field.
+ */
+ pageMarkers?: boolean;
};
export interface PdfPage {
diff --git a/apps/php-sdk/CHANGELOG.md b/apps/php-sdk/CHANGELOG.md
index 96660ff6b..8ff0f2778 100644
--- a/apps/php-sdk/CHANGELOG.md
+++ b/apps/php-sdk/CHANGELOG.md
@@ -5,6 +5,12 @@ 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.13.0] - 2026-08-21
+
+### Added
+- PDF parser `pageMarkers` option via `PDFParser` to join pages in
+ document markdown with `<!-- page N -->` separators.
+
## [1.12.0] - 2026-08-19
### Added
diff --git a/apps/php-sdk/src/Models/PDFParser.php b/apps/php-sdk/src/Models/PDFParser.php
new file mode 100644
index 000000000..4e2dada64
--- /dev/null
+++ b/apps/php-sdk/src/Models/PDFParser.php
@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Firecrawl\Models;
+
+/**
+ * PDF parser configuration for use in ScrapeOptions / ParseOptions parsers.
+ */
+final class PDFParser
+{
+ private function __construct(
+ private readonly ?string $mode = null,
+ private readonly ?int $maxPages = null,
+ private readonly ?bool $pages = null,
+ private readonly ?bool $blocks = null,
+ private readonly ?bool $pageMarkers = null,
+ ) {}
+
+ public static function with(
+ ?string $mode = null,
+ ?int $maxPages = null,
+ ?bool $pages = null,
+ ?bool $blocks = null,
+ ?bool $pageMarkers = null,
+ ): self {
+ return new self($mode, $maxPages, $pages, $blocks, $pageMarkers);
+ }
+
+ /** @return array<string, mixed> */
+ public function toArray(): array
+ {
+ return array_filter([
+ 'type' => 'pdf',
+ 'mode' => $this->mode,
+ 'maxPages' => $this->maxPages,
+ 'pages' => $this->pages,
+ 'blocks' => $this->blocks,
+ 'pageMarkers' => $this->pageMarkers,
+ ], fn (mixed $v): bool => $v !== null);
+ }
+
+ public function getMode(): ?string
+ {
+ return $this->mode;
+ }
+
+ public function getMaxPages(): ?int
+ {
+ return $this->maxPages;
+ }
+
+ public function getPages(): ?bool
+ {
+ return $this->pages;
+ }
+
+ public function getBlocks(): ?bool
+ {
+ return $this->blocks;
+ }
+
+ public function getPageMarkers(): ?bool
+ {
+ return $this->pageMarkers;
+ }
+}
diff --git a/apps/php-sdk/src/Models/ParseOptions.php b/apps/php-sdk/src/Models/ParseOptions.php
index 06c14db89..dc8a7396a 100644
--- a/apps/php-sdk/src/Models/ParseOptions.php
+++ b/apps/php-sdk/src/Models/ParseOptions.php
@@ -31,7 +31,7 @@ final class ParseOptions
* @param array<string, string>|null $headers
* @param list<string>|null $includeTags
* @param list<string>|null $excludeTags
- * @param list<mixed>|null $parsers
+ * @param list<string|PDFParser|array<string, mixed>>|null $parsers
* @param AuditMetadata|null $auditMetadata
*/
private function __construct(
@@ -56,7 +56,7 @@ final class ParseOptions
* @param array<string, string>|null $headers
* @param list<string>|null $includeTags
* @param list<string>|null $excludeTags
- * @param list<mixed>|null $parsers
+ * @param list<string|PDFParser|array<string, mixed>>|null $parsers
* @param AuditMetadata|null $auditMetadata
*/
public static function with(
@@ -134,7 +134,10 @@ final class ParseOptions
'excludeTags' => $this->excludeTags,
'onlyMainContent' => $this->onlyMainContent,
'timeout' => $this->timeout,
- 'parsers' => $this->parsers,
+ 'parsers' => $this->parsers === null ? null : array_map(
+ fn (mixed $parser): mixed => $parser instanceof PDFParser ? $parser->toArray() : $parser,
+ $this->parsers,
+ ),
'skipTlsVerification' => $this->skipTlsVerification,
'removeBase64Images' => $this->removeBase64Images,
'blockAds' => $this->blockAds,
@@ -210,7 +213,7 @@ final class ParseOptions
return $this->timeout;
}
- /** @return list<mixed>|null */
+ /** @return list<string|PDFParser|array<string, mixed>>|null */
public function getParsers(): ?array
{
return $this->parsers;
diff --git a/apps/php-sdk/src/Models/ScrapeOptions.php b/apps/php-sdk/src/Models/ScrapeOptions.php
index 5cc3ad42b..5b35b4372 100644
--- a/apps/php-sdk/src/Models/ScrapeOptions.php
+++ b/apps/php-sdk/src/Models/ScrapeOptions.php
@@ -11,7 +11,7 @@ final class ScrapeOptions
* @param array<string, string>|null $headers
* @param list<string>|null $includeTags
* @param list<string>|null $excludeTags
- * @param list<mixed>|null $parsers
+ * @param list<string|PDFParser|array<string, mixed>>|null $parsers
* @param list<array<string, mixed>>|null $actions
* @param AuditMetadata|null $auditMetadata
*/
@@ -48,7 +48,7 @@ final class ScrapeOptions
* @param array<string, string>|null $headers
* @param list<string>|null $includeTags
* @param list<string>|null $excludeTags
- * @param list<mixed>|null $parsers
+ * @param list<string|PDFParser|array<string, mixed>>|null $parsers
* @param list<array<string, mixed>>|null $actions
* @param array<string, string>|null $profile
* @param AuditMetadata|null $auditMetadata
@@ -115,7 +115,10 @@ final class ScrapeOptions
'timeout' => $this->timeout,
'waitFor' => $this->waitFor,
'mobile' => $this->mobile,
- 'parsers' => $this->parsers,
+ 'parsers' => $this->parsers === null ? null : array_map(
+ fn (mixed $parser): mixed => $parser instanceof PDFParser ? $parser->toArray() : $parser,
+ $this->parsers,
+ ),
'actions' => $this->actions,
'location' => $this->location?->toArray(),
'skipTlsVerification' => $this->skipTlsVerification,
@@ -191,7 +194,7 @@ final class ScrapeOptions
return $this->redactPII;
}
- /** @return list<mixed>|null */
+ /** @return list<string|PDFParser|array<string, mixed>>|null */
public function getParsers(): ?array
{
return $this->parsers;
diff --git a/apps/php-sdk/src/Version.php b/apps/php-sdk/src/Version.php
index 15e2cf996..82890da06 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.12.0';
+ public const SDK_VERSION = '1.13.0';
}
diff --git a/apps/php-sdk/tests/Unit/ModelsTest.php b/apps/php-sdk/tests/Unit/ModelsTest.php
index 8a11fd0c6..30b0fa878 100644
--- a/apps/php-sdk/tests/Unit/ModelsTest.php
+++ b/apps/php-sdk/tests/Unit/ModelsTest.php
@@ -14,6 +14,7 @@ use Firecrawl\Models\AgentOptions;
use Firecrawl\Models\AuditMetadata;
use Firecrawl\Models\MapOptions;
use Firecrawl\Models\ParseOptions;
+use Firecrawl\Models\PDFParser;
use Firecrawl\Models\QueryFormat;
use Firecrawl\Models\QuestionFormat;
use Firecrawl\Models\ScrapeOptions;
@@ -361,6 +362,20 @@ it('preserves positional integration in ScrapeOptions::with', function (): void
]);
});
+it('serializes PDF parser pageMarkers in ScrapeOptions', function (): void {
+ $options = ScrapeOptions::with(
+ parsers: [PDFParser::with(mode: 'auto', pages: true, blocks: true, pageMarkers: true)],
+ );
+
+ expect($options->toArray()['parsers'][0])->toMatchArray([
+ 'type' => 'pdf',
+ 'mode' => 'auto',
+ 'pages' => true,
+ 'blocks' => true,
+ 'pageMarkers' => true,
+ ]);
+});
+
it('serializes lockdown in ScrapeOptions', function (): void {
$options = ScrapeOptions::with(
lockdown: true,
diff --git a/apps/python-sdk/firecrawl/__init__.py b/apps/python-sdk/firecrawl/__init__.py
index c4babac4c..ef319169f 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.37.1"
+__version__ = "4.38.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_validation.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_validation.py
index 1f9c6f984..24d1e0bc1 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
@@ -390,8 +390,8 @@ class TestPrepareScrapeOptions:
assert result["parsers"][0]["maxPages"] == 5
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)
+ """PDF parser blocks, pages, and page_markers are forwarded to the API."""
+ parser = PDFParser(mode="auto", pages=True, blocks=True, page_markers=True)
options = ScrapeOptions(parsers=[parser])
result = prepare_scrape_options(options)
@@ -401,8 +401,16 @@ class TestPrepareScrapeOptions:
"mode": "auto",
"pages": True,
"blocks": True,
+ "pageMarkers": True,
}
+ markers_options = ScrapeOptions(
+ parsers=[{"type": "pdf", "page_markers": True}]
+ )
+ markers_result = prepare_scrape_options(markers_options)
+ assert markers_result["parsers"][0]["pageMarkers"] is True
+ assert "page_markers" not in markers_result["parsers"][0]
+
dict_options = ScrapeOptions(
parsers=[{"type": "pdf", "page_markdown": True, "blocks": True}]
)
diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.py
index 4eeab4e9f..6690496ab 100644
--- a/apps/python-sdk/firecrawl/v2/types.py
+++ b/apps/python-sdk/firecrawl/v2/types.py
@@ -1671,6 +1671,11 @@ class PDFParser(BaseModel):
max_pages: Optional[int] = None
pages: Optional[bool] = None
blocks: Optional[bool] = None
+ # Join PDF pages in document markdown with `\n\n---\n\n<!-- page N -->\n\n`
+ # (N = 1-based physical page of the content that follows). Markers appear
+ # between pages only, and numbering may skip pages merged by cross-page
+ # stitching β€” use `pages=True` when every physical page is needed.
+ page_markers: Optional[bool] = None
@model_validator(mode="before")
@classmethod
diff --git a/apps/python-sdk/firecrawl/v2/utils/validation.py b/apps/python-sdk/firecrawl/v2/utils/validation.py
index f88dfa06e..b8c4bc05a 100644
--- a/apps/python-sdk/firecrawl/v2/utils/validation.py
+++ b/apps/python-sdk/firecrawl/v2/utils/validation.py
@@ -795,12 +795,16 @@ def prepare_scrape_options(options: Optional[ScrapeOptions]) -> Optional[Dict[st
parser_data.setdefault("pages", parser_data.pop("page_markdown"))
if "pageMarkdown" in parser_data:
parser_data.setdefault("pages", parser_data.pop("pageMarkdown"))
+ if "page_markers" in parser_data:
+ parser_data["pageMarkers"] = parser_data.pop("page_markers")
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_markers" in parser_data:
+ parser_data["pageMarkers"] = parser_data.pop("page_markers")
converted_parsers.append(parser_data)
scrape_data["parsers"] = converted_parsers
elif key == "location":
diff --git a/apps/ruby-sdk/lib/firecrawl.rb b/apps/ruby-sdk/lib/firecrawl.rb
index 3ba8cd0dd..b6398d36c 100644
--- a/apps/ruby-sdk/lib/firecrawl.rb
+++ b/apps/ruby-sdk/lib/firecrawl.rb
@@ -4,6 +4,7 @@ require_relative "firecrawl/version"
require_relative "firecrawl/errors"
require_relative "firecrawl/http_client"
require_relative "firecrawl/models/query_format"
+require_relative "firecrawl/models/pdf_parser"
require_relative "firecrawl/models/product_profile"
require_relative "firecrawl/models/menu_profile"
require_relative "firecrawl/models/document"
diff --git a/apps/ruby-sdk/lib/firecrawl/models/parse_options.rb b/apps/ruby-sdk/lib/firecrawl/models/parse_options.rb
index cb7310e95..8892a5210 100644
--- a/apps/ruby-sdk/lib/firecrawl/models/parse_options.rb
+++ b/apps/ruby-sdk/lib/firecrawl/models/parse_options.rb
@@ -35,7 +35,7 @@ module Firecrawl
"excludeTags" => exclude_tags,
"onlyMainContent" => only_main_content,
"timeout" => timeout,
- "parsers" => parsers,
+ "parsers" => parsers&.map { |parser| parser.respond_to?(:to_h) ? parser.to_h : parser },
"skipTlsVerification" => skip_tls_verification,
"removeBase64Images" => remove_base64_images,
"blockAds" => block_ads,
diff --git a/apps/ruby-sdk/lib/firecrawl/models/pdf_parser.rb b/apps/ruby-sdk/lib/firecrawl/models/pdf_parser.rb
new file mode 100644
index 000000000..7fec9afd3
--- /dev/null
+++ b/apps/ruby-sdk/lib/firecrawl/models/pdf_parser.rb
@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Firecrawl
+ module Models
+ # PDF parser configuration for use in ScrapeOptions / ParseOptions parsers.
+ class PDFParser
+ attr_reader :mode, :max_pages, :pages, :blocks, :page_markers
+
+ def initialize(mode: nil, max_pages: nil, pages: nil, blocks: nil, page_markers: nil)
+ @mode = mode
+ @max_pages = max_pages
+ @pages = pages
+ @blocks = blocks
+ @page_markers = page_markers
+ end
+
+ def to_h
+ {
+ "type" => "pdf",
+ "mode" => mode,
+ "maxPages" => max_pages,
+ "pages" => pages,
+ "blocks" => blocks,
+ "pageMarkers" => page_markers,
+ }.compact
+ end
+
+ def type
+ "pdf"
+ end
+ end
+ end
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rb b/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rb
index 20c050555..10049e813 100644
--- a/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rb
+++ b/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rb
@@ -31,7 +31,7 @@ module Firecrawl
"timeout" => timeout,
"waitFor" => wait_for,
"mobile" => mobile,
- "parsers" => parsers,
+ "parsers" => parsers&.map { |parser| parser.respond_to?(:to_h) ? parser.to_h : parser },
"actions" => actions,
"location" => location.is_a?(Hash) ? location : location&.to_h,
"skipTlsVerification" => skip_tls_verification,
diff --git a/apps/ruby-sdk/lib/firecrawl/version.rb b/apps/ruby-sdk/lib/firecrawl/version.rb
index ad3564572..b14207c3e 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.13.0"
+ VERSION = "1.14.0"
end
diff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rb
index 644cf0c66..5148e8f98 100644
--- a/apps/ruby-sdk/test/firecrawl/client_test.rb
+++ b/apps/ruby-sdk/test/firecrawl/client_test.rb
@@ -135,6 +135,38 @@ class ClientTest < Minitest::Test
assert_equal "title", doc.blocks[0]["items"][0]["type"]
end
+ def test_scrape_serializes_pdf_parser_page_markers
+ stub_request(:post, "#{BASE_URL}/v2/scrape")
+ .with { |req|
+ body = JSON.parse(req.body)
+ body["parsers"] == [{
+ "type" => "pdf",
+ "mode" => "auto",
+ "pages" => true,
+ "blocks" => true,
+ "pageMarkers" => true
+ }]
+ }
+ .to_return(
+ status: 200,
+ body: JSON.generate(data: { markdown: "# Cover" }),
+ headers: { "Content-Type" => "application/json" }
+ )
+
+ options = Firecrawl::Models::ScrapeOptions.new(
+ parsers: [
+ Firecrawl::Models::PDFParser.new(
+ mode: "auto",
+ pages: true,
+ blocks: true,
+ page_markers: true
+ )
+ ]
+ )
+ doc = @client.scrape("https://example.com/report.pdf", options)
+ assert_equal "# Cover", doc.markdown
+ end
+
def test_scrape_with_options
stub_request(:post, "#{BASE_URL}/v2/scrape")
.with { |req| body = JSON.parse(req.body); body["formats"] == ["markdown", "html"] && body["onlyMainContent"] == true }
diff --git a/apps/rust-sdk/CHANGELOG.md b/apps/rust-sdk/CHANGELOG.md
index 099a60669..4a1853b4f 100644
--- a/apps/rust-sdk/CHANGELOG.md
+++ b/apps/rust-sdk/CHANGELOG.md
@@ -1,5 +1,12 @@
## CHANGELOG
+## [2.16.0] - 2026-08-21
+
+### Added
+
+- Added `ParserConfig::Pdf.page_markers` to join PDF pages in
+ `document.markdown` with `\n\n---\n\n<!-- page N -->\n\n`.
+
## [2.15.0] - 2026-08-21
### Added
diff --git a/apps/rust-sdk/Cargo.lock b/apps/rust-sdk/Cargo.lock
index 35d3e537c..1aa48bbb1 100644
--- a/apps/rust-sdk/Cargo.lock
+++ b/apps/rust-sdk/Cargo.lock
@@ -250,7 +250,7 @@ checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
[[package]]
name = "firecrawl"
-version = "2.15.0"
+version = "2.16.0"
dependencies = [
"mockito",
"reqwest",
diff --git a/apps/rust-sdk/Cargo.toml b/apps/rust-sdk/Cargo.toml
index a86a81885..a5b664721 100644
--- a/apps/rust-sdk/Cargo.toml
+++ b/apps/rust-sdk/Cargo.toml
@@ -1,6 +1,6 @@
[package]
name = "firecrawl"
-version = "2.15.0"
+version = "2.16.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 29374e414..9372dcbd9 100644
--- a/apps/rust-sdk/src/scrape.rs
+++ b/apps/rust-sdk/src/scrape.rs
@@ -123,6 +123,9 @@ pub enum ParserConfig {
pages: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
blocks: Option<bool>,
+ /// Join PDF pages in document markdown with `\n\n---\n\n<!-- page N -->\n\n`.
+ #[serde(rename = "pageMarkers", skip_serializing_if = "Option::is_none")]
+ page_markers: Option<bool>,
},
}
@@ -533,6 +536,7 @@ mod tests {
max_pages: None,
pages: Some(true),
blocks: Some(true),
+ page_markers: Some(true),
}]),
..Default::default()
};
@@ -544,7 +548,8 @@ mod tests {
"type": "pdf",
"mode": "auto",
"pages": true,
- "blocks": true
+ "blocks": true,
+ "pageMarkers": true
})
);
}