v4

gRPC

View as markdown

The Synthient gRPC API is a strongly-typed mirror of the HTTP API. Single IP and domain lookups, account info, parquet exports, and every live event stream are exposed as RPCs 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, or buf generate on an exported descriptor set) 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 grpcurl -protoset-out synthient.binpb grpc.synthient.com:443 describe synthient.v1.SynthientService to materialize a FileDescriptorSet for client codegen. Reflection requires the same x-api-key metadata as every other call.

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: $SYNTHIENT_API_KEY" \
  grpc.synthient.com:443 list

Generating clients from reflection

Every supported language can codegen against the live reflection feed, so there's 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.
grpcurl -protoset-out synthient.binpb \
  -H "x-api-key: $SYNTHIENT_API_KEY" \
  grpc.synthient.com:443 describe synthient.v1.SynthientService

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

RPC reference

Every HTTP endpoint except the batch lookup (POST /api/v4/lookup/ips) has a gRPC counterpart on synthient.v1.SynthientService; call LookupIP per address or use HTTP for batches. 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.

HTTPgRPC method
GET /api/v4/account/meGetAccountInfo
GET /api/v4/lookup/ip/{ip}LookupIP
GET /api/v4/lookup/domain/{domain}LookupDomain
GET /api/v4/feeds/{stream}/exportListExportFeeds
GET /api/v4/feeds/{stream}/export/{date}GetExportFeedURL (returns download_url, expires_at)
GET /api/v4/feeds/{stream}/export/{date}/metaGetExportFeedMeta
GET /api/v4/feeds/proxies/streamStreamProxies (server-streaming)
GET /api/v4/feeds/anonymizers/streamStreamAnonymizers (server-streaming)
GET /api/v4/feeds/torrents/streamStreamTorrents (server-streaming)
GET /api/v4/feeds/ja4t/streamStreamJA4T (server-streaming)
GET /api/v4/feeds/helio/http/streamStreamHoneypotHTTP (server-streaming)
GET /api/v4/feeds/helio/https/streamStreamHoneypotHTTPS (server-streaming)
GET /api/v4/feeds/helio/dns/streamStreamHoneypotDNS (server-streaming)
GET /api/v4/feeds/helio/adb/streamStreamHoneypotADB (server-streaming)

Timestamps

Integer timestamps on the HTTP surface are Unix seconds (UTC), except the anonymizer and Helios HTTP, HTTPS, and DNS stream timestamp, which is Unix milliseconds, and api_key.created_at, which is an RFC 3339 string. 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.

HTTPgRPC status
400 Bad RequestINVALID_ARGUMENT
401 UnauthorizedUNAUTHENTICATED
403 ForbiddenPERMISSION_DENIED
404 Not FoundNOT_FOUND
429 Too Many RequestsRESOURCE_EXHAUSTED (see retry-after metadata)
500 Internal Server ErrorINTERNAL
503 Service UnavailableUNAVAILABLE

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.
Previous
Next