v4

Ruby SDK

View as markdown

The official Ruby client for the Synthient API: IP and domain lookups, account details, real-time feed streams, and Parquet exports.

The generated reference for the client, feeds, and errors is on RubyDoc.info. It lists the response and event models only as constants, without their fields, so see Types for those. The gem ships RBS signatures for type checkers such as Steep. These pages cover the whole SDK with examples. The source and runnable programs, in examples/, are at github.com/synthient/synthient-ruby.

Getting started

1. Install

bundle add synthient

Requires Ruby 3.3 or later. The gem has no runtime dependencies. Load it with require "synthient". The gRPC schema fetcher is loaded separately with require "synthient/grpcschema" and needs the grpc and google-protobuf gems.

2. Make your first lookup

This program creates a client with the API key in SYNTHIENT_API_KEY, looks up one address, and closes the client. Each lookup costs one credit.

require "synthient"

client = Synthient::Client.new
info = client.lookup_ip("8.8.8.8")
client.close

network = info.network
puts "#{network.isp} #{network.type}" if network
intelligence = info.intelligence
puts "#{intelligence.risk_score} #{intelligence.categories.join(", ")}" if intelligence

Client.new reads the API key from the SYNTHIENT_API_KEY environment variable unless you pass api_key:. IPInfo#network, IPInfo#location, and IPInfo#intelligence are nil when the API has no data for that section, so check them before reading their fields.

Create one client, reuse it for every request, and call close on shutdown. The next steps need a client that is still open, because requests after close raise IOError.

3. Check your credits

account returns the account that owns the API key, including its scopes and remaining lookup credits. It costs no credits.

account = client.account
puts "#{account.email} #{account.organization.name} #{account.scopes.join(", ")}"
quota = account.lookup_quota
puts "#{quota.credits} credits, resetting in #{quota.resets_in} seconds"

4. Handle errors

Every error the SDK raises for a failed request is a Synthient::Error. Invalid arguments raise ArgumentError or TypeError instead, before any request is sent.

begin
  client.lookup_ip("8.8.8.8")
rescue Synthient::APIError => e
  case e.status
  when 402
    puts "out of lookup credits"
  when 429
    puts e.retry_after ? "rate limited, retry after #{e.retry_after}s" : "monthly request budget spent"
  else
    puts "request #{e.request_id} failed: #{e.detail || e.title}"
  end
end

5. Keep going

  • Client: create and configure the client, and read the metadata of every API response.
  • Lookups: look up IP addresses and domains, and check your account and the API's health.
  • Feeds: stream each feed's real-time events and download its hourly and daily Parquet exports.
  • Errors and retries: how failed requests are reported, and which requests are retried.
  • Types: the fields of every response and event type, and the enumerations they use.
  • gRPC schema: fetch the protobuf schema of the Synthient gRPC API.
Previous
Next