# 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`](/api-reference/invoke-workflow.md) endpoint, handles authentication, and supports both synchronous and asynchronous runs.

## Installation

Add to your `Gemfile`:

```ruby
gem "fetch_hive"
```

Then run:

```bash
bundle install
```

Or install directly:

```bash
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
export FETCH_HIVE_API_KEY=fhk_...
```

```ruby
require "fetch_hive"

client = FetchHive::Client.new
```

Or pass the key explicitly:

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

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

## Basic example

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

```ruby
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](/api-reference/invoke-workflow.md#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 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](/user-tracking/user-tracking.md)  |

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

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

## Handling the response

```ruby
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:

```ruby
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](/workflows/async-and-webhooks.md) 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 |

```ruby
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
begin
  run = client.invoke_workflow(deployment: "my-workflow", variant: "default")
rescue => e
  warn "Fetch Hive error: #{e.message}"
end
```

See [Error Handling](/workflows/error-handling.md) for workflow-specific failure cases and [Errors and Rate Limits](/api-reference/errors-and-rate-limits.md) 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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fetchhive.com/workflows/run-with-ruby-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.