Run with Ruby SDK

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

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 by signed callback
`callback_url`	`String`	No	Required when `async_mode: true` - the HTTPS callback 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

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

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

Callback Delivery and Webhook Triggers - 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

Getting Started

Live Chat

Prompts

Workflows

Hive Agents

Agents

Knowledge Bases

Experiments

Your Workspace

Monitoring

User Tracking

Resources

Installation

Authentication

Basic example

Method reference

Handling the response

Callback delivery

Configuration

Errors

Links

Next steps

​Installation

​Authentication

​Basic example

​Method reference

​Handling the response

​Callback delivery

​Configuration

​Errors

​Links

​Next steps

Installation

Authentication

Basic example

Method reference

Handling the response

Callback delivery

Configuration

Errors

Links

Next steps