Skip to main content
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 direct responses and callback delivery.

​
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 directly. 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 direct response shape.

​
Method reference

KeywordTypeRequiredDescription
deploymentStringYesThe workflow deployment name
variantStringNoThe deployment variant name
inputsHashNoKey-value pairs for the variables defined on the Start step
async_modeBooleanNoWhen true, return immediately and deliver the result by signed callback
callback_urlStringNoRequired when async_mode: true - the HTTPS callback URL to call when the run finishes
userStringNoOpaque caller identifier surfaced in User Tracking
metadataHashNoFlat 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

​
Callback delivery

Pass async_mode: true to return immediately and have Fetch Hive call your callback URL 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 Callback Delivery and Webhook Triggers for the verification flow and signed payload shape.

​
Configuration

OptionDefaultDescription
api_keyENV["FETCH_HIVE_API_KEY"]Bearer token from the dashboard
base_urlhttps://api.fetchhive.com/v1Override the API base URL
timeout120Request timeout in seconds - increase for long-running direct workflow requests
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.

​
Next steps