# 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](https://grpc.io/docs/guides/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

- `Endpoint` `host:port` — `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.
- `Service` `fqn` — `synthient.v1.SynthientService`
- `Auth metadata` `header` — `x-api-key: <YOUR_API_KEY>` on every call. Same key as the HTTP `x-api-key` header.
- `Reflection` `enabled` — 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**

```bash title="List services"
grpcurl -H "x-api-key: $SYNTHIENT_API_KEY" \
  grpc.synthient.com:443 list
```

```bash title="Describe the service"
grpcurl -H "x-api-key: $SYNTHIENT_API_KEY" \
  grpc.synthient.com:443 \
  describe synthient.v1.SynthientService
```

```bash title="CLI"
synthient grpc schema synthient.v1.SynthientService
```

```bash title="Get account info"
grpcurl -H "x-api-key: $SYNTHIENT_API_KEY" \
  grpc.synthient.com:443 \
  synthient.v1.SynthientService/GetAccountInfo
```

```bash title="Look up an IP"
grpcurl -H "x-api-key: $SYNTHIENT_API_KEY" \
  -d '{"ip": "1.1.1.1"}' \
  grpc.synthient.com:443 \
  synthient.v1.SynthientService/LookupIP
```

```bash title="Stream proxies"
grpcurl -H "x-api-key: $SYNTHIENT_API_KEY" \
  grpc.synthient.com:443 \
  synthient.v1.SynthientService/StreamProxies
```

## 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**

```bash title="buf (any language)"
# 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
```

```bash title="CLI"
synthient grpc schema synthient.v1.SynthientService --format binpb --output synthient.protoset
```

```bash title="protoc (re-export to .proto)"
# Re-export the schema as .proto for tooling that doesn't speak
# descriptor sets, then run protoc as you normally would.
grpcurl -protoset-out synthient.binpb \
  -H "x-api-key: $SYNTHIENT_API_KEY" \
  grpc.synthient.com:443 list

protoc --descriptor_set_in=synthient.binpb \
  --go_out=. --go-grpc_out=. \
  synthient/v1/service.proto
```

```bash title="connect-go"
# Connect uses buf under the hood, same pattern.
buf curl --schema-from-reflection \
  --header "x-api-key: $SYNTHIENT_API_KEY" \
  https://grpc.synthient.com:443/synthient.v1.SynthientService/GetAccountInfo \
  -d '{}'
```

## 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`](https://grpc.io/docs/guides/status-codes/) codes that map cleanly onto the HTTP error responses documented on the [Errors](https://docs.synthient.com/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](https://docs.synthient.com/rate-limits) for the per-endpoint quota model.

## Next steps

- [Authentication](https://docs.synthient.com/authentication): API key handling, scopes, and security best practices.
- [Errors](https://docs.synthient.com/errors): full HTTP error reference; the gRPC status mapping above lines up with each entry.
- [Rate Limits](https://docs.synthient.com/rate-limits): quota accounting and the retry-after backoff contract.