Ruby SDK
The official Ruby client for the Synthient API: IP lookups, account details, real-time feed streams, and Parquet exports.
Getting started
1. Install
bundle add synthient
Or with RubyGems:
gem install synthient
The gRPC schema fetcher is part of the gem but needs the grpc and google-protobuf gems:
bundle add grpc google-protobuf
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".
The gem ships RBS signatures, so Steep can check your calls with library "synthient" in your Steepfile.
This SDK follows Semantic Versioning. Breaking changes ship only in a new major version, so a constraint such as gem "synthient", "~> 1.0" never picks them up.
2. Make your first lookup
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 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.