riveter-sdk

Official Ruby SDK for the Riveter API — enrich data, build datasets, scrape pages, and run web searches.

Requires Ruby 3.1+. Zero runtime dependencies (stdlib Net::HTTP).

Install

gem install riveter-sdk

Or in a Gemfile:

gem "riveter-sdk", require: "riveter"

Quickstart

require "riveter"

# Reads ENV["RIVETER_API_KEY"] when api_key: is not passed.
# Get a key at https://app.riveterhq.com/settings/api
riveter = Riveter::Client.new(api_key: "YOUR_API_KEY")

run = riveter.enrich(
  prompt: "Research each company",
  attributes: ["CEO", "Employee Count"],
  input: { "Company" => ["Apple", "Google"] }
)

result = riveter.runs.wait_for_result(run.id)
puts result.output

The run lifecycle

Every async kickoff (enrich, datasets.build, extractions.run, ...) returns a run.

riveter.runs.get(run.id)                           # status + progress
riveter.runs.result(run.id, wait: 50)              # output (long-polls up to 50s)
riveter.runs.wait_for_result(run.id, timeout: 600) # poll until finished
riveter.runs.stop(run.id)                          # stop early

List runs with automatic pagination:

riveter.runs.list(status: "success").auto_paging_each do |run|
  puts run.id
end

Surface

  • riveter.enrich(...), riveter.quick_search(...), riveter.scrape(...), riveter.account
  • riveter.runs — get, result, stop, list, summary, wait_for_result
  • riveter.enrichments — list, create, get, update, build_dataset
  • riveter.datasets — build, extend_dataset
  • riveter.configured_datasets — build
  • riveter.extractions — create, get, run
  • riveter.monitors — create, list, get, update, runs

Responses are lightweight model objects; fields the SDK does not know yet stay reachable via #raw / #[].

Errors and retries

API failures raise Riveter::APIError with #status, #type (not_found, insufficient_credits, ...), #message, and optional #details. Network failures raise Riveter::APIConnectionError / Riveter::APITimeoutError. 429s are retried automatically using the X-RateLimit-Reset header; 5xx and network failures are retried for GETs. Configure with max_retries: and timeout:.

Options

Riveter::Client.new(
  api_key: "...",                           # default: ENV["RIVETER_API_KEY"]
  base_url: "https://api.riveterhq.com/v1", # default: ENV["RIVETER_BASE_URL"], then this
  timeout: 60,                              # keep above 50 for `wait` long-polls
  max_retries: 2
)

Development

bundle install
bundle exec rspec