> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](../api-reference/invoke-workflow) endpoint, handles authentication, and supports both direct responses and callback delivery.

## Installation

Add to your `Gemfile`:

```ruby theme={null}
gem "fetch_hive"
```

Then run:

```bash theme={null}
bundle install
```

Or install directly:

```bash theme={null}
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):

```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```

```ruby theme={null}
require "fetch_hive"

client = FetchHive::Client.new
```

Or pass the key explicitly:

```ruby theme={null}
client = FetchHive::Client.new(api_key: "fhk_...")
```

See [API Keys](../workspace/api-keys) for how to create and rotate keys.

## Basic example

Run a workflow deployment directly. The call blocks until the workflow finishes:

```ruby theme={null}
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](../api-reference/invoke-workflow#response).

## 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](../user-tracking/overview)                                   |
| `metadata`     | `Hash`    | No       | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |

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

```json theme={null}
{
  "async": { "enabled": true, "callback_url": "https://example.com/webhook" }
}
```

## Handling the response

```ruby theme={null}
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:

```ruby theme={null}
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](./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 direct workflow requests |

```ruby theme={null}
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:

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

See [Error Handling](./error-handling) for workflow-specific failure cases and [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for HTTP status code meanings.

## Links

* [Gem on RubyGems](https://rubygems.org/gems/fetch_hive)
* [Source on GitHub](https://github.com/Fetch-Hive/ruby-sdk)

## Next steps

* [Callback Delivery and Webhook Triggers](./async-and-webhooks) - Verify callback signatures
* [Run with API](./run-with-api) - The same flow with cURL
* [Run with Python SDK](./run-with-python-sdk)
* [Run with Node.js SDK](./run-with-nodejs-sdk)
* [Run with PHP SDK](./run-with-php-sdk)
* [Invoke Workflow](../api-reference/invoke-workflow) - Full endpoint reference