# Run with Ruby SDK

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

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

Invoke a prompt deployment and read the final response:

```ruby
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.md#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/user-tracking.md) |

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

## Handling the response

```ruby
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
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.md#response): `reasoning`, `response`, and a final `usage` event.

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

```ruby
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
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
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.md) 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](/prompts/run-with-api.md) - The same flow with cURL
* [Run with Python SDK](/prompts/run-with-python-sdk.md)
* [Run with Node.js SDK](/prompts/run-with-nodejs-sdk.md)
* [Run with PHP SDK](/prompts/run-with-php-sdk.md)
* [Invoke Prompt](/api-reference/invoke-prompt.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/prompts/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.