firecrawl-sdk 1.17.0 → 1.17.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4692141ed256c6cf62171578f7bfdbb852ddb915a60b48ba520a73ecc8885b1
-  data.tar.gz: ff206e069d080e13598824ff3faa7eaf86b89b2cacbc051cd53aa861b20d1977
+  metadata.gz: 02dbea25069649d09dd507af8b1e2fed0010c8c5d454ee04117261d3e8a2dbc0
+  data.tar.gz: c0b3d3596a2f68d8d26c976f707db9cbc407da5eda3f3d2b3547ed1affcace6f
 SHA512:
-  metadata.gz: 83a86911be8bfd5b9736bbfbe610c40934b31a9e6da25de714972be4399c9374421955e2b0ef5e41b6a15c0829c3c3ff30dbc1004a75c9a6210182f0df620399
-  data.tar.gz: 9ca272944fc87bf14462b30e0f7f99239a1253ca11c88c1d7393469f52491362e0a72f7c5e354467e0f154c1e780aa08732e162fdc2345832ffe0d4779f98bc9
+  metadata.gz: c1875f25b8ccebed6d9af7f31a0941f777a9c46ff448cedb428c8440a26b8e25927683d7bd86ad0ad35d81c3a762121c8e7051f83f8bdcf1e85749aa7667650d
+  data.tar.gz: 40fef9f8bb7032e9fb3bc55695af46e716b243c885faf7088acd6d6a14834482ba1b070e9f28409d4b0925bc2a7511d34ce3c1341a746aa98467d352c5409de2

data/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
@@ -194,6 +203,17 @@ status = client.agent(
     urls: ["https://example.com"]
   ))
 puts status.data
+
+# Use Alexandria data providers connected in the dashboard
+status = client.agent(
+  Firecrawl::Models::AgentOptions.new(
+    prompt: "Find the work email of the CEO of example.com",
+    exchange: Firecrawl::Models::AgentExchangeOptions.new(
+      enabled: true,
+      toolkits: ["apollo"]
+    )
+  ))
+puts status.exchange&.paid_calls
 ```
 
 ### Usage & Metrics

data/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
     # ================================================================

data/lib/firecrawl/models/agent_exchange_options.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # Alexandria (Exchange) options for an agent run, forwarded verbatim; the
+    # server owns every default and limit. On a follow-up turn, omitting the
+    # exchange options inherits the previous turn's settings.
+    #
+    # on_terms_required: "skip" or "ask".
+    class AgentExchangeOptions
+      # Answers the previous turn's pending approval. A "terms" approval is
+      # accepted as a whole, so call_ids and always are ignored on it.
+      class Approve
+        attr_reader :approval_id, :call_ids, :always
+
+        def initialize(approval_id:, call_ids: nil, always: nil)
+          @approval_id = approval_id
+          @call_ids = call_ids
+          @always = always
+        end
+
+        def to_h
+          {
+            "approvalId" => approval_id,
+            "callIds" => call_ids,
+            "always" => always,
+          }.compact
+        end
+      end
+
+      # Refuses the previous turn's pending approval.
+      class Decline
+        attr_reader :approval_id
+
+        def initialize(approval_id:)
+          @approval_id = approval_id
+        end
+
+        def to_h
+          { "approvalId" => approval_id }
+        end
+      end
+
+      FIELDS = %i[
+        enabled toolkits max_calls require_approval approve decline
+        on_terms_required
+      ].freeze
+
+      attr_reader(*FIELDS)
+
+      def initialize(**kwargs)
+        FIELDS.each { |f| instance_variable_set(:"@#{f}", kwargs[f]) }
+      end
+
+      def to_h
+        {
+          "enabled" => enabled,
+          "toolkits" => toolkits,
+          "maxCalls" => max_calls,
+          "requireApproval" => require_approval,
+          "approve" => approve&.to_h,
+          "decline" => decline&.to_h,
+          "onTermsRequired" => on_terms_required,
+        }.compact
+      end
+    end
+  end
+end

data/lib/firecrawl/models/agent_exchange_summary.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # What an agent run did with Alexandria (Exchange). toolkits and
+    # require_approval are what the run resolved to after thread inheritance.
+    class AgentExchangeSummary
+      # A provider that needs data terms the team has not accepted, so the run
+      # did not use it.
+      class SkippedProvider
+        attr_reader :provider, :name, :capability, :adds, :reason, :version,
+                    :terms_url
+
+        def initialize(data)
+          @provider = data["provider"]
+          @name = data["name"]
+          @capability = data["capability"]
+          @adds = data["adds"]
+          @reason = data["reason"]
+          @version = data["version"]
+          @terms_url = data["termsUrl"]
+        end
+      end
+
+      # The Exchange calls to view and accept providers' terms ("ask" mode).
+      # Nothing here runs for you; only call accept after your user agrees.
+      class TermsRequiredAction
+        # show and accept are the raw Exchange calls ("provider",
+        # "capability", "options").
+        class Provider
+          attr_reader :provider, :name, :capability, :adds, :version, :digest,
+                      :url, :show, :accept
+
+          def initialize(data)
+            @provider = data["provider"]
+            @name = data["name"]
+            @capability = data["capability"]
+            @adds = data["adds"]
+            @version = data["version"]
+            @digest = data["digest"]
+            @url = data["url"]
+            @show = data["show"]
+            @accept = data["accept"]
+          end
+        end
+
+        attr_reader :type, :approval_id, :providers
+
+        def initialize(data)
+          @type = data["type"]
+          @approval_id = data["approvalId"]
+          @providers = data["providers"]&.map { |p| Provider.new(p) }
+        end
+      end
+
+      attr_reader :enabled, :toolkits, :require_approval, :on_terms_required,
+                  :paid_calls, :credits_used, :skipped_providers,
+                  :requires_action
+
+      def initialize(data)
+        @enabled = data["enabled"]
+        @toolkits = data["toolkits"]
+        @require_approval = data["requireApproval"]
+        @on_terms_required = data["onTermsRequired"]
+        @paid_calls = data["paidCalls"]
+        @credits_used = data["creditsUsed"]
+        @skipped_providers = data["skippedProviders"]&.map { |p| SkippedProvider.new(p) }
+        @requires_action = data["requiresAction"] && TermsRequiredAction.new(data["requiresAction"])
+      end
+    end
+  end
+end

data/lib/firecrawl/models/agent_options.rb

@@ -6,10 +6,14 @@ module Firecrawl
     #
     # effort: valid values are "low", "medium", and "high"; sets the reasoning
     # budget for the run (every level runs spark-2).
+    #
+    # thread_id continues an existing thread as its next turn; omitted starts a
+    # new thread. mode: "extract" or "chat".
     class AgentOptions
       FIELDS = %i[
         urls prompt schema integration max_credits
         strict_constrain_to_urls model effort webhook audit_metadata
+        thread_id mode exchange
       ].freeze
 
       attr_reader(*FIELDS)
@@ -34,6 +38,9 @@ module Firecrawl
           "effort" => effort,
           "webhook" => webhook.is_a?(Hash) ? webhook : webhook&.to_h,
           "auditMetadata" => audit_metadata&.to_h,
+          "threadId" => thread_id,
+          "mode" => mode,
+          "exchange" => exchange&.to_h,
         }.compact
       end
     end

data/lib/firecrawl/models/agent_pending_approval.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # A turn that ended waiting for the caller. kind "calls" (or nil on older
+    # runs) holds paid calls to allow or refuse; kind "terms" lists providers
+    # whose data terms need accepting, with calls empty. Answer it on the next
+    # turn of the thread with AgentExchangeOptions approve or decline.
+    class AgentPendingApproval
+      # input and more are the raw call arguments.
+      class Call
+        attr_reader :id, :provider, :capability, :input, :more,
+                    :credits_estimate
+
+        def initialize(data)
+          @id = data["id"]
+          @provider = data["provider"]
+          @capability = data["capability"]
+          @input = data["input"]
+          @more = data["more"]
+          @credits_estimate = data["creditsEstimate"]
+        end
+      end
+
+      class TermsGate
+        attr_reader :provider, :name, :logo, :capability, :adds, :version,
+                    :digest, :url
+
+        def initialize(data)
+          @provider = data["provider"]
+          @name = data["name"]
+          @logo = data["logo"]
+          @capability = data["capability"]
+          @adds = data["adds"]
+          @version = data["version"]
+          @digest = data["digest"]
+          @url = data["url"]
+        end
+      end
+
+      class Resolution
+        attr_reader :approved, :call_ids, :always, :by_run_id
+
+        def initialize(data)
+          @approved = data["approved"]
+          @call_ids = data["callIds"]
+          @always = data["always"]
+          @by_run_id = data["byRunId"]
+        end
+      end
+
+      attr_reader :id, :kind, :reason, :calls, :terms, :resolution
+
+      def initialize(data)
+        @id = data["id"]
+        @kind = data["kind"]
+        @reason = data["reason"]
+        @calls = data["calls"]&.map { |c| Call.new(c) }
+        @terms = data["terms"]&.map { |t| TermsGate.new(t) }
+        @resolution = data["resolution"] && Resolution.new(data["resolution"])
+      end
+    end
+  end
+end

data/lib/firecrawl/models/agent_response.rb

@@ -4,12 +4,15 @@ module Firecrawl
   module Models
     # Response from starting an agent task.
     class AgentResponse
-      attr_reader :success, :id, :error
+      attr_reader :success, :id, :error, :thread_id, :thread_turn
 
       def initialize(data)
         @success = data["success"]
         @id = data["id"]
         @error = data["error"]
+        # Pass thread_id back in AgentOptions to continue the conversation.
+        @thread_id = data["threadId"]
+        @thread_turn = data["threadTurn"]
       end
 
       def to_s

data/lib/firecrawl/models/agent_status_response.rb

@@ -4,7 +4,9 @@ module Firecrawl
   module Models
     # Status response for monitoring agent tasks.
     class AgentStatusResponse
-      attr_reader :status, :data, :credits_used, :expires_at, :effort
+      attr_reader :status, :data, :credits_used, :expires_at, :effort,
+                  :thread_id, :thread_turn, :mode, :message, :pending_approval,
+                  :exchange
 
       def initialize(raw)
         @status = raw["status"]
@@ -13,6 +15,13 @@ module Firecrawl
         @expires_at = raw["expiresAt"]
         # The effort the job ran with; only present for runs that specified it.
         @effort = raw["effort"]
+        @thread_id = raw["threadId"]
+        @thread_turn = raw["threadTurn"]
+        @mode = raw["mode"]
+        # Chat-mode runs answer here instead of in data.
+        @message = raw["message"]
+        @pending_approval = raw["pendingApproval"] && AgentPendingApproval.new(raw["pendingApproval"])
+        @exchange = raw["exchange"] && AgentExchangeSummary.new(raw["exchange"])
       end
 
       def done?

data/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

data/lib/firecrawl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Firecrawl
-  VERSION = "1.17.0"
+  VERSION = "1.17.3"
 end

data/lib/firecrawl.rb

@@ -22,9 +22,13 @@ 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_exchange_options"
 require_relative "firecrawl/models/agent_options"
 require_relative "firecrawl/models/agent_response"
 require_relative "firecrawl/models/agent_list_response"
+require_relative "firecrawl/models/agent_exchange_summary"
+require_relative "firecrawl/models/agent_pending_approval"
 require_relative "firecrawl/models/agent_status_response"
 require_relative "firecrawl/models/agent_trace_response"
 require_relative "firecrawl/models/agent_snapshot_response"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: firecrawl-sdk
 version: !ruby/object:Gem::Version
-  version: 1.17.0
+  version: 1.17.3
 platform: ruby
 authors:
 - Firecrawl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-08 00:00:00.000000000 Z
+date: 2026-10-06 00:00:00.000000000 Z
 dependencies: []
 description: A type-safe Ruby client for the Firecrawl v2 API. Supports scraping,
   crawling, batch scraping, URL mapping, web search, and AI agent operations.
@@ -24,8 +24,11 @@ files:
 - lib/firecrawl/client.rb
 - lib/firecrawl/errors.rb
 - lib/firecrawl/http_client.rb
+- lib/firecrawl/models/agent_exchange_options.rb
+- lib/firecrawl/models/agent_exchange_summary.rb
 - lib/firecrawl/models/agent_list_response.rb
 - lib/firecrawl/models/agent_options.rb
+- lib/firecrawl/models/agent_pending_approval.rb
 - lib/firecrawl/models/agent_response.rb
 - lib/firecrawl/models/agent_snapshot_response.rb
 - lib/firecrawl/models/agent_status_response.rb
@@ -45,6 +48,7 @@ files:
 - lib/firecrawl/models/menu_profile.rb
 - lib/firecrawl/models/monitor.rb
 - lib/firecrawl/models/parse_file.rb
+- lib/firecrawl/models/parse_format.rb
 - lib/firecrawl/models/parse_options.rb
 - lib/firecrawl/models/pdf_parser.rb
 - lib/firecrawl/models/product_profile.rb