# Ruby SDK

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

> **Note**: The generated reference for the client, feeds, and errors is on [RubyDoc.info](https://rubydoc.info/gems/synthient). It lists the response and event models only as constants, without their fields, so see [Types](https://docs.synthient.com/sdks/ruby/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](https://github.com/synthient/synthient-ruby).

## Getting started

### 1. Install

```bash
bundle add synthient
```

Requires Ruby 3.3 or later. The gem has no runtime dependencies. Load it with `require "synthient"`. The [gRPC schema](https://docs.synthient.com/sdks/ruby/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.

```ruby
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.

```ruby
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.

```ruby
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](https://docs.synthient.com/sdks/ruby/client): create and configure the client, and read the metadata of every API response.
- [Lookups](https://docs.synthient.com/sdks/ruby/lookups): look up IP addresses and domains, and check your account and the API's health.
- [Feeds](https://docs.synthient.com/sdks/ruby/feeds): stream each feed's real-time events and download its hourly and daily Parquet exports.
- [Errors and retries](https://docs.synthient.com/sdks/ruby/errors): how failed requests are reported, and which requests are retried.
- [Types](https://docs.synthient.com/sdks/ruby/types): the fields of every response and event type, and the enumerations they use.
- [gRPC schema](https://docs.synthient.com/sdks/ruby/grpc-schema): fetch the protobuf schema of the Synthient gRPC API.