Skip to content

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

feat(ruby): add get_parse_formats for GET /v2/parse/formats (#4906)

Gergő Móriczf0d98bd8660b
diff --git a/apps/ruby-sdk/README.md b/apps/ruby-sdk/README.md
index c83a21d19..79398a653 100644
--- a/apps/ruby-sdk/README.md
+++ b/apps/ruby-sdk/README.md
@@ -126,6 +126,15 @@ doc = client.parse(file,
puts doc.markdown
```
+List the file formats the parse endpoint accepts. `available` is `false` for
+formats the deployment can't currently handle (e.g. images when OCR is off).
+
+```ruby
+client.get_parse_formats.each do |f|
+ puts "#{f.format} (#{f.kind}) #{f.extensions.join(", ")} #{f.mime_types.join(", ")} available=#{f.available}"
+end
+```
+
### Crawl
```ruby
diff --git a/apps/ruby-sdk/lib/firecrawl.rb b/apps/ruby-sdk/lib/firecrawl.rb
index 71a7fb7f7..ceda485a1 100644
--- a/apps/ruby-sdk/lib/firecrawl.rb
+++ b/apps/ruby-sdk/lib/firecrawl.rb
@@ -22,6 +22,7 @@ require_relative "firecrawl/models/search_options"
require_relative "firecrawl/models/search_data"
require_relative "firecrawl/models/parse_file"
require_relative "firecrawl/models/parse_options"
+require_relative "firecrawl/models/parse_format"
require_relative "firecrawl/models/agent_options"
require_relative "firecrawl/models/agent_response"
require_relative "firecrawl/models/agent_list_response"
diff --git a/apps/ruby-sdk/lib/firecrawl/client.rb b/apps/ruby-sdk/lib/firecrawl/client.rb
index 25b9b334d..1c3808f56 100644
--- a/apps/ruby-sdk/lib/firecrawl/client.rb
+++ b/apps/ruby-sdk/lib/firecrawl/client.rb
@@ -195,6 +195,15 @@ module Firecrawl
Models::Document.new(data)
end
+ # Lists the file formats accepted by {#parse} on this deployment.
+ #
+ # @return [Array<Models::ParseFormat>]
+ def get_parse_formats
+ raw = @http.get("/v2/parse/formats")
+ formats = (raw["data"] || {})["formats"] || []
+ formats.map { |f| Models::ParseFormat.new(f) }
+ end
+
# ================================================================
# CRAWL
# ================================================================
diff --git a/apps/ruby-sdk/lib/firecrawl/models/parse_format.rb b/apps/ruby-sdk/lib/firecrawl/models/parse_format.rb
new file mode 100644
index 000000000..90701228c
--- /dev/null
+++ b/apps/ruby-sdk/lib/firecrawl/models/parse_format.rb
@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Firecrawl
+ module Models
+ # A file format accepted by the `/v2/parse` endpoint.
+ #
+ # `kind` is usually one of {KIND_DOCUMENT} or {KIND_IMAGE}, but newer API
+ # versions may return other values, which are kept as-is.
+ class ParseFormat
+ KIND_DOCUMENT = "document"
+ KIND_IMAGE = "image"
+
+ attr_reader :format, :kind, :extensions, :mime_types, :available
+
+ def initialize(data)
+ @format = data["format"]
+ @kind = data["kind"]
+ @extensions = data["extensions"] || []
+ @mime_types = data["mimeTypes"] || []
+ @available = data["available"]
+ end
+
+ def document?
+ kind == KIND_DOCUMENT
+ end
+
+ def image?
+ kind == KIND_IMAGE
+ end
+
+ def to_s
+ "ParseFormat{format=#{format}, kind=#{kind}, available=#{available}}"
+ end
+ end
+ end
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/version.rb b/apps/ruby-sdk/lib/firecrawl/version.rb
index ea1723f97..b24f94d6a 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.17.0"
+ VERSION = "1.17.1"
end
diff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rb
index eda8d3630..d75929894 100644
--- a/apps/ruby-sdk/test/firecrawl/client_test.rb
+++ b/apps/ruby-sdk/test/firecrawl/client_test.rb
@@ -834,6 +834,86 @@ class ClientTest < Minitest::Test
assert_equal 1000, result.plan_credits
end
+ # ================================================================
+ # PARSE FORMATS
+ # ================================================================
+
+ def test_get_parse_formats
+ stub_request(:get, "#{BASE_URL}/v2/parse/formats")
+ .with(headers: { "Authorization" => "Bearer #{API_KEY}" })
+ .to_return(
+ status: 200,
+ body: JSON.generate(success: true, data: { formats: [
+ { format: "pdf", kind: "document", extensions: [".pdf"], mimeTypes: ["application/pdf"], available: true },
+ { format: "png", kind: "image", extensions: [".png"], mimeTypes: ["image/png"], available: false },
+ ] }),
+ headers: { "Content-Type" => "application/json" }
+ )
+
+ formats = @client.get_parse_formats
+
+ assert_requested :get, "#{BASE_URL}/v2/parse/formats", times: 1
+ assert_equal 2, formats.size
+ pdf, png = formats
+ assert_instance_of Firecrawl::Models::ParseFormat, pdf
+ assert_equal "pdf", pdf.format
+ assert_equal Firecrawl::Models::ParseFormat::KIND_DOCUMENT, pdf.kind
+ assert pdf.document?
+ refute pdf.image?
+ assert_equal [".pdf"], pdf.extensions
+ assert_equal ["application/pdf"], pdf.mime_types
+ assert_equal true, pdf.available
+ assert_equal "png", png.format
+ assert png.image?
+ assert_equal ["image/png"], png.mime_types
+ assert_equal false, png.available
+ end
+
+ def test_get_parse_formats_tolerates_unknown_kind_and_fields
+ stub_request(:get, "#{BASE_URL}/v2/parse/formats")
+ .to_return(
+ status: 200,
+ body: JSON.generate(success: true, data: { formats: [
+ { format: "mp4", kind: "video", extensions: [".mp4"], mimeTypes: ["video/mp4"], available: true, maxSizeMb: 50 },
+ ] }),
+ headers: { "Content-Type" => "application/json" }
+ )
+
+ format = @client.get_parse_formats.first
+ assert_equal "mp4", format.format
+ assert_equal "video", format.kind
+ refute format.document?
+ refute format.image?
+ assert_equal ["video/mp4"], format.mime_types
+ assert_equal true, format.available
+ end
+
+ def test_get_parse_formats_authentication_error
+ stub_request(:get, "#{BASE_URL}/v2/parse/formats")
+ .to_return(
+ status: 401,
+ body: JSON.generate(error: "Invalid API key"),
+ headers: { "Content-Type" => "application/json" }
+ )
+
+ error = assert_raises(Firecrawl::AuthenticationError) { @client.get_parse_formats }
+ assert_equal 401, error.status_code
+ end
+
+ def test_get_parse_formats_server_error
+ client = Firecrawl::Client.new(api_key: API_KEY, max_retries: 0, backoff_factor: 0.0)
+ stub_request(:get, "#{BASE_URL}/v2/parse/formats")
+ .to_return(
+ status: 500,
+ body: JSON.generate(error: "Internal server error"),
+ headers: { "Content-Type" => "application/json" }
+ )
+
+ error = assert_raises(Firecrawl::FirecrawlError) { client.get_parse_formats }
+ assert_equal 500, error.status_code
+ assert_equal "Internal server error", error.message
+ end
+
# ================================================================
# ERROR HANDLING
# ================================================================