> ## 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 prompt deployment from Ruby with the fetch_hive gem

Use the official `fetch_hive` gem when you want to invoke a prompt deployment from Ruby. The SDK wraps the public [`POST /v1/prompt/invoke`](../api-reference/invoke-prompt) endpoint with idiomatic helpers, handles authentication, and parses streaming responses into yielded hashes.

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

Invoke a prompt deployment and read the final response:

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

client = FetchHive::Client.new

result = client.invoke_prompt(
  deployment: "YOUR_DEPLOYMENT_NAME",
  variant: "YOUR_VARIANT_NAME",
  inputs: { text: "Fetch Hive helps teams ship AI products faster." }
)

puts result["response"]
```

`invoke_prompt` blocks until the prompt completes and returns the parsed JSON body as a hash. See the [non-streaming response shape](../api-reference/invoke-prompt#response).

## Method reference

| Keyword      | Type     | Required | Description                                                                                                       |
| ------------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `deployment` | `String` | Yes      | The prompt deployment name                                                                                        |
| `variant`    | `String` | No       | The deployment variant name                                                                                       |
| `inputs`     | `Hash`   | No       | Key-value pairs for the prompt variables                                                                          |
| `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) |

The SDK injects `streaming: false` for `invoke_prompt`. To stream, use `invoke_prompt_stream` (below).

## Handling the response

```ruby theme={null}
result = client.invoke_prompt(deployment: "my-prompt", variant: "default")

puts result["response"]      # final text
puts result["model"]         # model identifier
puts result["usage"]         # token usage breakdown
puts result["request_id"]    # use this to look up the run in Logs
```

## Streaming

Use `invoke_prompt_stream` to receive Server-Sent Events as they arrive. The method yields each parsed event hash to the block:

```ruby theme={null}
client.invoke_prompt_stream(
  deployment: "YOUR_DEPLOYMENT_NAME",
  variant: "YOUR_VARIANT_NAME",
  inputs: { text: "Fetch Hive helps teams ship AI products faster." }
) do |chunk|
  case chunk["type"]
  when "response"
    print chunk["response"]
    $stdout.flush
  when "usage"
    puts "\n\nUsage: #{chunk['usage']}"
  end
end
```

The stream yields the same event types documented in [Invoke Prompt → Response](../api-reference/invoke-prompt#response): `reasoning`, `response`, a final `usage` event, or an `error` event if the provider fails mid-stream.

If you omit the block, the method returns an `Enumerator` you can pass around:

```ruby theme={null}
enum = client.invoke_prompt_stream(deployment: "my-prompt", variant: "default")
enum.each { |chunk| handle(chunk) }
```

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

Non-2xx responses raise a `RuntimeError` with the status code and body. Rescue them if you need to handle failures:

```ruby theme={null}
begin
  result = client.invoke_prompt(deployment: "my-prompt", variant: "default")
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

* [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 Prompt](../api-reference/invoke-prompt) - Full endpoint reference