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 endpoint with idiomatic helpers, handles authentication, and parses streaming responses into yielded hashes.

Installation

Add to your Gemfile:

gem "fetch_hive"

Then run:

bundle install

Or install directly:

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):

export FETCH_HIVE_API_KEY=fhk_...

require "fetch_hive"

client = FetchHive::Client.new

Or pass the key explicitly:

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

See API Keys for how to create and rotate keys.

Basic example

Invoke a prompt deployment and read the final response:

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.

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
metadata	Hash	No	Flat caller-defined metadata for audit and log filtering. See Invoke metadata

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

Handling the response

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:

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

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

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:

begin
  result = client.invoke_prompt(deployment: "my-prompt", variant: "default")
rescue => e
  warn "Fetch Hive error: #{e.message}"
end

See Errors and Rate Limits for status code meanings.

Links

• Gem on RubyGems

• Source on GitHub

Next steps

• Run with API - The same flow with cURL

• Run with Python SDK

• Run with Node.js SDK

• Run with PHP SDK

• Invoke Prompt - Full endpoint reference