Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat(sdks): add parsers[].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.csindex 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 ModelsTestsAssert.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.csprojindex 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.csindex 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.csindex 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.csnew file mode 100644index 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.goindex 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 pagediff --git a/apps/go-sdk/options_test.go b/apps/go-sdk/options_test.goindex 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.goindex 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.ktsindex 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_11diff --git a/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java b/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.javaindex 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 minutesprivate static final int DEFAULT_MAX_RETRIES = 3;private static final double DEFAULT_BACKOFF_FACTOR = 0.5;diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/Document.java b/apps/java-sdk/src/main/java/com/firecrawl/models/Document.javaindex 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; }@Overridepublic 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.javanew file mode 100644index 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.javanew file mode 100644index 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.javanew file mode 100644index 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.javaindex 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.javaindex 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());+ }+@Testvoid testDocumentDeserializesMenu() throws Exception {String json = "{\"menu\":{"diff --git a/apps/js-sdk/firecrawl/package.json b/apps/js-sdk/firecrawl/package.jsonindex 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.tsindex 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 schemadiff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.tsindex 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` URLdiff --git a/apps/php-sdk/CHANGELOG.md b/apps/php-sdk/CHANGELOG.mdindex 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### Addeddiff --git a/apps/php-sdk/src/Models/Document.php b/apps/php-sdk/src/Models/Document.phpindex 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 Documentprivate 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 Documentmenu: 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.phpindex 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.phpindex 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__.pyindex 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 projectlogger: logging.Logger = logging.getLogger("firecrawl")diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_document_blocks.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_document_blocks.pynew file mode 100644index 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 Nonediff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_validation.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_validation.pyindex 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.pyindex 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 typesDocument,DocumentMetadata,+ PdfBlockConfidence,+ PdfBlockItem,+ PdfPageBlocks,# Scrape typesScrapeFormats,@@ -67,6 +70,7 @@ from .v2.types import (ScrapeAction,ExecuteJavascriptAction,PDFAction,+ PDFParser,# Usage typesQueueStatusResponse,@@ -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.pyindex 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] = Noneproduct: Optional[ProductProfile] = Nonemenu: Optional[MenuProfile] = None+ blocks: Optional[List[PdfPageBlocks]] = None@propertydef metadata_typed(self) -> DocumentMetadata:@@ -1618,6 +1656,8 @@ class PDFParser(BaseModel):type: Literal["pdf"] = "pdf"mode: Optional[Literal["fast", "auto", "ocr"]] = Nonemax_pages: Optional[int] = None+ page_markdown: Optional[bool] = None+ blocks: Optional[bool] = None# Location typesdiff --git a/apps/python-sdk/firecrawl/v2/utils/validation.py b/apps/python-sdk/firecrawl/v2/utils/validation.pyindex 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[stparser_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 APIif "max_pages" in parser_data:parser_data["maxPages"] = parser_data.pop("max_pages")+ if "page_markdown" in parser_data:+ parser_data["pageMarkdown"] = parser_data.pop("page_markdown")converted_parsers.append(parser_data)scrape_data["parsers"] = converted_parserselif key == "location":diff --git a/apps/ruby-sdk/lib/firecrawl/models/document.rb b/apps/ruby-sdk/lib/firecrawl/models/document.rbindex 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 Firecrawlattr_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,+ :blocksdef 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"]enddef to_sdiff --git a/apps/ruby-sdk/lib/firecrawl/version.rb b/apps/ruby-sdk/lib/firecrawl/version.rbindex 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: truemodule Firecrawl- VERSION = "1.11.1"+ VERSION = "1.12.0"enddiff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rbindex 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::Testassert_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_optionsstub_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.mdindex 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### Addeddiff --git a/apps/rust-sdk/Cargo.lock b/apps/rust-sdk/Cargo.lockindex 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.tomlindex 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.rsindex 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.rsindex 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);+ }}