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
chore(api/query): change api surface
mogery14d5af3e4cb3
diff --git a/apps/api/src/__tests__/snips/v2/scrape-query.test.ts b/apps/api/src/__tests__/snips/v2/scrape-query.test.tsindex 660253cb3..41cbd5b4d 100644--- a/apps/api/src/__tests__/snips/v2/scrape-query.test.ts+++ b/apps/api/src/__tests__/snips/v2/scrape-query.test.ts@@ -61,6 +61,30 @@ describe("Query format", () => {scrapeTimeout,);+ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "returns a direct quote answer when query mode is directQuote",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: [+ {+ type: "query",+ prompt: "What is Firecrawl?",+ mode: "directQuote",+ },+ ],+ },+ identity,+ );++ expect(response.answer).toBeDefined();+ expect(typeof response.answer).toBe("string");+ expect(response.answer!.length).toBeGreaterThan(0);+ },+ scrapeTimeout,+ );+concurrentIf(TEST_PRODUCTION || HAS_AI)("does not include answer field when query format is not provided",async () => {diff --git a/apps/api/src/__tests__/snips/v2/types-validation.test.ts b/apps/api/src/__tests__/snips/v2/types-validation.test.tsindex d11c5928a..3ab18a905 100644--- a/apps/api/src/__tests__/snips/v2/types-validation.test.ts+++ b/apps/api/src/__tests__/snips/v2/types-validation.test.ts@@ -87,7 +87,25 @@ describe("V2 Types Validation", () => {const result = scrapeRequestSchema.parse(input);expect(result.formats).toEqual([- { type: "query", prompt: "What is Firecrawl?", directQuote: false },+ { type: "query", prompt: "What is Firecrawl?", mode: "freeform" },+ ]);+ });++ it("should accept query format directQuote mode", () => {+ const input: ScrapeRequestInput = {+ url: "https://example.com",+ formats: [+ {+ type: "query",+ prompt: "What is Firecrawl?",+ mode: "directQuote",+ },+ ],+ };++ const result = scrapeRequestSchema.parse(input);+ expect(result.formats).toEqual([+ { type: "query", prompt: "What is Firecrawl?", mode: "directQuote" },]);});@@ -1003,10 +1021,44 @@ describe("V2 Types Validation", () => {const result = searchRequestSchema.parse(input);expect(result.scrapeOptions?.formats).toEqual([- { type: "query", prompt: "What is Firecrawl?", directQuote: false },+ { type: "query", prompt: "What is Firecrawl?", mode: "freeform" },]);});+ it("should reject search scrapeOptions query format with invalid mode", () => {+ const input: SearchRequestInput = {+ query: "test",+ scrapeOptions: {+ formats: [+ {+ type: "query",+ prompt: "What is Firecrawl?",+ mode: "quoted",+ } as any,+ ],+ },+ };++ expect(() => searchRequestSchema.parse(input)).toThrow();+ });++ it("should reject search scrapeOptions query format with directQuote boolean", () => {+ const input: SearchRequestInput = {+ query: "test",+ scrapeOptions: {+ formats: [+ {+ type: "query",+ prompt: "What is Firecrawl?",+ directQuote: true,+ } as any,+ ],+ },+ };++ expect(() => searchRequestSchema.parse(input)).toThrow();+ });+it("should reject search scrapeOptions query prompt over 10000 characters", () => {const input: SearchRequestInput = {query: "test",diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.tsindex f11bb094c..ecfe24d5f 100644--- a/apps/api/src/controllers/v2/types.ts+++ b/apps/api/src/controllers/v2/types.ts@@ -403,7 +403,7 @@ type AttributesFormatWithOptions = z.output<typeof attributesFormatWithOptions>;const queryFormatWithOptions = z.strictObject({type: z.literal("query"),prompt: z.string().max(10000),- directQuote: z.boolean().optional().default(false),+ mode: z.enum(["freeform", "directQuote"]).optional().default("freeform"),});type QueryFormatWithOptions = z.output<typeof queryFormatWithOptions>;diff --git a/apps/api/src/scraper/scrapeURL/transformers/query.ts b/apps/api/src/scraper/scrapeURL/transformers/query.tsindex 54e162daf..b6cb0d735 100644--- a/apps/api/src/scraper/scrapeURL/transformers/query.ts+++ b/apps/api/src/scraper/scrapeURL/transformers/query.ts@@ -507,7 +507,7 @@ export async function performQuery(let answer: string | null;- if (queryFormat.directQuote) {+ if (queryFormat.mode === "directQuote") {answer = await performDirectQuoteQuery(meta,document,diff --git a/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs b/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.csindex 4d44144b7..7c1f20ec5 100644--- a/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs+++ b/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs@@ -244,6 +244,21 @@ public class ModelsTestsAssert.Contains("\"schema\"", json);}+ [Fact]+ public void QueryFormat_HasCorrectMode()+ {+ var format = new QueryFormat+ {+ Prompt = "What is Firecrawl?",+ Mode = QueryFormat.DirectQuoteMode+ };++ var json = JsonSerializer.Serialize(format, JsonOptions);+ Assert.Contains("\"type\":\"query\"", json);+ Assert.Contains("\"prompt\":\"What is Firecrawl?\"", json);+ Assert.Contains("\"mode\":\"directQuote\"", json);+ }+[Fact]public void WebhookConfig_SerializesCorrectly(){diff --git a/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj b/apps/dot-net-sdk/Firecrawl/Firecrawl.csprojindex 6bd4e455a..e2a0f936f 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.2.0</Version>+ <Version>1.2.1</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/Models/QueryFormat.cs b/apps/dot-net-sdk/Firecrawl/Models/QueryFormat.csnew file mode 100644index 000000000..44cd93920--- /dev/null+++ b/apps/dot-net-sdk/Firecrawl/Models/QueryFormat.cs@@ -0,0 +1,22 @@+using System.Text.Json.Serialization;++namespace Firecrawl.Models;++/// <summary>+/// Query format specification for use in ScrapeOptions.Formats.+/// </summary>+public class QueryFormat+{+ public const string FreeformMode = "freeform";+ public const string DirectQuoteMode = "directQuote";++ [JsonPropertyName("type")]+ public string Type { get; } = "query";++ [JsonPropertyName("prompt")]+ public required string Prompt { get; set; }++ [JsonPropertyName("mode")]+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]+ public string? Mode { get; set; }+}diff --git a/apps/elixir-sdk/mix.exs b/apps/elixir-sdk/mix.exsindex 12db15dc3..479cf2217 100644--- a/apps/elixir-sdk/mix.exs+++ b/apps/elixir-sdk/mix.exs@@ -1,7 +1,7 @@defmodule Firecrawl.MixProject douse Mix.Project- @version "1.2.0"+ @version "1.2.1"@source_url "https://github.com/firecrawl/firecrawl/tree/main/apps/elixir-sdk"def project dodiff --git a/apps/go-sdk/options.go b/apps/go-sdk/options.goindex 75766bc77..4f610553d 100644--- a/apps/go-sdk/options.go+++ b/apps/go-sdk/options.go@@ -1,8 +1,40 @@package firecrawl+import "encoding/json"++// QueryFormatMode selects how query answers are generated.+type QueryFormatMode string++const (+ QueryModeFreeform QueryFormatMode = "freeform"+ QueryModeDirectQuote QueryFormatMode = "directQuote"+)++// QueryFormat asks a question about page content.+type QueryFormat struct {+ Prompt string `json:"prompt"`+ Mode QueryFormatMode `json:"mode,omitempty"`+}++// MarshalJSON always emits the API-required query format type.+func (q QueryFormat) MarshalJSON() ([]byte, error) {+ type queryFormat struct {+ Type string `json:"type"`+ Prompt string `json:"prompt"`+ Mode QueryFormatMode `json:"mode,omitempty"`+ }++ return json.Marshal(queryFormat{+ Type: "query",+ Prompt: q.Prompt,+ Mode: q.Mode,+ })+}+// ScrapeOptions configures a single-page scrape request.type ScrapeOptions struct {- Formats []string `json:"formats,omitempty"`+ Formats []string `json:"-"`+ FormatOptions []interface{} `json:"-"`Headers map[string]string `json:"headers,omitempty"`IncludeTags []string `json:"includeTags,omitempty"`ExcludeTags []string `json:"excludeTags,omitempty"`@@ -24,6 +56,25 @@ type ScrapeOptions struct {JsonOptions *JsonOptions `json:"jsonOptions,omitempty"`}+// MarshalJSON preserves string formats while allowing object formats such as QueryFormat.+func (o ScrapeOptions) MarshalJSON() ([]byte, error) {+ type scrapeOptions ScrapeOptions+ payload := struct {+ scrapeOptions+ Formats interface{} `json:"formats,omitempty"`+ }{+ scrapeOptions: scrapeOptions(o),+ }++ if len(o.FormatOptions) > 0 {+ payload.Formats = o.FormatOptions+ } else if len(o.Formats) > 0 {+ payload.Formats = o.Formats+ }++ return json.Marshal(payload)+}+// CrawlOptions configures a crawl request.type CrawlOptions struct {Prompt *string `json:"prompt,omitempty"`@@ -34,7 +85,7 @@ type CrawlOptions struct {IgnoreQueryParameters *bool `json:"ignoreQueryParameters,omitempty"`DeduplicateSimilarURLs *bool `json:"deduplicateSimilarURLs,omitempty"`Limit *int `json:"limit,omitempty"`- CrawlEntireDomain *bool `json:"crawlEntireDomain,omitempty"`+ CrawlEntireDomain *bool `json:"crawlEntireDomain,omitempty"`AllowExternalLinks *bool `json:"allowExternalLinks,omitempty"`AllowSubdomains *bool `json:"allowSubdomains,omitempty"`Delay *int `json:"delay,omitempty"`@@ -87,14 +138,14 @@ type SearchOptions struct {// AgentOptions configures an agent request.type AgentOptions struct {- URLs []string `json:"urls,omitempty"`- Prompt string `json:"prompt"`- Schema map[string]interface{} `json:"schema,omitempty"`- Integration *string `json:"integration,omitempty"`- MaxCredits *int `json:"maxCredits,omitempty"`- StrictConstrainToURLs *bool `json:"strictConstrainToURLs,omitempty"`- Model *string `json:"model,omitempty"`- Webhook *WebhookConfig `json:"webhook,omitempty"`+ URLs []string `json:"urls,omitempty"`+ Prompt string `json:"prompt"`+ Schema map[string]interface{} `json:"schema,omitempty"`+ Integration *string `json:"integration,omitempty"`+ MaxCredits *int `json:"maxCredits,omitempty"`+ StrictConstrainToURLs *bool `json:"strictConstrainToURLs,omitempty"`+ Model *string `json:"model,omitempty"`+ Webhook *WebhookConfig `json:"webhook,omitempty"`}// LocationConfig specifies geolocation for requests.diff --git a/apps/go-sdk/options_test.go b/apps/go-sdk/options_test.gonew file mode 100644index 000000000..dbb4f0b5c--- /dev/null+++ b/apps/go-sdk/options_test.go@@ -0,0 +1,43 @@+package firecrawl++import (+ "encoding/json"+ "strings"+ "testing"+)++func TestScrapeOptionsSerializesQueryFormatMode(t *testing.T) {+ payload, err := json.Marshal(ScrapeOptions{+ FormatOptions: []interface{}{+ QueryFormat{+ Prompt: "What is Firecrawl?",+ Mode: QueryModeDirectQuote,+ },+ },+ })+ if err != nil {+ t.Fatalf("Marshal ScrapeOptions: %v", err)+ }++ jsonBody := string(payload)+ for _, want := range []string{+ `"formats":[{"type":"query","prompt":"What is Firecrawl?","mode":"directQuote"}]`,+ } {+ if !strings.Contains(jsonBody, want) {+ t.Fatalf("serialized query format = %s, want to contain %s", jsonBody, want)+ }+ }+}++func TestScrapeOptionsPreservesStringFormats(t *testing.T) {+ payload, err := json.Marshal(ScrapeOptions{+ Formats: []string{"markdown"},+ })+ if err != nil {+ t.Fatalf("Marshal ScrapeOptions: %v", err)+ }++ if !strings.Contains(string(payload), `"formats":["markdown"]`) {+ t.Fatalf("serialized string formats = %s", payload)+ }+}diff --git a/apps/go-sdk/parse.go b/apps/go-sdk/parse.goindex b47501e03..6329f2f7a 100644--- a/apps/go-sdk/parse.go+++ b/apps/go-sdk/parse.go@@ -57,7 +57,8 @@ func NewParseFileFromBytes(filename string, content []byte) *ParseFile {// mobile) nor the screenshot, branding, or changeTracking formats. The proxy// field only accepts "auto" or "basic".type ParseOptions struct {- Formats []string `json:"formats,omitempty"`+ Formats []string `json:"-"`+ FormatOptions []interface{} `json:"-"`Headers map[string]string `json:"headers,omitempty"`IncludeTags []string `json:"includeTags,omitempty"`ExcludeTags []string `json:"excludeTags,omitempty"`@@ -72,6 +73,25 @@ type ParseOptions struct {JsonOptions *JsonOptions `json:"jsonOptions,omitempty"`}+// MarshalJSON preserves string formats while allowing object formats such as QueryFormat.+func (o ParseOptions) MarshalJSON() ([]byte, error) {+ type parseOptions ParseOptions+ payload := struct {+ parseOptions+ Formats interface{} `json:"formats,omitempty"`+ }{+ parseOptions: parseOptions(o),+ }++ if len(o.FormatOptions) > 0 {+ payload.Formats = o.FormatOptions+ } else if len(o.Formats) > 0 {+ payload.Formats = o.Formats+ }++ return json.Marshal(payload)+}+// Parse uploads a file to the `/v2/parse` endpoint and returns the extracted document.func (c *Client) Parse(ctx context.Context, file *ParseFile, opts *ParseOptions) (*Document, error) {if file == nil {diff --git a/apps/go-sdk/version.go b/apps/go-sdk/version.goindex e0d6e24e1..afafa732e 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.2.0"+const Version = "1.2.1"diff --git a/apps/java-sdk/build.gradle.kts b/apps/java-sdk/build.gradle.ktsindex 33f7bda2a..3183e7110 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.4.0"+version = "1.4.1"java {sourceCompatibility = JavaVersion.VERSION_11diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/QueryFormat.java b/apps/java-sdk/src/main/java/com/firecrawl/models/QueryFormat.javanew file mode 100644index 000000000..195281897--- /dev/null+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/QueryFormat.java@@ -0,0 +1,59 @@+package com.firecrawl.models;++import com.fasterxml.jackson.annotation.JsonInclude;+import com.fasterxml.jackson.annotation.JsonValue;++/**+ * Query format for asking a question about page content.+ */+@JsonInclude(JsonInclude.Include.NON_NULL)+public class QueryFormat {++ public enum Mode {+ FREEFORM("freeform"),+ DIRECT_QUOTE("directQuote");++ private final String value;++ Mode(String value) {+ this.value = value;+ }++ @JsonValue+ public String getValue() {+ return value;+ }+ }++ private final String type = "query";+ private String prompt;+ private Mode mode;++ private QueryFormat() {}++ public String getType() { return type; }+ public String getPrompt() { return prompt; }+ public Mode getMode() { return mode; }++ public static Builder builder() { return new Builder(); }++ public static final class Builder {+ private String prompt;+ private Mode mode;++ private Builder() {}++ /** Question to answer from the page content. */+ public Builder prompt(String prompt) { this.prompt = prompt; return this; }++ /** Query answer mode: freeform or direct quote. */+ public Builder mode(Mode mode) { this.mode = mode; return this; }++ public QueryFormat build() {+ QueryFormat f = new QueryFormat();+ f.prompt = this.prompt;+ f.mode = this.mode;+ return f;+ }+ }+}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 222704900..440af580d 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@@ -108,8 +108,8 @@ public class ScrapeOptions {/*** Output formats to request. Accepts strings like "markdown", "html", "rawHtml",- * "links", "screenshot", "json", "audio", etc., or format configuration maps for- * advanced formats (e.g., JsonFormat, ScreenshotFormat).+ * "links", "screenshot", "json", "audio", etc., or format configuration maps/objects for+ * advanced formats (e.g., JsonFormat, QueryFormat).*/public Builder formats(List<Object> formats) { this.formats = formats; return this; }diff --git a/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.java b/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.javaindex 9899a4335..04a68737e 100644--- a/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.java+++ b/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.java@@ -60,14 +60,21 @@ class FirecrawlClientTest {@Testvoid testScrapeOptionsBuilder() {+ QueryFormat queryFormat = QueryFormat.builder()+ .prompt("What is Firecrawl?")+ .mode(QueryFormat.Mode.DIRECT_QUOTE)+ .build();+ScrapeOptions options = ScrapeOptions.builder()- .formats(List.of("markdown", "html"))+ .formats(List.of("markdown", "html", queryFormat)).onlyMainContent(true).timeout(30000).mobile(false).build();- assertEquals(List.of("markdown", "html"), options.getFormats());+ assertEquals(List.of("markdown", "html", queryFormat), options.getFormats());+ assertEquals("query", queryFormat.getType());+ assertEquals(QueryFormat.Mode.DIRECT_QUOTE, queryFormat.getMode());assertTrue(options.getOnlyMainContent());assertEquals(30000, options.getTimeout());assertFalse(options.getMobile());diff --git a/apps/js-sdk/firecrawl/package.json b/apps/js-sdk/firecrawl/package.jsonindex c8b729bdf..5504ff98d 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.21.0",+ "version": "4.21.1","description": "JavaScript SDK for Firecrawl API","main": "dist/index.js","types": "dist/index.d.ts",diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.tsindex 8a3fa0334..f72a6b8ea 100644--- a/apps/js-sdk/firecrawl/src/v2/types.ts+++ b/apps/js-sdk/firecrawl/src/v2/types.ts@@ -55,6 +55,7 @@ export interface AttributesFormat extends Format {export interface QueryFormat {type: 'query';prompt: string;+ mode?: 'freeform' | 'directQuote';}export type FormatOption =diff --git a/apps/php-sdk/src/Models/ParseOptions.php b/apps/php-sdk/src/Models/ParseOptions.phpindex a9a0a4a0b..ec1d458aa 100644--- a/apps/php-sdk/src/Models/ParseOptions.php+++ b/apps/php-sdk/src/Models/ParseOptions.php@@ -23,7 +23,7 @@ final class ParseOptions];/**- * @param list<string|JsonFormat>|null $formats+ * @param list<string|JsonFormat|QueryFormat>|null $formats* @param array<string, string>|null $headers* @param list<string>|null $includeTags* @param list<string>|null $excludeTags@@ -45,7 +45,7 @@ final class ParseOptions) {}/**- * @param list<string|JsonFormat>|null $formats+ * @param list<string|JsonFormat|QueryFormat>|null $formats* @param array<string, string>|null $headers* @param list<string>|null $includeTags* @param list<string>|null $excludeTags@@ -105,7 +105,8 @@ final class ParseOptionsif ($this->formats !== null) {$data['formats'] = array_map(- fn (string|JsonFormat $f): string|array => $f instanceof JsonFormat ? $f->toArray() : $f,+ fn (string|JsonFormat|QueryFormat $f): string|array =>+ $f instanceof JsonFormat || $f instanceof QueryFormat ? $f->toArray() : $f,$this->formats,);}diff --git a/apps/php-sdk/src/Models/QueryFormat.php b/apps/php-sdk/src/Models/QueryFormat.phpnew file mode 100644index 000000000..70daa7920--- /dev/null+++ b/apps/php-sdk/src/Models/QueryFormat.php@@ -0,0 +1,47 @@+<?php++declare(strict_types=1);++namespace Firecrawl\Models;++final class QueryFormat+{+ public const MODE_FREEFORM = 'freeform';+ public const MODE_DIRECT_QUOTE = 'directQuote';++ private function __construct(+ private readonly string $prompt,+ private readonly ?string $mode = null,+ ) {}++ public static function with(+ string $prompt,+ ?string $mode = null,+ ): self {+ if ($mode !== null && !in_array($mode, [self::MODE_FREEFORM, self::MODE_DIRECT_QUOTE], true)) {+ throw new \InvalidArgumentException("query mode must be 'freeform' or 'directQuote'");+ }++ return new self($prompt, $mode);+ }++ /** @return array<string, mixed> */+ public function toArray(): array+ {+ return array_filter([+ 'type' => 'query',+ 'prompt' => $this->prompt,+ 'mode' => $this->mode,+ ], fn (mixed $v): bool => $v !== null);+ }++ public function getPrompt(): string+ {+ return $this->prompt;+ }++ public function getMode(): ?string+ {+ return $this->mode;+ }+}diff --git a/apps/php-sdk/src/Models/ScrapeOptions.php b/apps/php-sdk/src/Models/ScrapeOptions.phpindex 15be371b3..7694d70ca 100644--- a/apps/php-sdk/src/Models/ScrapeOptions.php+++ b/apps/php-sdk/src/Models/ScrapeOptions.php@@ -7,7 +7,7 @@ namespace Firecrawl\Models;final class ScrapeOptions{/**- * @param list<string|JsonFormat|ScreenshotFormat>|null $formats+ * @param list<string|JsonFormat|ScreenshotFormat|QueryFormat>|null $formats* @param array<string, string>|null $headers* @param list<string>|null $includeTags* @param list<string>|null $excludeTags@@ -41,7 +41,7 @@ final class ScrapeOptions) {}/**- * @param list<string|JsonFormat|ScreenshotFormat>|null $formats+ * @param list<string|JsonFormat|ScreenshotFormat|QueryFormat>|null $formats* @param array<string, string>|null $headers* @param list<string>|null $includeTags* @param list<string>|null $excludeTags@@ -89,8 +89,8 @@ final class ScrapeOptionsif ($this->formats !== null) {$data['formats'] = array_map(- fn (string|JsonFormat|ScreenshotFormat $f): string|array =>- $f instanceof JsonFormat || $f instanceof ScreenshotFormat ? $f->toArray() : $f,+ fn (string|JsonFormat|ScreenshotFormat|QueryFormat $f): string|array =>+ $f instanceof JsonFormat || $f instanceof ScreenshotFormat || $f instanceof QueryFormat ? $f->toArray() : $f,$this->formats,);}@@ -128,7 +128,7 @@ final class ScrapeOptionsreturn $data;}- /** @return list<string|JsonFormat|ScreenshotFormat>|null */+ /** @return list<string|JsonFormat|ScreenshotFormat|QueryFormat>|null */public function getFormats(): ?array{return $this->formats;diff --git a/apps/php-sdk/src/Version.php b/apps/php-sdk/src/Version.phpindex 11d7dc95b..e7da56ddc 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.1.0';+ public const SDK_VERSION = '1.1.1';}diff --git a/apps/php-sdk/tests/Unit/ModelsTest.php b/apps/php-sdk/tests/Unit/ModelsTest.phpindex d3a6b78de..59b2592bb 100644--- a/apps/php-sdk/tests/Unit/ModelsTest.php+++ b/apps/php-sdk/tests/Unit/ModelsTest.php@@ -6,6 +6,7 @@ use Firecrawl\Models\CreditUsage;use Firecrawl\Models\MapData;use Firecrawl\Models\BatchScrapeJob;use Firecrawl\Models\CrawlJob;+use Firecrawl\Models\QueryFormat;use Firecrawl\Models\ScrapeOptions;it('hydrates CreditUsage from nested data key', function (): void {@@ -133,3 +134,19 @@ it('serializes lockdown in ScrapeOptions', function (): void {'integration' => 'php-sdk',]);});++it('serializes query format mode in ScrapeOptions', function (): void {+ $options = ScrapeOptions::with(+ formats: [QueryFormat::with('What is Firecrawl?', QueryFormat::MODE_DIRECT_QUOTE)],+ );++ expect($options->toArray()['formats'][0])->toMatchArray([+ 'type' => 'query',+ 'prompt' => 'What is Firecrawl?',+ 'mode' => 'directQuote',+ ]);+});++it('rejects invalid query format mode', function (): void {+ QueryFormat::with('What is Firecrawl?', 'quoted');+})->throws(InvalidArgumentException::class, "query mode must be 'freeform' or 'directQuote'");diff --git a/apps/python-sdk/firecrawl/__init__.py b/apps/python-sdk/firecrawl/__init__.pyindex 492fe6f85..e42f93db3 100644--- a/apps/python-sdk/firecrawl/__init__.py+++ b/apps/python-sdk/firecrawl/__init__.py@@ -17,7 +17,7 @@ from .v1 import (V1ChangeTrackingOptions,)-__version__ = "4.24.0"+__version__ = "4.24.1"# Define the logger for the Firecrawl projectlogger: 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.pyindex 615fafb7e..41b205b1a 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@@ -1,5 +1,5 @@import pytest-from firecrawl.v2.types import JsonFormat, ScrapeOptions, PDFParser+from firecrawl.v2.types import JsonFormat, QueryFormat, ScrapeOptions, PDFParserfrom firecrawl.v2.utils.validation import validate_scrape_options, prepare_scrape_options@@ -189,6 +189,47 @@ class TestPrepareScrapeOptions:with pytest.raises(ValueError, match="Timeout must be positive"):prepare_scrape_options(options)+ def test_prepare_query_format_with_mode(self):+ """Test query format mode is preserved."""+ options = ScrapeOptions(+ formats=[QueryFormat(prompt="What is Firecrawl?", mode="directQuote")]+ )+ result = prepare_scrape_options(options)++ assert result["formats"] == [+ {"type": "query", "prompt": "What is Firecrawl?", "mode": "directQuote"}+ ]++ def test_prepare_query_format_rejects_direct_quote_boolean(self):+ """Test old query directQuote layout is rejected."""+ options = ScrapeOptions(+ formats=[+ {+ "type": "query",+ "prompt": "What is Firecrawl?",+ "directQuote": True,+ }+ ]+ )++ with pytest.raises(ValueError, match="uses 'mode' instead of 'directQuote'"):+ prepare_scrape_options(options)++ def test_prepare_query_format_rejects_invalid_mode(self):+ """Test query mode validation."""+ options = ScrapeOptions(+ formats=[+ {+ "type": "query",+ "prompt": "What is Firecrawl?",+ "mode": "quoted",+ }+ ]+ )++ with pytest.raises(ValueError, match="mode must be 'freeform' or 'directQuote'"):+ prepare_scrape_options(options)+def test_prepare_empty_options(self):"""Test preparation with empty options."""options = ScrapeOptions() # All defaultsdiff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.pyindex a8e9b6b06..9b06f0341 100644--- a/apps/python-sdk/firecrawl/v2/types.py+++ b/apps/python-sdk/firecrawl/v2/types.py@@ -451,6 +451,7 @@ class QueryFormat(Format):type: Literal["query"] = "query"prompt: str+ mode: Optional[Literal["freeform", "directQuote"]] = NoneFormatOption = Union[diff --git a/apps/python-sdk/firecrawl/v2/utils/validation.py b/apps/python-sdk/firecrawl/v2/utils/validation.pyindex 0a13f2dcb..8568bec50 100644--- a/apps/python-sdk/firecrawl/v2/utils/validation.py+++ b/apps/python-sdk/firecrawl/v2/utils/validation.py@@ -454,6 +454,13 @@ def _validate_query_format(format_obj: Any) -> Dict[str, Any]:if not isinstance(format_obj.get('prompt'), str) or not format_obj['prompt'].strip():raise ValueError("query format requires a non-empty 'prompt' string")+ if "directQuote" in format_obj:+ raise ValueError("query format uses 'mode' instead of 'directQuote'")++ mode = format_obj.get("mode")+ if mode is not None and mode not in ("freeform", "directQuote"):+ raise ValueError("query format mode must be 'freeform' or 'directQuote'")+return format_objdiff --git a/apps/ruby-sdk/lib/firecrawl.rb b/apps/ruby-sdk/lib/firecrawl.rbindex 869a08ba0..79af43268 100644--- a/apps/ruby-sdk/lib/firecrawl.rb+++ b/apps/ruby-sdk/lib/firecrawl.rb@@ -3,6 +3,7 @@require_relative "firecrawl/version"require_relative "firecrawl/errors"require_relative "firecrawl/http_client"+require_relative "firecrawl/models/query_format"require_relative "firecrawl/models/document"require_relative "firecrawl/models/scrape_options"require_relative "firecrawl/models/crawl_options"diff --git a/apps/ruby-sdk/lib/firecrawl/models/parse_options.rb b/apps/ruby-sdk/lib/firecrawl/models/parse_options.rbindex b3edb06c2..1d67aa3be 100644--- a/apps/ruby-sdk/lib/firecrawl/models/parse_options.rb+++ b/apps/ruby-sdk/lib/firecrawl/models/parse_options.rb@@ -26,7 +26,7 @@ module Firecrawldef to_h{- "formats" => formats,+ "formats" => formats&.map { |fmt| format_value(fmt) },"headers" => headers,"includeTags" => include_tags,"excludeTags" => exclude_tags,@@ -69,6 +69,10 @@ module Firecrawlfmt.respond_to?(:type) ? fmt.type : nilendend++ def format_value(fmt)+ fmt.respond_to?(:to_h) ? fmt.to_h : fmt+ endendendenddiff --git a/apps/ruby-sdk/lib/firecrawl/models/query_format.rb b/apps/ruby-sdk/lib/firecrawl/models/query_format.rbnew file mode 100644index 000000000..5706ff36b--- /dev/null+++ b/apps/ruby-sdk/lib/firecrawl/models/query_format.rb@@ -0,0 +1,34 @@+# frozen_string_literal: true++module Firecrawl+ module Models+ # Query format for asking a question about page content.+ class QueryFormat+ MODE_FREEFORM = "freeform"+ MODE_DIRECT_QUOTE = "directQuote"++ attr_reader :prompt, :mode++ def initialize(prompt:, mode: nil)+ unless mode.nil? || [MODE_FREEFORM, MODE_DIRECT_QUOTE].include?(mode)+ raise ArgumentError, "query mode must be 'freeform' or 'directQuote'"+ end++ @prompt = prompt+ @mode = mode+ end++ def to_h+ {+ "type" => "query",+ "prompt" => prompt,+ "mode" => mode,+ }.compact+ end++ def type+ "query"+ end+ end+ end+enddiff --git a/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rb b/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rbindex cb6134ac9..dfd29e474 100644--- a/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rb+++ b/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rb@@ -20,7 +20,7 @@ module Firecrawldef to_h{- "formats" => formats,+ "formats" => formats&.map { |fmt| format_value(fmt) },"headers" => headers,"includeTags" => include_tags,"excludeTags" => exclude_tags,@@ -41,6 +41,12 @@ module Firecrawl"integration" => integration,}.compactend++ private++ def format_value(fmt)+ fmt.respond_to?(:to_h) ? fmt.to_h : fmt+ endendendenddiff --git a/apps/ruby-sdk/lib/firecrawl/version.rb b/apps/ruby-sdk/lib/firecrawl/version.rbindex 10ea39d74..33b639d21 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.3.0"+ VERSION = "1.3.1"enddiff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rbindex 5b4547f4a..184d5505b 100644--- a/apps/ruby-sdk/test/firecrawl/client_test.rb+++ b/apps/ruby-sdk/test/firecrawl/client_test.rb@@ -458,6 +458,25 @@ class ClientTest < Minitest::Testrefute h.key?("timeout") # nil values should be omittedend+ def test_query_format_to_h+ format = Firecrawl::Models::QueryFormat.new(+ prompt: "What is Firecrawl?",+ mode: Firecrawl::Models::QueryFormat::MODE_DIRECT_QUOTE+ )+ opts = Firecrawl::Models::ScrapeOptions.new(formats: [format])++ assert_equal(+ [{ "type" => "query", "prompt" => "What is Firecrawl?", "mode" => "directQuote" }],+ opts.to_h["formats"]+ )+ end++ def test_query_format_rejects_invalid_mode+ assert_raises(ArgumentError) do+ Firecrawl::Models::QueryFormat.new(prompt: "What is Firecrawl?", mode: "quoted")+ end+ end+def test_scrape_options_skip_tls_defaults_to_falseopts = Firecrawl::Models::ScrapeOptions.newassert_equal false, opts.skip_tls_verificationdiff --git a/apps/rust-sdk/Cargo.lock b/apps/rust-sdk/Cargo.lockindex 7f17f6a56..13078e92d 100644--- a/apps/rust-sdk/Cargo.lock+++ b/apps/rust-sdk/Cargo.lock@@ -250,7 +250,7 @@ checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"[[package]]name = "firecrawl"-version = "2.3.0"+version = "2.3.1"dependencies = ["mockito","reqwest",diff --git a/apps/rust-sdk/Cargo.toml b/apps/rust-sdk/Cargo.tomlindex 7bb9bf1b6..6de8905e7 100644--- a/apps/rust-sdk/Cargo.toml+++ b/apps/rust-sdk/Cargo.toml@@ -1,6 +1,6 @@[package]name = "firecrawl"-version = "2.3.0"+version = "2.3.1"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 650ed92d8..43ec1b86d 100644--- a/apps/rust-sdk/src/scrape.rs+++ b/apps/rust-sdk/src/scrape.rs@@ -436,8 +436,30 @@ impl Client {#[cfg(test)]mod tests {use super::*;+ use crate::{QueryFormat, QueryFormatMode};use serde_json::json;+ #[test]+ fn test_query_format_serializes_mode() {+ let options = ScrapeOptions {+ formats: Some(vec![Format::Query(QueryFormat {+ prompt: "What is Firecrawl?".to_string(),+ mode: Some(QueryFormatMode::DirectQuote),+ })]),+ ..Default::default()+ };++ let payload = serde_json::to_value(options).unwrap();+ assert_eq!(+ payload["formats"][0],+ json!({+ "type": "query",+ "prompt": "What is Firecrawl?",+ "mode": "directQuote"+ })+ );+ }+#[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 d1bb976c7..bcc7879ee 100644--- a/apps/rust-sdk/src/types.rs+++ b/apps/rust-sdk/src/types.rs@@ -1,14 +1,13 @@//! Type definitions for Firecrawl API v2.-use serde::{Deserialize, Serialize};+use serde::{de, Deserialize, Deserializer, Serialize, Serializer};use serde_json::Value;use std::collections::HashMap;use crate::serde_helpers::deserialize_string_or_array;/// Available output formats for scraping operations.-#[derive(Deserialize, Serialize, Clone, Copy, Debug, PartialEq, Eq)]-#[serde(rename_all = "camelCase")]+#[derive(Clone, Debug, PartialEq, Eq)]pub enum Format {/// Markdown content of the page.Markdown,@@ -34,6 +33,120 @@ pub enum Format {Branding,/// Audio extraction (MP3) from YouTube videos.Audio,+ /// Query answer generated from the page content.+ Query(QueryFormat),+}++impl Serialize for Format {+ fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>+ where+ S: Serializer,+ {+ match self {+ Format::Markdown => serializer.serialize_str("markdown"),+ Format::Html => serializer.serialize_str("html"),+ Format::RawHtml => serializer.serialize_str("rawHtml"),+ Format::Links => serializer.serialize_str("links"),+ Format::Images => serializer.serialize_str("images"),+ Format::Screenshot => serializer.serialize_str("screenshot"),+ Format::Summary => serializer.serialize_str("summary"),+ Format::ChangeTracking => serializer.serialize_str("changeTracking"),+ Format::Json => serializer.serialize_str("json"),+ Format::Attributes => serializer.serialize_str("attributes"),+ Format::Branding => serializer.serialize_str("branding"),+ Format::Audio => serializer.serialize_str("audio"),+ Format::Query(query) => query.serialize(serializer),+ }+ }+}++impl<'de> Deserialize<'de> for Format {+ fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>+ where+ D: Deserializer<'de>,+ {+ let value = Value::deserialize(deserializer)?;+ match value {+ Value::String(format) => match format.as_str() {+ "markdown" => Ok(Format::Markdown),+ "html" => Ok(Format::Html),+ "rawHtml" => Ok(Format::RawHtml),+ "links" => Ok(Format::Links),+ "images" => Ok(Format::Images),+ "screenshot" => Ok(Format::Screenshot),+ "summary" => Ok(Format::Summary),+ "changeTracking" => Ok(Format::ChangeTracking),+ "json" => Ok(Format::Json),+ "attributes" => Ok(Format::Attributes),+ "branding" => Ok(Format::Branding),+ "audio" => Ok(Format::Audio),+ _ => Err(de::Error::custom(format!("unknown format: {}", format))),+ },+ Value::Object(_) => QueryFormat::deserialize(value)+ .map(Format::Query)+ .map_err(de::Error::custom),+ _ => Err(de::Error::custom("format must be a string or object")),+ }+ }+}++/// Query format for asking a question about page content.+#[derive(Clone, Debug, PartialEq, Eq)]+pub struct QueryFormat {+ pub prompt: String,+ pub mode: Option<QueryFormatMode>,+}++#[derive(Deserialize, Serialize)]+#[serde(rename_all = "camelCase")]+struct QueryFormatWire {+ #[serde(rename = "type")]+ format_type: String,+ prompt: String,+ #[serde(skip_serializing_if = "Option::is_none")]+ mode: Option<QueryFormatMode>,+}++impl Serialize for QueryFormat {+ fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>+ where+ S: Serializer,+ {+ QueryFormatWire {+ format_type: "query".to_string(),+ prompt: self.prompt.clone(),+ mode: self.mode,+ }+ .serialize(serializer)+ }+}++impl<'de> Deserialize<'de> for QueryFormat {+ fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>+ where+ D: Deserializer<'de>,+ {+ let wire = QueryFormatWire::deserialize(deserializer)?;+ if wire.format_type != "query" {+ return Err(de::Error::custom(+ "query format object must have type query",+ ));+ }++ Ok(Self {+ prompt: wire.prompt,+ mode: wire.mode,+ })+ }+}++/// Query answer mode.+#[derive(Deserialize, Serialize, Clone, Copy, Debug, PartialEq, Eq)]+pub enum QueryFormatMode {+ #[serde(rename = "freeform")]+ Freeform,+ #[serde(rename = "directQuote")]+ DirectQuote,}/// Viewport dimensions for screenshots.