# Types

The fields of every response and event type, and the enumerations they use.

## Lookup types

Models in `com.synthient.model` are immutable records named after the API's JSON fields, read through accessor methods such as `IpInfo.ip()`. Fields the API always sends are non-null, and a response missing one throws `SynthientException`. Optional fields are `@Nullable` and are `null` when the API omits them. Lists and maps are unmodifiable. Timestamps are decoded to `Instant` and durations to `Duration`. Fields with a documented value set are `String`s so that values the API adds later still decode; see [Enumerations](#enumerations). Canonical constructors exist for tests and may gain parameters in minor releases as the API adds fields.

### IpInfo

The intelligence Synthient holds for an IP address. See the [IP API](https://docs.synthient.com/ipapi) for how each field is derived.

- `ip` `String` — The address that was looked up, as canonicalized by the API.
- `network` `Network` — The network the address belongs to, or `null` when unknown.
- `location` `Location` — The geolocation of the address, or `null` when unknown.
- `intelligence` `Intelligence` — Risk, category, and provider data for the address, or `null` when the API has none.

### Network

- `asn` `long` — The autonomous system number.
- `isp` `String` — The internet service provider.
- `type` `String` — The kind of network, one of `NetworkType`. See [Enumerations](#enumerations).
- `org` `String` — The organization, or `null` when unknown.
- `domain` `String` — The organization's domain, or `null` when unknown.
- `abuseEmail` `String` — The abuse contact email, or `null` when unknown.
- `abusePhone` `String` — The abuse contact phone number, or `null` when unknown.

### Location

- `country` `String` — The country code.
- `state` `String` — The state or region.
- `city` `String` — The city.
- `timezone` `String` — The IANA time zone.
- `latitude` `double` — The latitude in degrees.
- `longitude` `double` — The longitude in degrees.
- `geoHash` `String` — The geohash of the coordinates.

### Intelligence

Synthient's assessment of an address. See [Methodology](https://docs.synthient.com/methodology) for how it is built.

- `riskScore` `int` — The risk score, from 0 to 100.
- `devices` `List<Device>` — The devices seen behind the address.
- `behavior` `List<String>` — The behaviors observed from the address.
- `categories` `List<String>` — The service categories of the address.
- `providers` `List<Provider>` — The proxy and VPN providers seen using the address.

### Provider

A proxy or VPN provider seen using an IP address.

- `name` `String` — The provider name. The API names this field `provider`. See [Service Tags](https://docs.synthient.com/service-tags).
- `type` `String` — The kind of service.
- `lastSeen` `Instant` — When the provider was last seen using the address.

### Device

A device seen behind an IP address.

- `os` `String` — The operating system, one of `OperatingSystem`. See [Enumerations](#enumerations).
- `version` `String` — The operating system version.
- `lastSeen` `Instant` — When the device was last seen.

## Domain types

### DomainInfo

Proxy traffic to a domain over the last 30 days.

- `domain` `String` — The domain that was looked up.
- `status` `String` — Whether the domain had events in the last 24 hours, one of `DomainStatus`.
- `stats` `DomainStats` — Aggregate event counts.
- `timeSeries` `List<TimeSeriesPoint>` — Daily event and distinct source address counts.
- `uniqueIps` `UniqueIps` — Counts of the distinct source addresses.
- `topSubdomains` `List<SubdomainCount>` — The most targeted subdomains.
- `topPorts` `List<PortCount>` — The most targeted ports.
- `geoDistribution` `List<CountryCount>` — Event counts by source country.
- `hourDowHeatmap` `List<List<Long>>` — Event counts as 7 rows of 24 hours, in UTC, indexed as `hourDowHeatmap().get(day).get(hour)`. Row 0 is Monday, so row `d` is `DayOfWeek.of(d + 1)`.
- `activityStats` `ActivityStats` — The hourly activity pattern.
- `recentEvents` `List<DomainEvent>` — The most recent events, up to the requested limit.
- `topAsn` `AsnCount` — The source network with the most events, or `null` when there were none.

### DomainStats

- `totalEvents30d` `long` — Events in the last 30 days.
- `events24h` `long` — Events in the last 24 hours.

### UniqueIps

The distinct source addresses seen for a domain.

- `value24h` `long` — Distinct source addresses in the last 24 hours.
- `value30d` `long` — Distinct source addresses in the last 30 days.
- `sparkline24h` `List<Long>` — Distinct source addresses per hour over the last 24 hours.

### TimeSeriesPoint

The event counts for one day.

- `date` `Instant` — The start of the day in UTC.
- `events` `long` — Events that day.
- `uniqueIps` `long` — Distinct source addresses that day.

### AsnCount

- `asn` `long` — The autonomous system number.
- `events` `long` — Events from that network.

### SubdomainCount

- `subdomain` `String` — The subdomain.
- `count` `long` — The number of events that targeted it.

### PortCount

- `port` `int` — The port.
- `count` `long` — The number of events that targeted it.

### CountryCount

- `countryCode` `String` — The country code.
- `uniqueIps` `long` — Distinct source addresses from that country.
- `events` `long` — Events from that country.

### ActivityStats

The hourly activity pattern of a domain, in UTC.

- `peakHour` `int` — The busiest hour of the day, from 0 to 23.
- `quietHour` `int` — The quietest hour of the day, from 0 to 23.
- `medianPerHour` `long` — The median number of events per hour.
- `p95PerHour` `long` — The 95th percentile of events per hour.
- `cadence` `String` — A sentence describing the activity pattern, one of `Cadence`. See [Enumerations](#enumerations).

### DomainEvent

A proxy request to a domain.

- `timestamp` `Instant` — When the request was seen.
- `sourceIp` `String` — The full proxy exit address that carried the request. The API names the field `source_ip_masked`, but the address is not masked.
- `targetSubdomain` `String` — The subdomain that was requested.
- `port` `int` — The port that was requested.
- `countryCode` `String` — The country of the source address.

## Account types

### Account

The account that owns the API key.

- `firstName` `String` — The account holder's first name.
- `lastName` `String` — The account holder's last name.
- `email` `String` — The account holder's email address.
- `organization` `Organization` — The organization the key belongs to.
- `scopes` `List<String>` — The scopes the key grants, each one of `Scope`. See [Enumerations](#enumerations).
- `lookupQuota` `LookupQuota` — The organization's lookup credits.
- `apiKey` `AccountApiKey` — The key used for the request, or `null` when the API omits it.

### Organization

- `id` `String` — The organization's ID.
- `name` `String` — The organization's name.
- `relation` `String` — The account's role in the organization, one of `Relation`. See [Enumerations](#enumerations).

### LookupQuota

An organization's lookup credits.

- `credits` `long` — The number of lookup credits remaining.
- `resetsIn` `Duration` — The time until the credits reset.

### AccountApiKey

The API key used for a request. It does not include the secret.

- `id` `String` — The key's ID.
- `name` `String` — The key's name.
- `createdAt` `Instant` — When the key was created.

## Export types

### ExportPage

One page of a feed's exports, newest first.

- `stream` `String` — The feed's stream name.
- `exports` `List<Export>` — The exports on this page. The API names this field `feeds`.
- `nextCursor` `String` — The cursor of the next page, to pass to `listExports`, or `null` on the last page.

### Export

A Parquet export of a feed.

- `id` `String` — The ID to pass to `exportMeta`, `download`, and `downloadUrl`. On the first page, the newest hourly export may have the ID `ExportId.LATEST`.
- `kind` `String` — Whether the export covers an hour or a day, one of `ExportKind`.
- `date` `LocalDate` — The UTC day the export covers.
- `hour` `Integer` — The UTC hour the export covers, or `null` for a daily export.
- `sizeBytes` `long` — The size of the Parquet file in bytes.
- `rowCount` `long` — The number of rows in the file.
- `checksum` `String` — The hex-encoded SHA-256 of the Parquet file.
- `createdAt` `Instant` — When the export was written.
- `downloadPath` `String` — The API path that redirects to the file.

### ExportMeta

The metadata of a Parquet export.

- `id` `String` — The export ID.
- `stream` `String` — The feed's stream name.
- `kind` `String` — Whether the export covers an hour or a day, one of `ExportKind`.
- `format` `String` — The file format, `"parquet"`.
- `date` `Instant` — The start of the hour or day the export covers.
- `hour` `Integer` — The UTC hour the export covers, or `null` for a daily export.
- `rows` `long` — The number of rows in the file.
- `size` `long` — The size of the Parquet file in bytes.
- `checksum` `String` — The hex-encoded SHA-256 of the Parquet file.
- `createdAt` `Instant` — When the export was written.
- `schema` `ParquetSchema` — The Parquet columns.

### ParquetSchema

- `fields` `List<ParquetColumn>` — The columns in file order.

### ParquetColumn

- `name` `String` — The column name.
- `type` `String` — The column type, one of `ParquetType`. See [Enumerations](#enumerations).

## Event types

Stream events carry the fields described in the [Firehose](https://docs.synthient.com/enterprise/firehose) and [Helios](https://docs.synthient.com/enterprise/helios) documentation, renamed to camelCase. Timestamps are decoded to `Instant` with a fixed unit per event type: Unix seconds for proxy, torrent, and JA4T events, and Unix milliseconds for anonymizer and Helios HTTP, HTTPS, and DNS events. The unit is never guessed from the size of the value. An event that is missing a required field throws `SynthientException` and ends the stream.

### ProxyEvent

A proxy sighting from `proxies()`. Every field may be absent and is then `null`.

- `ip` `String` — The proxy's address.
- `provider` `String` — The proxy provider.
- `type` `String` — The kind of service, one of `ProxyType`. See [Enumerations](#enumerations).
- `timestamp` `Instant` — When the proxy was seen.
- `countryCode` `String` — The ISO 3166-1 alpha-2 country of the address.
- `asn` `Long` — The autonomous system number of the address.

### AnonymizerEvent

An address range used by a VPN or other anonymizing service, from `anonymizers()`. Every field may be absent and is then `null`.

- `rangeStart` `String` — The first address of the range.
- `rangeEnd` `String` — The last address of the range.
- `provider` `String` — The service provider.
- `type` `String` — The kind of service, one of `ProxyType`. See [Enumerations](#enumerations).
- `timestamp` `Instant` — When the range was seen.
- `countryCode` `String` — The ISO 3166-1 alpha-2 country of `rangeStart`.
- `asn` `Long` — The autonomous system number of `rangeStart`.

### TorrentEvent

A torrent from `torrents()`. Every field may be absent and is then `null`.

- `infoHash` `String` — The hex-encoded SHA-1 info hash.
- `name` `String` — The torrent's name.
- `magnetUri` `String` — The torrent's magnet link.
- `totalSize` `Long` — The total size of the torrent's files in bytes.
- `pieceLength` `Long` — The piece length in bytes.
- `fileCount` `Integer` — The number of files in the torrent.
- `timestamp` `Instant` — When the torrent was seen.
- `files` `List<TorrentFile>` — The files in the torrent.
- `peers` `List<TorrentPeer>` — The peers seen sharing the torrent.

### TorrentFile

A file in a torrent. Every field may be absent and is then `null`.

- `path` `String` — The file's path in the torrent.
- `length` `Long` — The file size in bytes.

### TorrentPeer

A peer seen sharing a torrent. Every field may be absent and is then `null`.

- `ip` `String` — The peer's address.
- `port` `Integer` — The peer's port.
- `encrypted` `Boolean` — Whether the peer used an encrypted connection.
- `source` `String` — Where the peer was found: DHT, PEX, or a tracker.

### Ja4tEvent

A TCP fingerprint seen from a proxy, from `ja4t()`. Every field may be absent and is then `null`.

- `ip` `String` — The proxy's address.
- `ja4t` `String` — The JA4T fingerprint.
- `provider` `String` — The proxy provider.
- `type` `String` — The kind of service, one of `ProxyType`. See [Enumerations](#enumerations).
- `timestamp` `Instant` — When the fingerprint was seen.
- `countryCode` `String` — The ISO 3166-1 alpha-2 country of the address.
- `asn` `Long` — The autonomous system number of the address.

### HeliosMeta

The proxy a Helios honeypot request came through. Every field may be absent and is then `null`.

- `proxyIp` `String` — The proxy's exit address.
- `server` `String` — The honeypot server that received the request.
- `poolId` `String` — The proxy pool.
- `provider` `String` — The proxy provider.

### HeliosHttpEvent

An HTTP request received by a Helios honeypot through a proxy.

- `timestamp` `Instant` — When the request was received.
- `tunnelId` `BigInteger` — The proxy tunnel. It is an unsigned 64-bit value that can exceed `Long.MAX_VALUE`.
- `domain` `String` — The tunnel's destination domain.
- `port` `int` — The tunnel's destination port.
- `protocol` `String` — Always `"http"`.
- `meta` `HeliosMeta` — The proxy the request came through.
- `details` `HttpRequestDetails` — The parsed request, or `null` when absent.
- `raw` `String` — The raw request bytes as base64, or `null` when absent. The SDK does not decode it.

```java
try (EventStream<HeliosHttpEvent> events = client.heliosHttp().stream()) {
    for (HeliosHttpEvent event : events) {
        String raw = event.raw();
        if (raw != null) {
            byte[] request = Base64.getDecoder().decode(raw);
            System.out.println(event.tunnelId() + " " + request.length);
        }
    }
}
```

### HttpRequestDetails

A parsed HTTP request. Every field may be absent and is then `null`.

- `method` `String` — The request method.
- `uri` `String` — The request target.
- `version` `String` — The HTTP version.
- `headers` `Map<String, String>` — The request headers.

### HeliosHttpsEvent

A TLS handshake received by a Helios honeypot through a proxy.

- `timestamp` `Instant` — When the handshake was received.
- `tunnelId` `BigInteger` — The proxy tunnel. It is an unsigned 64-bit value that can exceed `Long.MAX_VALUE`.
- `domain` `String` — The tunnel's destination domain.
- `port` `int` — The tunnel's destination port.
- `protocol` `String` — Always `"https"`.
- `meta` `HeliosMeta` — The proxy the handshake came through.
- `details` `TlsClientHello` — The parsed ClientHello, or `null` when the sensor could not parse it.
- `raw` `String` — Always `null`, because the HTTPS sensors do not capture handshake bytes.

### TlsClientHello

A parsed TLS ClientHello. Every field may be absent and is then `null`: fields the sensor could not parse are absent, and new fields may appear.

- `recordVersion` `String` — The record layer version.
- `handshakeVersion` `String` — The handshake version.
- `clientRandom` `String` — The hex-encoded 32-byte client random.
- `sessionId` `String` — The hex-encoded session ID.
- `sessionIdLength` `Integer` — The session ID length in bytes.
- `sni` `String` — The server name indication.
- `cipherSuites` `List<TlsCodeName>` — The offered cipher suites.
- `compressionMethods` `List<Integer>` — The offered compression methods.
- `extensions` `List<TlsExtension>` — The extensions in wire order.
- `supportedGroups` `List<TlsCodeName>` — The supported groups.
- `signatureAlgorithms` `List<TlsCodeName>` — The signature algorithms.
- `alpn` `List<String>` — The application protocols.
- `supportedVersions` `List<String>` — The supported TLS versions.
- `ecPointFormats` `List<String>` — The elliptic curve point formats.
- `keyShareGroups` `List<String>` — The key share groups.
- `pskKeyExchangeModes` `List<String>` — The pre-shared key exchange modes.
- `compressCertificate` `List<String>` — The certificate compression algorithms.
- `hasGrease` `Boolean` — Whether GREASE values were present.
- `applicationSettings` `Boolean` — Whether the application settings extension was present.
- `delegatedCredentials` `Boolean` — Whether the delegated credentials extension was present.
- `encryptThenMac` `Boolean` — Whether the encrypt-then-MAC extension was present.
- `extendedMasterSecret` `Boolean` — Whether the extended master secret extension was present.
- `postHandshakeAuth` `Boolean` — Whether the post-handshake authentication extension was present.
- `renegotiationInfo` `Boolean` — Whether the renegotiation info extension was present.
- `signedCertificateTimestamps` `Boolean` — Whether the signed certificate timestamps extension was present.
- `statusRequest` `Boolean` — Whether the status request extension was present.

### TlsCodeName

A TLS code point and its name. GREASE values are named like `GREASE(0x0a0a)`. Every field may be absent and is then `null`.

- `code` `Integer` — The code point.
- `name` `String` — The code point's name.

### TlsExtension

A TLS extension in a ClientHello. Every field may be absent and is then `null`.

- `code` `Integer` — The extension type.
- `name` `String` — The extension name.
- `length` `Integer` — The extension data length in bytes.

### HeliosDnsEvent

A DNS tunnel opened to a Helios honeypot through a proxy. Its `domain` is the tunnel's destination, not a DNS query name.

- `timestamp` `Instant` — When the tunnel was opened.
- `tunnelId` `BigInteger` — The proxy tunnel. It is an unsigned 64-bit value that can exceed `Long.MAX_VALUE`.
- `domain` `String` — The tunnel's destination domain, not a DNS query name.
- `port` `int` — The tunnel's destination port.
- `protocol` `String` — Always `"dns"`.
- `meta` `HeliosMeta` — The proxy the tunnel came through.

### HeliosAdbEvent

A command run on a Helios Android Debug Bridge honeypot. It has no timestamp because the sensor sends none.

- `session` `String` — The session ID as 32 hex characters.
- `sequentialId` `long` — The command's position in the session, starting at 1.
- `command` `String` — The command text. Invalid UTF-8 bytes are replaced with U+FFFD.
- `hash` `String` — The hex-encoded SHA-256 the sensor assigns to the session's payload. It is not a hash of `command`: every command in a session shares it, and sessions that replay the same script share it too.

## Enumerations

Fields with a documented value set are `String`s, so values the API adds later still decode. A final class in `com.synthient.model` holds a `String` constant for each known value. The SDK documents every set as open, so handle unknown values instead of assuming the constants are exhaustive. Compare with `equals`:

```java
Network network = client.lookupIp("8.8.8.8").network();
if (network != null && NetworkType.RESIDENTIAL.equals(network.type())) {
    System.out.println("residential network: " + network.isp());
}
```

### NetworkType

The known values of `Network.type()`.

| Constant         | Value            |
| ---------------- | ---------------- |
| `MOBILE`         | `MOBILE`         |
| `SATELLITE`      | `SATELLITE`      |
| `IN_FLIGHT_WIFI` | `IN_FLIGHT_WIFI` |
| `RESIDENTIAL`    | `RESIDENTIAL`    |
| `CORPORATE`      | `CORPORATE`      |
| `ACADEMIC`       | `ACADEMIC`       |
| `DATACENTER`     | `DATACENTER`     |
| `GOVERNMENT`     | `GOVERNMENT`     |

### ProxyType

The known values of the `type` of `ProxyEvent`, `AnonymizerEvent`, and `Ja4tEvent`.

| Constant            | Value               |
| ------------------- | ------------------- |
| `FREE_VPN`          | `FREE_VPN`          |
| `COMMERCIAL_VPN`    | `COMMERCIAL_VPN`    |
| `ENTERPRISE_VPN`    | `ENTERPRISE_VPN`    |
| `MOBILE_PROXY`      | `MOBILE_PROXY`      |
| `BLOCKCHAIN_PROXY`  | `BLOCKCHAIN_PROXY`  |
| `RESIDENTIAL_PROXY` | `RESIDENTIAL_PROXY` |
| `PUBLIC_PROXY`      | `PUBLIC_PROXY`      |
| `DATACENTER_PROXY`  | `DATACENTER_PROXY`  |
| `TOR_NODE`          | `TOR_NODE`          |
| `PRIVATE_RELAY`     | `PRIVATE_RELAY`     |
| `BOTNET`            | `BOTNET`            |
| `SEARCH_ENGINE`     | `SEARCH_ENGINE`     |
| `AI_CRAWLER`        | `AI_CRAWLER`        |
| `SOCIAL_MEDIA`      | `SOCIAL_MEDIA`      |
| `UPTIME_MONITOR`    | `UPTIME_MONITOR`    |
| `LINK_PREVIEW`      | `LINK_PREVIEW`      |
| `SEO_CRAWLER`       | `SEO_CRAWLER`       |
| `WEB_ARCHIVER`      | `WEB_ARCHIVER`      |
| `WEBHOOK_PROVIDER`  | `WEBHOOK_PROVIDER`  |
| `PAYMENT_PROCESSOR` | `PAYMENT_PROCESSOR` |
| `INTERNET_SCANNER`  | `INTERNET_SCANNER`  |

### OperatingSystem

The known values of `Device.os()`.

| Constant    | Value       |
| ----------- | ----------- |
| `ANDROID`   | `Android`   |
| `CHROME_OS` | `Chrome OS` |
| `FREEBSD`   | `FreeBSD`   |
| `IOS`       | `iOS`       |
| `LINUX`     | `Linux`     |
| `MAC_OS_X`  | `Mac OS X`  |
| `WINDOWS`   | `Windows`   |

### Scope

The known values of `Account.scopes()`. `BASIC` authorizes lookups and `account()`. Each feed has one scope for its exports and one for its stream, as listed under [Feeds](https://docs.synthient.com/sdks/java/feeds). See [Authentication](https://docs.synthient.com/authentication) for how scopes are granted.

| Constant                | Value                   |
| ----------------------- | ----------------------- |
| `BASIC`                 | `BASIC`                 |
| `PROXY_FEEDS`           | `PROXY_FEEDS`           |
| `PROXY_FIREHOSE`        | `PROXY_FIREHOSE`        |
| `ANONYMIZERS_FEED`      | `ANONYMIZERS_FEED`      |
| `ANONYMIZERS_STREAM`    | `ANONYMIZERS_STREAM`    |
| `JA3_FEED`              | `JA3_FEED`              |
| `JA3_STREAM`            | `JA3_STREAM`            |
| `TORRENTS_FEED`         | `TORRENTS_FEED`         |
| `TORRENTS_STREAM`       | `TORRENTS_STREAM`       |
| `HONEYPOT_HTTP_FEED`    | `HONEYPOT_HTTP_FEED`    |
| `HONEYPOT_HTTP_STREAM`  | `HONEYPOT_HTTP_STREAM`  |
| `HONEYPOT_HTTPS_FEED`   | `HONEYPOT_HTTPS_FEED`   |
| `HONEYPOT_HTTPS_STREAM` | `HONEYPOT_HTTPS_STREAM` |
| `HONEYPOT_ADB_FEED`     | `HONEYPOT_ADB_FEED`     |
| `HONEYPOT_ADB_STREAM`   | `HONEYPOT_ADB_STREAM`   |
| `HONEYPOT_DNS_FEED`     | `HONEYPOT_DNS_FEED`     |
| `HONEYPOT_DNS_STREAM`   | `HONEYPOT_DNS_STREAM`   |
| `JA4_FEED`              | `JA4_FEED`              |
| `JA4_STREAM`            | `JA4_STREAM`            |
| `JA4T_FEED`             | `JA4T_FEED`             |
| `JA4T_STREAM`           | `JA4T_STREAM`           |
| `ADMIN_PROXIES`         | `ADMIN_PROXIES`         |

### Relation

The known values of `Organization.relation()`.

| Constant | Value    |
| -------- | -------- |
| `OWNER`  | `OWNER`  |
| `ADMIN`  | `ADMIN`  |
| `MEMBER` | `MEMBER` |

### DomainStatus

The known values of `DomainInfo.status()`.

| Constant   | Value      | Meaning                                                                    |
| ---------- | ---------- | -------------------------------------------------------------------------- |
| `ACTIVE`   | `active`   | The domain had events in the last 24 hours.                                |
| `INACTIVE` | `inactive` | The domain had no events in the last 24 hours, or has never been observed. |

### Cadence

The known values of `ActivityStats.cadence()`.

| Constant                 | Value                                                |
| ------------------------ | ---------------------------------------------------- |
| `NO_ACTIVITY`            | `No activity in the last 30 days.`                   |
| `EVEN`                   | `Activity is evenly distributed across the day.`     |
| `WEEKDAY_BUSINESS_HOURS` | `Activity follows a weekday business-hours pattern.` |
| `WEEKEND`                | `Activity follows a weekend pattern.`                |
| `BURSTY`                 | `Activity is burst-driven with significant peaks.`   |

### ExportKind

The known values of `Export.kind()` and `ExportMeta.kind()`.

| Constant | Value    |
| -------- | -------- |
| `HOURLY` | `hourly` |
| `DAILY`  | `daily`  |

### ParquetType

The known values of `ParquetColumn.type()`.

| Constant | Value    |
| -------- | -------- |
| `STRING` | `string` |
| `INT64`  | `int64`  |
| `UINT32` | `uint32` |
| `UINT64` | `uint64` |
| `BOOL`   | `bool`   |
| `BYTES`  | `bytes`  |