Skip to content

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

feat(sdks): add parsers[].blocks for typed PDF layout blocks (#4351)

Abimael Martellb3a6c73e463a
diff --git a/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs b/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs
index 3f95992ca..da08b5638 100644
--- a/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs
+++ b/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs
@@ -145,6 +145,49 @@ public class ModelsTests
Assert.Null(doc.Warning);
}
+ [Fact]
+ public void Document_DeserializesBlocksCorrectly()
+ {
+ var json = """
+ {
+ "markdown": "# Annual Report 2025",
+ "blocks": [
+ {
+ "pageNumber": 1,
+ "width": 1700,
+ "height": 2200,
+ "status": "ok",
+ "items": [
+ {
+ "id": "p1.b0",
+ "type": "title",
+ "label": "doc_title",
+ "bbox": [0.118, 0.054, 0.882, 0.092],
+ "content": "# Annual Report 2025",
+ "markdownSpan": [0, 21],
+ "readingOrder": 0,
+ "source": "native_text",
+ "confidence": { "layout": 0.97, "ocr": null }
+ }
+ ]
+ }
+ ]
+ }
+ """;
+
+ var doc = JsonSerializer.Deserialize<Document>(json, JsonOptions);
+ Assert.NotNull(doc);
+ Assert.Equal("# Annual Report 2025", doc.Markdown);
+ Assert.NotNull(doc.Blocks);
+ Assert.Single(doc.Blocks);
+ Assert.Equal(1, doc.Blocks[0].PageNumber);
+ Assert.Equal("ok", doc.Blocks[0].Status);
+ Assert.Single(doc.Blocks[0].Items);
+ Assert.Equal("title", doc.Blocks[0].Items[0].Type);
+ Assert.Equal(0, doc.Blocks[0].Items[0].ReadingOrder);
+ Assert.Equal(0.97, doc.Blocks[0].Items[0].Confidence?.Layout);
+ }
+
[Fact]
public void Document_DeserializesProductCorrectly()
{
diff --git a/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj b/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj
index 01f2feea9..a3b918db3 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.10.1</Version>
+ <Version>1.11.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 52c02acc2..03b797d94 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 7aa7ef69a..6852cb52c 100644
--- a/apps/dot-net-sdk/Firecrawl/Models/Document.cs
+++ b/apps/dot-net-sdk/Firecrawl/Models/Document.cs
@@ -63,4 +63,10 @@ public class Document
[JsonPropertyName("menu")]
public MenuProfile? Menu { get; set; }
+
+ /// <summary>
+ /// Typed PDF layout blocks, present only when parsers[].blocks is true.
+ /// </summary>
+ [JsonPropertyName("blocks")]
+ public List<PdfPageBlocks>? Blocks { get; set; }
}
diff --git a/apps/dot-net-sdk/Firecrawl/Models/PdfBlocks.cs b/apps/dot-net-sdk/Firecrawl/Models/PdfBlocks.cs
new file mode 100644
index 000000000..cca587b8f
--- /dev/null
+++ b/apps/dot-net-sdk/Firecrawl/Models/PdfBlocks.cs
@@ -0,0 +1,69 @@
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Layout and OCR confidence scores for a PDF block.
+/// </summary>
+public class PdfBlockConfidence
+{
+ [JsonPropertyName("layout")]
+ public double? Layout { get; set; }
+
+ [JsonPropertyName("ocr")]
+ public double? Ocr { get; set; }
+}
+
+/// <summary>
+/// A typed PDF layout block (bounding box, type, reading order).
+/// </summary>
+public class PdfBlockItem
+{
+ [JsonPropertyName("id")]
+ public string Id { get; set; } = "";
+
+ [JsonPropertyName("type")]
+ public string Type { get; set; } = "";
+
+ [JsonPropertyName("label")]
+ public string? Label { get; set; }
+
+ [JsonPropertyName("bbox")]
+ public List<double>? BBox { get; set; }
+
+ [JsonPropertyName("content")]
+ public string Content { get; set; } = "";
+
+ [JsonPropertyName("markdownSpan")]
+ public List<int>? MarkdownSpan { get; set; }
+
+ [JsonPropertyName("readingOrder")]
+ public int ReadingOrder { get; set; }
+
+ [JsonPropertyName("source")]
+ public string? Source { get; set; }
+
+ [JsonPropertyName("confidence")]
+ public PdfBlockConfidence? Confidence { get; set; }
+}
+
+/// <summary>
+/// Typed layout blocks for a single PDF page.
+/// </summary>
+public class PdfPageBlocks
+{
+ [JsonPropertyName("pageNumber")]
+ public int PageNumber { get; set; }
+
+ [JsonPropertyName("width")]
+ public double? Width { get; set; }
+
+ [JsonPropertyName("height")]
+ public double? Height { get; set; }
+
+ [JsonPropertyName("status")]
+ public string Status { get; set; } = "";
+
+ [JsonPropertyName("items")]
+ public List<PdfBlockItem> Items { get; set; } = [];
+}
diff --git a/apps/go-sdk/models.go b/apps/go-sdk/models.go
index 62f826fba..7408ecb17 100644
--- a/apps/go-sdk/models.go
+++ b/apps/go-sdk/models.go
@@ -24,6 +24,45 @@ type Document struct {
Branding map[string]interface{} `json:"branding,omitempty"`
Product *ProductProfile `json:"product,omitempty"`
Menu *MenuProfile `json:"menu,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"`
+}
+
+// PdfBlockConfidence is layout and OCR confidence for a PDF block.
+type PdfBlockConfidence struct {
+ Layout *float64 `json:"layout"`
+ OCR *float64 `json:"ocr"`
+}
+
+// PdfBlockItem is a typed PDF layout block.
+type PdfBlockItem struct {
+ ID string `json:"id"`
+ Type string `json:"type"`
+ Label *string `json:"label"`
+ BBox []float64 `json:"bbox"`
+ Content string `json:"content"`
+ MarkdownSpan []int `json:"markdownSpan"`
+ ReadingOrder int `json:"readingOrder"`
+ Source *string `json:"source"`
+ Confidence PdfBlockConfidence `json:"confidence"`
+}
+
+// PdfPageBlocks is the typed layout for a single PDF page.
+type PdfPageBlocks struct {
+ PageNumber int `json:"pageNumber"`
+ Width *float64 `json:"width"`
+ Height *float64 `json:"height"`
+ Status string `json:"status"`
+ Items []PdfBlockItem `json:"items"`
}
// ProductProfile represents structured product data extracted from a page
diff --git a/apps/go-sdk/options_test.go b/apps/go-sdk/options_test.go
index f7f230658..d7679d59c 100644
--- a/apps/go-sdk/options_test.go
+++ b/apps/go-sdk/options_test.go
@@ -64,6 +64,65 @@ func TestScrapeOptionsPreservesStringFormats(t *testing.T) {
}
}
+func TestScrapeOptionsSerializesPDFParserBlocks(t *testing.T) {
+ blocks := true
+ payload, err := json.Marshal(ScrapeOptions{
+ Parsers: []interface{}{
+ PDFParser{Type: "pdf", Mode: "auto", Blocks: &blocks},
+ },
+ })
+ if err != nil {
+ t.Fatalf("Marshal ScrapeOptions: %v", err)
+ }
+
+ want := `"parsers":[{"type":"pdf","mode":"auto","blocks":true}]`
+ if !strings.Contains(string(payload), want) {
+ t.Fatalf("serialized parsers = %s, want to contain %s", payload, want)
+ }
+}
+
+func TestDocumentDeserializesBlocks(t *testing.T) {
+ raw := []byte(`{
+ "markdown": "# Annual Report 2025",
+ "blocks": [{
+ "pageNumber": 1,
+ "width": 1700,
+ "height": 2200,
+ "status": "ok",
+ "items": [{
+ "id": "p1.b0",
+ "type": "title",
+ "label": "doc_title",
+ "bbox": [0.118, 0.054, 0.882, 0.092],
+ "content": "# Annual Report 2025",
+ "markdownSpan": [0, 21],
+ "readingOrder": 0,
+ "source": "native_text",
+ "confidence": {"layout": 0.97, "ocr": null}
+ }]
+ }]
+ }`)
+
+ var doc Document
+ if err := json.Unmarshal(raw, &doc); err != nil {
+ t.Fatalf("Unmarshal Document: %v", err)
+ }
+ if len(doc.Blocks) != 1 {
+ t.Fatalf("blocks len = %d, want 1", len(doc.Blocks))
+ }
+ page := doc.Blocks[0]
+ if page.PageNumber != 1 || page.Status != "ok" || len(page.Items) != 1 {
+ t.Fatalf("page = %+v", page)
+ }
+ item := page.Items[0]
+ if item.ID != "p1.b0" || item.Type != "title" || item.ReadingOrder != 0 {
+ t.Fatalf("item = %+v", item)
+ }
+ if item.Confidence.Layout == nil || *item.Confidence.Layout != 0.97 {
+ t.Fatalf("layout confidence = %+v", item.Confidence.Layout)
+ }
+}
+
func TestScrapeOptionsSerializesRedactPII(t *testing.T) {
payload, err := json.Marshal(ScrapeOptions{
RedactPII: Bool(true),
diff --git a/apps/go-sdk/version.go b/apps/go-sdk/version.go
index 64a7295db..63c538b9b 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.9.1"
+const Version = "1.10.0"
diff --git a/apps/java-sdk/build.gradle.kts b/apps/java-sdk/build.gradle.kts
index 19f377982..465f54062 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.12.1"
+version = "1.13.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 e80852fc5..6c6598f1c 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 48b10b180..6d5a34e9b 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;
+ /** Typed PDF layout blocks, present only when parsers[].blocks is true. */
+ private List<PdfPageBlocks> blocks;
public String getMarkdown() { return markdown; }
public String getHtml() { return html; }
@@ -51,6 +53,7 @@ public class Document {
public Map<String, Object> getBranding() { return branding; }
public Product getProduct() { return product; }
public Menu getMenu() { return menu; }
+ public List<PdfPageBlocks> getBlocks() { return blocks; }
@Override
public String toString() {
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/PdfBlockConfidence.java b/apps/java-sdk/src/main/java/com/firecrawl/models/PdfBlockConfidence.java
new file mode 100644
index 000000000..32f1a4889
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/PdfBlockConfidence.java
@@ -0,0 +1,21 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+
+/**
+ * Layout and OCR confidence scores for a PDF layout block.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class PdfBlockConfidence {
+
+ private Double layout;
+ private Double ocr;
+
+ public Double getLayout() { return layout; }
+ public Double getOcr() { return ocr; }
+
+ @Override
+ public String toString() {
+ return "PdfBlockConfidence{layout=" + layout + ", ocr=" + ocr + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/PdfBlockItem.java b/apps/java-sdk/src/main/java/com/firecrawl/models/PdfBlockItem.java
new file mode 100644
index 000000000..5e74eadab
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/PdfBlockItem.java
@@ -0,0 +1,36 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import java.util.List;
+
+/**
+ * A typed PDF layout block (bounding box, type, reading order).
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class PdfBlockItem {
+
+ private String id;
+ private String type;
+ private String label;
+ private List<Double> bbox;
+ private String content;
+ private List<Integer> markdownSpan;
+ private int readingOrder;
+ private String source;
+ private PdfBlockConfidence confidence;
+
+ public String getId() { return id; }
+ public String getType() { return type; }
+ public String getLabel() { return label; }
+ public List<Double> getBbox() { return bbox; }
+ public String getContent() { return content; }
+ public List<Integer> getMarkdownSpan() { return markdownSpan; }
+ public int getReadingOrder() { return readingOrder; }
+ public String getSource() { return source; }
+ public PdfBlockConfidence getConfidence() { return confidence; }
+
+ @Override
+ public String toString() {
+ return "PdfBlockItem{id=" + id + ", type=" + type + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/PdfPageBlocks.java b/apps/java-sdk/src/main/java/com/firecrawl/models/PdfPageBlocks.java
new file mode 100644
index 000000000..7d2bbf36b
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/PdfPageBlocks.java
@@ -0,0 +1,29 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import java.util.List;
+
+/**
+ * Typed layout blocks for a single PDF page, returned when
+ * {@code parsers} includes {@code {type: "pdf", blocks: true}}.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class PdfPageBlocks {
+
+ private int pageNumber;
+ private Double width;
+ private Double height;
+ private String status;
+ private List<PdfBlockItem> items;
+
+ public int getPageNumber() { return pageNumber; }
+ public Double getWidth() { return width; }
+ public Double getHeight() { return height; }
+ public String getStatus() { return status; }
+ public List<PdfBlockItem> getItems() { return items; }
+
+ @Override
+ public String toString() {
+ return "PdfPageBlocks{pageNumber=" + pageNumber + ", status=" + status + "}";
+ }
+}
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 756001373..9b2e54a42 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}). */
+ /** Parsers to use (e.g., "pdf" or {"type": "pdf", "maxPages": 10, "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 8ef13cd6c..fd010ed98 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,42 @@ class FirecrawlClientTest {
);
}
+ @Test
+ void testDocumentDeserializesBlocks() throws Exception {
+ String json = "{\"markdown\":\"# Annual Report 2025\",\"blocks\":[{"
+ + "\"pageNumber\":1,\"width\":1700,\"height\":2200,\"status\":\"ok\","
+ + "\"items\":[{\"id\":\"p1.b0\",\"type\":\"title\",\"label\":\"doc_title\","
+ + "\"bbox\":[0.118,0.054,0.882,0.092],\"content\":\"# Annual Report 2025\","
+ + "\"markdownSpan\":[0,21],\"readingOrder\":0,\"source\":\"native_text\","
+ + "\"confidence\":{\"layout\":0.97,\"ocr\":null}}]}]}";
+
+ 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.getBlocks());
+ assertEquals(1, doc.getBlocks().size());
+
+ PdfPageBlocks page = doc.getBlocks().get(0);
+ assertEquals(1, page.getPageNumber());
+ assertEquals(1700.0, page.getWidth());
+ assertEquals(2200.0, page.getHeight());
+ assertEquals("ok", page.getStatus());
+ assertEquals(1, page.getItems().size());
+
+ PdfBlockItem item = page.getItems().get(0);
+ assertEquals("p1.b0", item.getId());
+ assertEquals("title", item.getType());
+ assertEquals("doc_title", item.getLabel());
+ assertEquals(List.of(0.118, 0.054, 0.882, 0.092), item.getBbox());
+ assertEquals("# Annual Report 2025", item.getContent());
+ assertEquals(List.of(0, 21), item.getMarkdownSpan());
+ assertEquals(0, item.getReadingOrder());
+ assertEquals("native_text", item.getSource());
+ assertEquals(0.97, item.getConfidence().getLayout());
+ assertNull(item.getConfidence().getOcr());
+ }
+
@Test
void testDocumentDeserializesMenu() throws Exception {
String json = "{\"menu\":{"
diff --git a/apps/js-sdk/firecrawl/package.json b/apps/js-sdk/firecrawl/package.json
index 139368a82..87b7ef629 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.32.2",
+ "version": "4.33.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 bcac9d4c4..ae349dc07 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,6 +89,19 @@ describe("v2 utils: validation", () => {
expect(options.parsers).toEqual(before);
});
+ test("ensureValidScrapeOptions: leaves PDF parser blocks option untouched", () => {
+ const options = {
+ parsers: [{ type: "pdf", mode: "auto", blocks: true, pageMarkdown: true }],
+ } as any;
+ expect(() => ensureValidScrapeOptions(options)).not.toThrow();
+ expect(options.parsers[0]).toEqual({
+ type: "pdf",
+ mode: "auto",
+ blocks: true,
+ pageMarkdown: true,
+ });
+ });
+
test("ensureValidFormats: detects mistaken use of zod schema.shape", () => {
const schema = z.object({ title: z.string(), count: z.number() });
// User mistakenly passes schema.shape instead of schema
diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.ts
index 128f99bb3..1f840d35b 100644
--- a/apps/js-sdk/firecrawl/src/v2/types.ts
+++ b/apps/js-sdk/firecrawl/src/v2/types.ts
@@ -187,6 +187,41 @@ export interface AuditMetadata {
username: string;
}
+export type PDFParser = {
+ type: "pdf";
+ mode?: "fast" | "auto" | "ocr";
+ maxPages?: number;
+ /** Include physical per-page markdown alongside document markdown. */
+ pageMarkdown?: boolean;
+ /** Include per-page typed layout blocks (bounding boxes, block types, reading order). */
+ blocks?: boolean;
+};
+
+export interface PdfBlockConfidence {
+ layout: number | null;
+ ocr: number | null;
+}
+
+export interface PdfBlockItem {
+ id: string;
+ type: string;
+ label: string | null;
+ bbox: [number, number, number, number] | null;
+ content: string;
+ markdownSpan: [number, number] | null;
+ readingOrder: number;
+ source: string | null;
+ confidence: PdfBlockConfidence;
+}
+
+export interface PdfPageBlocks {
+ pageNumber: number;
+ width: number | null;
+ height: number | null;
+ status: string;
+ items: PdfBlockItem[];
+}
+
export interface ScrapeOptions {
formats?: FormatOption[];
headers?: Record<string, string>;
@@ -196,9 +231,7 @@ export interface ScrapeOptions {
timeout?: number;
waitFor?: number;
mobile?: boolean;
- parsers?: Array<
- string | { type: "pdf"; mode?: "fast" | "auto" | "ocr"; maxPages?: number }
- >;
+ parsers?: Array<string | PDFParser>;
actions?: ActionOption[];
location?: LocationConfig;
skipTlsVerification?: boolean;
@@ -647,6 +680,8 @@ export interface Document {
branding?: BrandingProfile;
product?: ProductProfile;
menu?: MenuProfile;
+ /** Typed PDF layout blocks, present only when `parsers[].blocks` is true. */
+ blocks?: PdfPageBlocks[];
}
// Pagination configuration for auto-fetching pages from v2 endpoints that return a `next` URL
diff --git a/apps/php-sdk/CHANGELOG.md b/apps/php-sdk/CHANGELOG.md
index 056885888..34e8fea85 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.11.0] - 2026-08-19
+
+### Added
+- PDF parser `blocks` option and `Document::getBlocks()` for per-page typed
+ layout blocks (bounding boxes, block types, reading order).
+
## [1.9.0] - 2026-07-10
### Added
diff --git a/apps/php-sdk/src/Models/Document.php b/apps/php-sdk/src/Models/Document.php
index d190ee106..49187755e 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 $blocks
*/
public function __construct(
private readonly ?string $markdown = null,
@@ -36,6 +37,7 @@ final class Document
private readonly ?array $branding = null,
private readonly ?Product $product = null,
private readonly ?Menu $menu = null,
+ private readonly ?array $blocks = null,
) {}
/** @param array<string, mixed> $data */
@@ -66,6 +68,9 @@ final class Document
menu: isset($data['menu']) && is_array($data['menu'])
? Menu::fromArray($data['menu'])
: null,
+ blocks: isset($data['blocks']) && is_array($data['blocks'])
+ ? $data['blocks']
+ : null,
);
}
@@ -175,4 +180,14 @@ final class Document
{
return $this->menu;
}
+
+ /**
+ * Typed PDF layout blocks, present only when parsers[].blocks is true.
+ *
+ * @return list<array<string, mixed>>|null
+ */
+ public function getBlocks(): ?array
+ {
+ return $this->blocks;
+ }
}
diff --git a/apps/php-sdk/src/Version.php b/apps/php-sdk/src/Version.php
index 40f902912..bf594c79a 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.10.1';
+ public const SDK_VERSION = '1.11.0';
}
diff --git a/apps/php-sdk/tests/Unit/ModelsTest.php b/apps/php-sdk/tests/Unit/ModelsTest.php
index 9d0d5aba7..4301e4d63 100644
--- a/apps/php-sdk/tests/Unit/ModelsTest.php
+++ b/apps/php-sdk/tests/Unit/ModelsTest.php
@@ -103,6 +103,33 @@ it('preserves null creditsUsed in CrawlJob', function (): void {
expect($job->getCreditsUsed())->toBeNull();
});
+it('hydrates PDF blocks in Document', function (): void {
+ $doc = Document::fromArray([
+ 'markdown' => '# Annual Report 2025',
+ 'blocks' => [
+ [
+ 'pageNumber' => 1,
+ 'width' => 1700,
+ 'height' => 2200,
+ 'status' => 'ok',
+ 'items' => [
+ [
+ 'id' => 'p1.b0',
+ 'type' => 'title',
+ 'content' => '# Annual Report 2025',
+ 'readingOrder' => 0,
+ ],
+ ],
+ ],
+ ],
+ ]);
+
+ expect($doc->getMarkdown())->toBe('# Annual Report 2025');
+ expect($doc->getBlocks())->toHaveCount(1);
+ expect($doc->getBlocks()[0]['pageNumber'])->toBe(1);
+ expect($doc->getBlocks()[0]['items'][0]['type'])->toBe('title');
+});
+
it('hydrates video URL in Document', function (): void {
$doc = Document::fromArray([
'markdown' => '# Video',
diff --git a/apps/python-sdk/firecrawl/__init__.py b/apps/python-sdk/firecrawl/__init__.py
index b58024270..7c31532c1 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.35.1"
+__version__ = "4.36.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
new file mode 100644
index 000000000..c0293e8d4
--- /dev/null
+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_document_blocks.py
@@ -0,0 +1,50 @@
+from firecrawl.v2.types import Document, PdfPageBlocks
+from firecrawl.v2.utils.normalize import normalize_document_input
+
+
+class TestDocumentBlocks:
+ def test_blocks_hydrate_from_api_camel_case(self):
+ raw = {
+ "markdown": "# Annual Report 2025",
+ "blocks": [
+ {
+ "pageNumber": 1,
+ "width": 1700,
+ "height": 2200,
+ "status": "ok",
+ "items": [
+ {
+ "id": "p1.b0",
+ "type": "title",
+ "label": "doc_title",
+ "bbox": [0.118, 0.054, 0.882, 0.092],
+ "content": "# Annual Report 2025",
+ "markdownSpan": [0, 21],
+ "readingOrder": 0,
+ "source": "native_text",
+ "confidence": {"layout": 0.97, "ocr": None},
+ }
+ ],
+ }
+ ],
+ }
+
+ doc = Document(**normalize_document_input(raw))
+ assert doc.blocks is not None
+ assert len(doc.blocks) == 1
+ page = doc.blocks[0]
+ assert isinstance(page, PdfPageBlocks)
+ assert page.page_number == 1
+ assert page.width == 1700
+ assert page.status == "ok"
+ item = page.items[0]
+ assert item.id == "p1.b0"
+ assert item.type == "title"
+ assert item.markdown_span == [0, 21]
+ assert item.reading_order == 0
+ assert item.confidence.layout == 0.97
+ assert item.confidence.ocr is None
+
+ def test_blocks_absent_when_not_requested(self):
+ doc = Document(**normalize_document_input({"markdown": "# Hello"}))
+ assert doc.blocks is None
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 2e9ebc1fd..f4bec29cf 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,6 +389,28 @@ 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)
+ options = ScrapeOptions(parsers=[parser])
+
+ result = prepare_scrape_options(options)
+
+ assert result["parsers"][0] == {
+ "type": "pdf",
+ "mode": "auto",
+ "pageMarkdown": True,
+ "blocks": True,
+ }
+
+ dict_options = ScrapeOptions(
+ 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]["blocks"] is True
+ assert "page_markdown" not in dict_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."""
options = ScrapeOptions(min_age=1000, max_age=5000)
diff --git a/apps/python-sdk/firecrawl/types.py b/apps/python-sdk/firecrawl/types.py
index 79dc613fe..c1b647fab 100644
--- a/apps/python-sdk/firecrawl/types.py
+++ b/apps/python-sdk/firecrawl/types.py
@@ -12,6 +12,9 @@ from .v2.types import (
# Document types
Document,
DocumentMetadata,
+ PdfBlockConfidence,
+ PdfBlockItem,
+ PdfPageBlocks,
# Scrape types
ScrapeFormats,
@@ -67,6 +70,7 @@ from .v2.types import (
ScrapeAction,
ExecuteJavascriptAction,
PDFAction,
+ PDFParser,
# Usage types
QueueStatusResponse,
@@ -96,6 +100,9 @@ __all__ = [
# Document types
'Document',
'DocumentMetadata',
+ 'PdfBlockConfidence',
+ 'PdfBlockItem',
+ 'PdfPageBlocks',
# Scrape types
'ScrapeFormats',
@@ -152,6 +159,7 @@ __all__ = [
'ScrapeAction',
'ExecuteJavascriptAction',
'PDFAction',
+ 'PDFParser',
# Usage types
'QueueStatusResponse',
diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.py
index 096cecd1b..f4f1fcbe4 100644
--- a/apps/python-sdk/firecrawl/v2/types.py
+++ b/apps/python-sdk/firecrawl/v2/types.py
@@ -439,6 +439,43 @@ RedactPIIEntity = Literal[
]
+class PdfBlockConfidence(BaseModel):
+ """Layout and OCR confidence scores for a PDF block."""
+
+ model_config = {"extra": "allow", "populate_by_name": True}
+
+ layout: Optional[float] = None
+ ocr: Optional[float] = None
+
+
+class PdfBlockItem(BaseModel):
+ """A typed PDF layout block (bounding box, type, reading order)."""
+
+ model_config = {"extra": "allow", "populate_by_name": True}
+
+ id: str
+ type: str
+ label: Optional[str] = None
+ bbox: Optional[List[float]] = None
+ content: str
+ markdown_span: Optional[List[int]] = Field(default=None, alias="markdownSpan")
+ reading_order: int = Field(alias="readingOrder")
+ source: Optional[str] = None
+ confidence: PdfBlockConfidence
+
+
+class PdfPageBlocks(BaseModel):
+ """Typed layout blocks for a single PDF page."""
+
+ model_config = {"extra": "allow", "populate_by_name": True}
+
+ page_number: int = Field(alias="pageNumber")
+ width: Optional[float] = None
+ height: Optional[float] = None
+ status: str
+ items: List[PdfBlockItem] = Field(default_factory=list)
+
+
class Document(BaseModel):
"""A scraped document."""
@@ -461,6 +498,7 @@ class Document(BaseModel):
branding: Optional[BrandingProfile] = None
product: Optional[ProductProfile] = None
menu: Optional[MenuProfile] = None
+ blocks: Optional[List[PdfPageBlocks]] = None
@property
def metadata_typed(self) -> DocumentMetadata:
@@ -1618,6 +1656,8 @@ class PDFParser(BaseModel):
type: Literal["pdf"] = "pdf"
mode: Optional[Literal["fast", "auto", "ocr"]] = None
max_pages: Optional[int] = None
+ page_markdown: Optional[bool] = None
+ blocks: Optional[bool] = None
# Location types
diff --git a/apps/python-sdk/firecrawl/v2/utils/validation.py b/apps/python-sdk/firecrawl/v2/utils/validation.py
index ac87d8fb5..73c2a89c0 100644
--- a/apps/python-sdk/firecrawl/v2/utils/validation.py
+++ b/apps/python-sdk/firecrawl/v2/utils/validation.py
@@ -790,12 +790,16 @@ 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")
+ if "page_markdown" in parser_data:
+ parser_data["pageMarkdown"] = parser_data.pop("page_markdown")
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 b13c9cebe..219bd3062 100644
--- a/apps/ruby-sdk/lib/firecrawl/models/document.rb
+++ b/apps/ruby-sdk/lib/firecrawl/models/document.rb
@@ -7,7 +7,8 @@ module Firecrawl
attr_reader :markdown, :html, :raw_html, :json, :summary,
:metadata, :links, :images, :screenshot, :audio,
:video, :attributes, :actions, :answer, :highlights,
- :warning, :change_tracking, :branding, :product, :menu
+ :warning, :change_tracking, :branding, :product, :menu,
+ :blocks
def initialize(data)
@markdown = data["markdown"]
@@ -30,6 +31,7 @@ module Firecrawl
@branding = data["branding"]
@product = data["product"] && ProductProfile.new(data["product"])
@menu = data["menu"] && MenuProfile.new(data["menu"])
+ @blocks = data["blocks"]
end
def to_s
diff --git a/apps/ruby-sdk/lib/firecrawl/version.rb b/apps/ruby-sdk/lib/firecrawl/version.rb
index c53228978..ff07525b9 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.11.1"
+ VERSION = "1.12.0"
end
diff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rb
index 598635490..b93718c23 100644
--- a/apps/ruby-sdk/test/firecrawl/client_test.rb
+++ b/apps/ruby-sdk/test/firecrawl/client_test.rb
@@ -85,6 +85,35 @@ class ClientTest < Minitest::Test
assert_equal "Example", doc.metadata["title"]
end
+ def test_scrape_hydrates_pdf_blocks
+ stub_request(:post, "#{BASE_URL}/v2/scrape")
+ .to_return(
+ status: 200,
+ body: JSON.generate(data: {
+ markdown: "# Annual Report 2025",
+ blocks: [{
+ pageNumber: 1,
+ width: 1700,
+ height: 2200,
+ status: "ok",
+ items: [{
+ id: "p1.b0",
+ type: "title",
+ content: "# Annual Report 2025",
+ readingOrder: 0
+ }]
+ }]
+ }),
+ headers: { "Content-Type" => "application/json" }
+ )
+
+ doc = @client.scrape("https://example.com/report.pdf")
+ assert_equal "# Annual Report 2025", doc.markdown
+ assert_equal 1, doc.blocks.length
+ assert_equal 1, doc.blocks[0]["pageNumber"]
+ assert_equal "title", doc.blocks[0]["items"][0]["type"]
+ 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 e30e1f68d..8bf4a283e 100644
--- a/apps/rust-sdk/CHANGELOG.md
+++ b/apps/rust-sdk/CHANGELOG.md
@@ -1,5 +1,12 @@
## CHANGELOG
+## [2.13.0] - 2026-08-19
+
+### Added
+
+- Added `ParserConfig::Pdf.blocks` to request typed PDF layout blocks.
+- Added `Document.blocks` (`PdfPageBlocks`) for per-page bounding boxes, block types, and reading order.
+
## [2.5.0] - 2026-05-12
### Added
diff --git a/apps/rust-sdk/Cargo.lock b/apps/rust-sdk/Cargo.lock
index f37994035..b24df11aa 100644
--- a/apps/rust-sdk/Cargo.lock
+++ b/apps/rust-sdk/Cargo.lock
@@ -250,7 +250,7 @@ checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
[[package]]
name = "firecrawl"
-version = "2.12.1"
+version = "2.13.0"
dependencies = [
"mockito",
"reqwest",
diff --git a/apps/rust-sdk/Cargo.toml b/apps/rust-sdk/Cargo.toml
index a44518286..e56ecbc85 100644
--- a/apps/rust-sdk/Cargo.toml
+++ b/apps/rust-sdk/Cargo.toml
@@ -1,6 +1,6 @@
[package]
name = "firecrawl"
-version = "2.12.1"
+version = "2.13.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 f4214c945..30c2828d5 100644
--- a/apps/rust-sdk/src/scrape.rs
+++ b/apps/rust-sdk/src/scrape.rs
@@ -117,8 +117,12 @@ pub enum ParserConfig {
parser_type: String,
#[serde(skip_serializing_if = "Option::is_none")]
mode: Option<String>,
- #[serde(skip_serializing_if = "Option::is_none")]
+ #[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")]
+ blocks: Option<bool>,
},
}
@@ -520,6 +524,31 @@ mod tests {
assert!(payload.get("formats").is_none());
}
+ #[test]
+ fn test_pdf_parser_serializes_blocks() {
+ let options = ScrapeOptions {
+ parsers: Some(vec![ParserConfig::Pdf {
+ parser_type: "pdf".to_string(),
+ mode: Some("auto".to_string()),
+ max_pages: None,
+ page_markdown: Some(true),
+ blocks: Some(true),
+ }]),
+ ..Default::default()
+ };
+
+ let payload = serde_json::to_value(options).unwrap();
+ assert_eq!(
+ payload["parsers"][0],
+ json!({
+ "type": "pdf",
+ "mode": "auto",
+ "pageMarkdown": true,
+ "blocks": true
+ })
+ );
+ }
+
#[tokio::test]
async fn test_scrape_with_mock() {
let mut server = mockito::Server::new_async().await;
diff --git a/apps/rust-sdk/src/types.rs b/apps/rust-sdk/src/types.rs
index b97b4036d..5768662d8 100644
--- a/apps/rust-sdk/src/types.rs
+++ b/apps/rust-sdk/src/types.rs
@@ -690,6 +690,46 @@ pub struct Document {
pub product: Option<Product>,
/// Menu extraction result.
pub menu: Option<Menu>,
+ /// Typed PDF layout blocks, present only when `parsers[].blocks` is true.
+ pub blocks: Option<Vec<PdfPageBlocks>>,
+}
+
+/// Layout and OCR confidence scores for a PDF block.
+#[serde_with::skip_serializing_none]
+#[derive(Deserialize, Serialize, Debug, Default, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct PdfBlockConfidence {
+ pub layout: Option<f64>,
+ pub ocr: Option<f64>,
+}
+
+/// A typed PDF layout block (bounding box, type, reading order).
+#[serde_with::skip_serializing_none]
+#[derive(Deserialize, Serialize, Debug, Default, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct PdfBlockItem {
+ pub id: String,
+ #[serde(rename = "type")]
+ pub block_type: String,
+ pub label: Option<String>,
+ pub bbox: Option<[f64; 4]>,
+ pub content: String,
+ pub markdown_span: Option<[i64; 2]>,
+ pub reading_order: i64,
+ pub source: Option<String>,
+ pub confidence: PdfBlockConfidence,
+}
+
+/// Typed layout blocks for a single PDF page.
+#[serde_with::skip_serializing_none]
+#[derive(Deserialize, Serialize, Debug, Default, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct PdfPageBlocks {
+ pub page_number: u32,
+ pub width: Option<f64>,
+ pub height: Option<f64>,
+ pub status: String,
+ pub items: Vec<PdfBlockItem>,
}
/// Product extraction result for a page.
@@ -1132,4 +1172,38 @@ mod tests {
assert_eq!(item_json["availability"]["inStock"], true);
assert_eq!(item_json["identifiers"]["merchantItemId"], "abc123");
}
+
+ #[test]
+ fn test_document_with_blocks() {
+ let json = json!({
+ "markdown": "# Annual Report 2025",
+ "blocks": [{
+ "pageNumber": 1,
+ "width": 1700.0,
+ "height": 2200.0,
+ "status": "ok",
+ "items": [{
+ "id": "p1.b0",
+ "type": "title",
+ "label": "doc_title",
+ "bbox": [0.118, 0.054, 0.882, 0.092],
+ "content": "# Annual Report 2025",
+ "markdownSpan": [0, 21],
+ "readingOrder": 0,
+ "source": "native_text",
+ "confidence": { "layout": 0.97, "ocr": null }
+ }]
+ }]
+ });
+ let doc: Document = serde_json::from_value(json).unwrap();
+ let pages = doc.blocks.expect("blocks should be present");
+ assert_eq!(pages.len(), 1);
+ assert_eq!(pages[0].page_number, 1);
+ assert_eq!(pages[0].status, "ok");
+ assert_eq!(pages[0].items[0].id, "p1.b0");
+ assert_eq!(pages[0].items[0].block_type, "title");
+ assert_eq!(pages[0].items[0].reading_order, 0);
+ assert_eq!(pages[0].items[0].confidence.layout, Some(0.97));
+ assert_eq!(pages[0].items[0].confidence.ocr, None);
+ }
}