Skip to content

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

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.cs
index 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 ModelsTests
Assert.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.csproj
index 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.cs
new file mode 100644
index 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.exs
index 12db15dc3..479cf2217 100644
--- a/apps/elixir-sdk/mix.exs
+++ b/apps/elixir-sdk/mix.exs
@@ -1,7 +1,7 @@
defmodule Firecrawl.MixProject do
use Mix.Project
- @version "1.2.0"
+ @version "1.2.1"
@source_url "https://github.com/firecrawl/firecrawl/tree/main/apps/elixir-sdk"
def project do
diff --git a/apps/go-sdk/options.go b/apps/go-sdk/options.go
index 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.go
new file mode 100644
index 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.go
index 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.go
index 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.kts
index 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_11
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/QueryFormat.java b/apps/java-sdk/src/main/java/com/firecrawl/models/QueryFormat.java
new file mode 100644
index 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.java
index 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.java
index 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 {
@Test
void 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.json
index 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.ts
index 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.php
index 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 ParseOptions
if ($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.php
new file mode 100644
index 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.php
index 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 ScrapeOptions
if ($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 ScrapeOptions
return $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.php
index 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.php
index 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__.py
index 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 project
logger: logging.Logger = logging.getLogger("firecrawl")
diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_validation.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/utils/test_validation.py
index 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, PDFParser
from 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 defaults
diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.py
index 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"]] = None
FormatOption = Union[
diff --git a/apps/python-sdk/firecrawl/v2/utils/validation.py b/apps/python-sdk/firecrawl/v2/utils/validation.py
index 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_obj
diff --git a/apps/ruby-sdk/lib/firecrawl.rb b/apps/ruby-sdk/lib/firecrawl.rb
index 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.rb
index 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 Firecrawl
def to_h
{
- "formats" => formats,
+ "formats" => formats&.map { |fmt| format_value(fmt) },
"headers" => headers,
"includeTags" => include_tags,
"excludeTags" => exclude_tags,
@@ -69,6 +69,10 @@ module Firecrawl
fmt.respond_to?(:type) ? fmt.type : nil
end
end
+
+ def format_value(fmt)
+ fmt.respond_to?(:to_h) ? fmt.to_h : fmt
+ end
end
end
end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/query_format.rb b/apps/ruby-sdk/lib/firecrawl/models/query_format.rb
new file mode 100644
index 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
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rb b/apps/ruby-sdk/lib/firecrawl/models/scrape_options.rb
index 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 Firecrawl
def 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,
}.compact
end
+
+ private
+
+ def format_value(fmt)
+ fmt.respond_to?(:to_h) ? fmt.to_h : fmt
+ end
end
end
end
diff --git a/apps/ruby-sdk/lib/firecrawl/version.rb b/apps/ruby-sdk/lib/firecrawl/version.rb
index 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: true
module Firecrawl
- VERSION = "1.3.0"
+ VERSION = "1.3.1"
end
diff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rb
index 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::Test
refute h.key?("timeout") # nil values should be omitted
end
+ 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_false
opts = Firecrawl::Models::ScrapeOptions.new
assert_equal false, opts.skip_tls_verification
diff --git a/apps/rust-sdk/Cargo.lock b/apps/rust-sdk/Cargo.lock
index 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.toml
index 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.rs
index 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.rs
index 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.