Java SDK

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

Getting started

1. Install

implementation("com.synthient:synthient-java:1.0.0")

Requires Java 21 or later. The client is in the com.synthient package and the response models are in com.synthient.model. The SDK is built on OkHttp, whose OkHttpClient and Headers types appear in its API. Its packages are @NullMarked with JSpecify, so every type is non-null unless it is annotated @Nullable. The jar's automatic module name is com.synthient. The gRPC schema fetcher is a separate artifact, com.synthient:synthient-java-grpcschema.

2. Make your first lookup

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

import com.synthient.SynthientClient;
import com.synthient.model.Intelligence;
import com.synthient.model.IpInfo;
import com.synthient.model.Network;

public final class Quickstart {
    public static void main(String[] args) {
        try (SynthientClient client = new SynthientClient()) {
            IpInfo info = client.lookupIp("8.8.8.8");
            Network network = info.network();
            if (network != null) {
                System.out.println(network.isp() + " " + network.type());
            }
            Intelligence intelligence = info.intelligence();
            if (intelligence != null) {
                System.out.println(intelligence.riskScore() + " " + intelligence.categories());
            }
        }
    }
}

The no-argument constructor reads the API key from the SYNTHIENT_API_KEY environment variable. IpInfo.network(), IpInfo.location(), and IpInfo.intelligence() return null when the API has no data for that section, so check them before reading their fields.

A SynthientClient holds a connection pool, so close it when you are done, for example with try-with-resources.

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 account = client.account();
System.out.println(account.email() + " " + account.organization().name() + " " + account.scopes());
LookupQuota quota = account.lookupQuota();
System.out.println(quota.credits() + " credits, resetting in " + quota.resetsIn());

4. Handle errors

Every exception the SDK throws for a failed call is unchecked and extends SynthientException.

try {
    IpInfo info = client.lookupIp("8.8.8.8");
    System.out.println(info.ip());
} catch (ApiException e) {
    switch (e.statusCode()) {
        case 402 -> System.out.println("out of lookup credits");
        case 429 -> System.out.println(
                e.retryAfter() == null ? "monthly request budget spent" : "rate limited, retry after " + e.retryAfter());
        default -> System.out.println(
                "request " + e.requestId() + " failed: " + (e.detail().isEmpty() ? e.title() : e.detail()));
    }
} catch (ApiConnectionException e) {
    System.out.println("no response: " + e.getMessage());
}

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.