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

> Start a Hive Agent run from Ruby with the fetch_hive gem

Use the official `fetch_hive` gem when you want to start a Hive Agent run from Ruby. The SDK wraps the public [`POST /v1/hive-agent/invoke`](../api-reference/hive-agents/invoke) endpoint with an idiomatic helper and handles authentication.

Hive Agent invocation does not stream and does not wait for the final answer in the HTTP response. The SDK returns identifiers immediately, then Fetch Hive sends a signed callback when the run completes, fails, or is cancelled.

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

Start a Hive Agent run and read the accepted response:

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

client = FetchHive::Client.new

result = client.invoke_hive_agent(
  hive_agent: "YOUR_HIVE_AGENT_ID",
  objective: "Research competitors and summarize verified findings",
  callback_url: "https://example.com/hive-agent-callback",
  sources: { website_urls: ["https://example.com"] },
  metadata: { customer_id: "cus_123" }
)

puts result["run_id"]
puts result["request_id"]
puts result["webhook_secret"]
```

`invoke_hive_agent` returns the parsed JSON body as a hash as soon as the run is queued. See the [accepted response shape](../api-reference/hive-agents/invoke#response).

## Method reference

| Keyword        | Type     | Required | Description                                                                                                       |
| -------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `hive_agent`   | `String` | Yes      | The Hive Agent ID from the dashboard                                                                              |
| `objective`    | `String` | Yes      | Specific objective for the planner to create work nodes from                                                      |
| `callback_url` | `String` | Yes      | HTTPS URL that receives the signed terminal callback                                                              |
| `sources`      | `Hash`   | No       | Grounded context from websites, assets, or knowledge bases in the workspace                                       |
| `metadata`     | `Hash`   | No       | Flat caller-defined metadata for audit and log filtering. See [Invoke metadata](../user-tracking/invoke-metadata) |

The SDK always sends `async.enabled: true` with your `callback_url`. Hive Agent invocation is async-only.

## Handling the response

Fetch Hive returns `202 Accepted` when the run is queued. Store `webhook_secret` so your callback receiver can verify `X-Fetch-Hive-Signature`.

```ruby theme={null}
result = client.invoke_hive_agent(
  hive_agent: "YOUR_HIVE_AGENT_ID",
  objective: "Research competitors and summarize verified findings",
  callback_url: "https://example.com/hive-agent-callback"
)

puts result["run_id"]          # queued run identifier
puts result["request_id"]      # use this to look up the run in Logs
puts result["status"]          # usually "pending"
puts result["webhook_secret"]  # verify the signed callback
```

Open [Logs](./logs) to inspect status, trace, costs, node output, callback attempts, and the final response.

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

```ruby theme={null}
client = FetchHive::Client.new(
  api_key: "fhk_...",
  base_url: "https://api.fetchhive.com/v1",
  timeout: 60
)
```

## Errors

Missing `callback_url` raises `ArgumentError` before a request is sent. Non-2xx responses raise a `RuntimeError` with the status code and body:

```ruby theme={null}
begin
  result = client.invoke_hive_agent(
    hive_agent: "YOUR_HIVE_AGENT_ID",
    objective: "Research competitors and summarize verified findings",
    callback_url: "https://example.com/hive-agent-callback"
  )
rescue => e
  warn "Fetch Hive error: #{e.message}"
end
```

See [Errors and Rate Limits](../api-reference/errors-and-rate-limits) for 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

* [Invoke from Code](./invoke-from-code) - Overview of starting runs from your app
* [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](../api-reference/hive-agents/invoke) - Full endpoint reference