gRPC

The Synthient gRPC API is a strongly-typed mirror of the HTTP API. Every lookup, parquet export, and live event stream is exposed as an RPC on synthient.v1.SynthientService, served over TLS at grpc.synthient.com:443.

Authenticate with the same key you use for HTTP pass it as the x-api-key metadata entry on every RPC. The schema itself is served via gRPC server reflection, so any reflection-aware client (grpcurl, grpcui, buf curl, generated stubs via buf build) discovers methods, message types, and field numbers at runtime there is no .proto bundle to download or vendor into your repo.

Connection

Name
Endpoint
Type
host:port
Description
grpc.synthient.com:443 TLS required. The certificate is issued by a public CA; no custom roots are needed. Do not use api.synthient.com or port 50051 the internal gRPC port is not exposed publicly.
Name
Service
Type
fqn
Description
synthient.v1.SynthientService
Name
Auth metadata
Type
header
Description
x-api-key: <YOUR_API_KEY> on every call. Same key as the HTTP x-api-key header.
Name
Reflection
Type
enabled
Description
Reflection is the canonical schema source. Use grpcurl … list / … describe to inspect, or buf build --schema-from-reflection grpc.synthient.com:443 to materialize a FileDescriptorSet for client codegen.

Versioning

The HTTP base path /api/v4 is the HTTP surface revision. The gRPC service is synthient.v1.SynthientService. The two version numbers are decoupled by design they were not bumped in lockstep historically and are not now. A breaking change to the gRPC contract bumps the proto package (synthient.v2, synthient.v3, …); a breaking change to the HTTP surface bumps the path revision (/api/v5, /api/v6, …).

Quickstart

Discover the service with reflection, then issue your first authenticated call. The GetAccountInfo RPC works for any key, so it's the cheapest probe to confirm your auth is wired up correctly.

Probe with grpcurl

grpcurl -H "x-api-key: $API_KEY" \
  grpc.synthient.com:443 list

Generating clients from reflection

Every supported language can codegen against the live reflection feed no need for a vendored .proto bundle.

Codegen via reflection

# Materialize a descriptor set from the live reflection feed,
# then drive any buf-supported codegen plugin against it.
buf build --schema-from-reflection grpc.synthient.com:443 \
  -o synthient.binpb

buf generate synthient.binpb \
  --template buf.gen.yaml

RPC reference

Every HTTP endpoint has a gRPC counterpart on synthient.v1.SynthientService. The full, authoritative method list is the reflection feed grpcurl … describe synthient.v1.SynthientService will print it. The summary below shows the common methods grouped by surface.

HTTP	gRPC method
`GET /api/v4/account/me`	`GetAccountInfo`
`GET /api/v4/lookup/ip/{ip}`	`LookupIP`
`POST /api/v4/lookup/ips`	`LookupIPs`
`GET /api/v4/lookup/domain/{domain}`	`LookupDomain`
`GET /api/v4/feeds/{stream}/export`	`ListExportSnapshots`
`GET /api/v4/feeds/{stream}/export/{date}`	`GetExportSnapshotURL`
`GET /api/v4/feeds/{stream}/export/{date}/meta`	`GetExportSnapshotMeta`
`GET /api/v4/feeds/proxies/stream`	`StreamProxies` (server-streaming)
`GET /api/v4/feeds/anonymizers/stream`	`StreamAnonymizers` (server-streaming)
`GET /api/v4/feeds/torrents/stream`	`StreamTorrents` (server-streaming)
`GET /api/v4/feeds/helio/http/stream`	`StreamHoneypotHTTP` (server-streaming)
`GET /api/v4/feeds/helio/https/stream`	`StreamHoneypotHTTPS` (server-streaming)
`GET /api/v4/feeds/helio/dns/stream`	`StreamHoneypotDNS` (server-streaming)
`GET /api/v4/feeds/helio/adb/stream`	`StreamHoneypotADB` (server-streaming)

Timestamps

Every timestamp on the HTTP surface is encoded as Unix seconds (UTC, integer). The same instants on the gRPC surface are encoded as google.protobuf.Timestamp (RFC 3339 strings under protojson, structured {seconds, nanos} under proto3 binary). Both representations refer to the same instant only the encoding differs.

Errors

gRPC rejections use canonical google.rpc.Status codes that map cleanly onto the HTTP error responses documented on the Errors page.

HTTP	gRPC status
400 Bad Request	`INVALID_ARGUMENT`
401 Unauthorized	`UNAUTHENTICATED`
403 Forbidden	`PERMISSION_DENIED`
404 Not Found	`NOT_FOUND`
429 Too Many Requests	`RESOURCE_EXHAUSTED` (see `retry-after` metadata)
500 Internal Server Error	`INTERNAL`
503 Service Unavailable	`UNAVAILABLE`

Rate-limit rejections (RESOURCE_EXHAUSTED) carry a retry-after metadata entry mirroring the HTTP Retry-After header read it from the trailing metadata and back off accordingly. See Rate Limits for the per-endpoint quota model.

Next steps

Authentication API key handling, scopes, and security best practices.
Errors full HTTP error reference; the gRPC status mapping above lines up with each entry.
Rate Limits quota accounting and the retry-after backoff contract.