Run with Ruby SDK

Invoke a workflow deployment from Ruby with the fetch_hive gem

Use the official fetch_hive gem when you want to invoke a workflow deployment from Ruby. The SDK wraps the public POST /v1/workflow/invoke endpoint, handles authentication, and supports both synchronous and asynchronous runs.

Installation

Add to your Gemfile:

gem "fetch_hive"

Then run:

bundle install

Or install directly:

gem install fetch_hive

The gem uses faraday under the hood and supports Ruby 3.0+.

Authentication

Set the FETCH_HIVE_API_KEY environment variable to your workspace API key (the client reads it automatically):

export FETCH_HIVE_API_KEY=fhk_...

require "fetch_hive"

client = FetchHive::Client.new

Or pass the key explicitly:

client = FetchHive::Client.new(api_key: "fhk_...")

See API Keys for how to create and rotate keys.

Basic example

Run a workflow deployment synchronously — the call blocks until the workflow finishes:

require "fetch_hive"

client = FetchHive::Client.new

run = client.invoke_workflow(
  deployment: "YOUR_DEPLOYMENT_NAME",
  variant: "YOUR_VARIANT_NAME",
  inputs: { topic: "State of enterprise AI in 2026" }
)

puts run["run_status"]
puts run["output"]

See the sync response shape.

Method reference

Keyword	Type	Required	Description
deployment	String	Yes	The workflow deployment name
variant	String	No	The deployment variant name
inputs	Hash	No	Key-value pairs for the variables defined on the Start step
async_mode	Boolean	No	When true, return immediately and deliver the result via webhook
callback_url	String	No	Required when async_mode: true — the HTTPS webhook URL to call when the run finishes
user	String	No	Opaque caller identifier surfaced in User Tracking
metadata	Hash	No	Flat caller-defined metadata for audit and log filtering. See Invoke metadata

invoke_workflow builds the request body for you. When you pass async_mode: true, the SDK sends:

{
  "async": { "enabled": true, "callback_url": "https://example.com/webhook" }
}

Handling the response

run = client.invoke_workflow(deployment: "my-workflow", variant: "default")

puts run["run_status"]    # "completed" | "failed" | "running" | "queued"
puts run["output"]        # final workflow output
puts run["request_id"]    # use this to look up the run in Logs

Async runs and webhooks

Pass async_mode: true to queue the workflow and have Fetch Hive call your webhook when the run finishes:

run = client.invoke_workflow(
  deployment: "YOUR_DEPLOYMENT_NAME",
  variant: "YOUR_VARIANT_NAME",
  inputs: { topic: "State of enterprise AI in 2026" },
  async_mode: true,
  callback_url: "https://example.com/callback"
)

puts "Queued: #{run['run_status']}"
puts "Webhook secret: #{run['webhook_secret']}"

Store the webhook_secret so you can verify the signature on the incoming callback. See Async and Webhooks for the verification flow and signed payload shape.

Configuration

Option	Default	Description
api_key	ENV["FETCH_HIVE_API_KEY"]	Bearer token from the dashboard
base_url	https://api.fetchhive.com/v1	Override the API base URL
timeout	120	Request timeout in seconds — increase for long-running synchronous workflows

client = FetchHive::Client.new(
  api_key: "fhk_...",
  base_url: "https://api.fetchhive.com/v1",
  timeout: 600
)

Errors

Non-2xx responses raise a RuntimeError with the status code and body. Rescue them if you need to handle failures:

begin
  run = client.invoke_workflow(deployment: "my-workflow", variant: "default")
rescue => e
  warn "Fetch Hive error: #{e.message}"
end

See Error Handling for workflow-specific failure cases and Errors and Rate Limits for HTTP status code meanings.

Links

• Gem on RubyGems

• Source on GitHub

Next steps

• Async and Webhooks - Verify callback signatures

• Run with API - The same flow with cURL

• Run with Python SDK

• Run with Node.js SDK

• Run with PHP SDK

• Invoke Workflow - Full endpoint reference