Guide

gRPC

Call unary and streaming gRPC methods using server reflection, imported .proto files or inline definitions.

Postguy calls gRPC methods with a dynamic codec. There is no code generation: you send JSON and get JSON back. Descriptors come from one of three places:

The server's reflection service.
.proto files in the workspace.
Inline file lists.

The parity file marks parts of area D as partial, and d.grpcurl-snippet and d.generate-collection as planned. The list under Not yet says what is missing. The collection runner skips gRPC requests.

Create a gRPC request

Select a collection or folder in the sidebar.
Open the plus menu and choose New gRPC request.

The protocol (HTTP, gRPC or WebSocket) is fixed when a request is created.

Or import .proto files to get a collection with one request per method.

The request tab

The top of the tab holds the request name, the TLS checkbox, Save, and a bar with the method picker, the URL and Invoke.

Control	Notes
Method picker	Lists the methods of the loaded definition, grouped by service, with their call shape (`unary`, `server stream`, `client stream`, `bidi stream`). Without a loaded definition it says `Set the service definition first.` and offers `Open Service definition`. Picking a method on an empty message fills in an example message.
URL field	Placeholder `localhost:50051`. Without a `://` scheme, Postguy adds `http://`, or `https://` when TLS is on. Variables are resolved.
`TLS` checkbox	Explicit toggle. Typing a `grpcs://` URL never sets it silently. With TLS off, the connection is plain HTTP/2 (h2c).
`Invoke`	Calls the method with the current, possibly unsaved, request. The call shape comes from the method. While the call runs the button becomes `Cancel`. `Cmd/Ctrl+Enter` also invokes.
`Save`	Saves the request. `Cmd/Ctrl+S` also saves. Unsaved edits survive a restart and closing the tab asks to save.

Below the bar are six tabs.

Tab	Contents
Service definition	`Use server reflection`, or a `.proto` file, and the loaded request and response messages.
Message	The JSON message editor.
Authorization	Inherit, No Auth, API Key, Basic, Bearer and OAuth 2.0.
Metadata	Key/value table with bulk edit.
Scripts	Pre-invoke, On message and Post-response scripts.
Test	Assertions and a test script, the same as the HTTP Test tab.

Service definitions

On the Service definition tab:

Use server reflection (default). Load services asks the server at the URL for its services and their message types. Nothing is sent until you click it. If the server has no reflection service, or cannot be reached, the tab shows Server reflection failed: … with the reason. Reload services asks again.
Proto file. Untick reflection and click Choose .proto file…. The files you pick, and the files they import from the same folder tree, are copied into <workspace>/protos/<name>/ and the request points at that proto set. Reload recompiles it.

Once loaded and a method is picked, the tab shows Service / Method, the call shape, then request <Type> and response <Type>, each with a Field/Type table. Hover a type to see its full name.

Source	Behaviour
Reflection	Lists the services with `ListServices`, then fetches each service's file set. Tries `grpc.reflection.v1` and falls back to `v1alpha` if the server answers `UNIMPLEMENTED`. Uses the same TLS settings as the call. At most 256 services.
Proto set	A named folder `<workspace>/protos/<name>/`. The set is compiled from every `.proto` file in it (up to 256 files, nesting 8). Imports can be relative to the protos root or to the set's own folder.
Inline	A list of files under `<workspace>/protos/` plus extra import folders, also under that root. Set through the `request_update` tool.

Paths are confined to <workspace>/protos/. Absolute paths, .. and symlinks that leave the root are refused.

Message

The editor holds one JSON object. For client-streaming and bidirectional methods, write a JSON array; each element is sent as one message.
With a loaded definition, keys the input message does not define are shown in red. Hover one to see Unknown field and the message it was checked against. A count of unknown fields appears next to the Message label above the editor. Map keys and the contents of google.protobuf.* types are never flagged.
Generate example writes a default message for the method's input type. A cycle guard stops recursive message types.
Beautify reformats valid JSON.
A message that is not valid JSON stops before any call is made.

Variables, auth and metadata

Variables (environment, collection, secrets) are resolved in the URL, method path, message, metadata and definition fields.
A name that cannot be resolved fails the call instead of being sent literally: the gRPC request message has unresolved variable(s): ….
Auth, whether set on the request or inherited, is sent as metadata. API Key auth is always sent as metadata; the query location does not exist for gRPC.
Metadata keys are lowercased. A key ending in -bin is decoded from base64 and sent as binary metadata.

Scripts and tests

Request-level scripts run around the call. Collection and folder scripts do not run for gRPC.

Script	When
Pre-invoke	Before variables are resolved. It can set variables and change the URL, the metadata (`pm.request.headers`) and the message (`pm.request.body`).
On message	After the call, once per received message, for at most 1,000 messages. `pm.response.json()` is that message.
Post-response	After the call, followed by the Test tab.

In On message and Post-response scripts:

pm.response.code is the numeric gRPC status (0 is OK) and pm.response.status its name.
The body is the reply message as JSON, a JSON array of all replies for server-streaming methods, or the status message when the call failed.

A non-OK status is a result: the response pane shows it and the scripts and tests still run. Results appear in the response pane's Tests tab. When scripts are disabled in Settings, scripts and tests are skipped with a warning.

Calls

Unary. One JSON message in, one out.
Server streaming. One request message. Every reply is collected.
Client streaming. The input messages are sent in order. The single reply is returned.
Bidirectional. A finite list of input messages is sent, then all replies are collected.

The response pane shows the status (0 OK or the error code and name), the time, the message count for streams, the replies, the response metadata and the test results.

Limits:

At most 10,000 input messages are sent. Extras are ignored.
A reply stream that goes past 10,000 messages ends with gRPC status 8: response exceeded 10000 messages (RESOURCE_EXHAUSTED).
Interactive streaming, where you send and end the stream by hand, does not exist yet.

gRPC calls are not recorded in History.

TLS and certificates

For gRPC, the TLS toggle is the request's TLS checkbox.

Postguy uses the system trust store, the custom CA bundle and the PEM client certificate from Settings › Certificates. PEM files are limited to 1 MiB.

There is no insecure (verification off) mode for gRPC.

Per-request settings

A gRPC request stores verifySsl, serverName, includeDefaultFields, maxResponseMb and deadlineMs. The engine does not read them, so they have no effect today.

Not yet

From area D of parity/postman-features.toml:

Proto-aware completion and saved messages in the editor.
Interactive Send / End streaming and a live message timeline.
Trailers and grpc-status-details-bin decoding.
The server-name (SNI) override.
A grpcurl snippet (Code snippets).
Collection and folder scripts, and runner support.

Headless

Tool	Purpose
`grpc_describe`	Services, methods with streaming flags, and every reachable message's fields and types (read-only). With reflection it lists every service.
`grpc_check_message`	Keys in a message that the method's input type does not define (read-only)
`grpc_example_message`	Example input message (read-only)
`grpc_send`	Full pipeline: scripts, auth, the call (shape from the method) and tests
`grpc_invoke`	Unary call; optional `message` overrides the stored one
`grpc_stream`	Streaming call with a `messages` array; replies in arrival order
`grpc_set_proto`	Copy `.proto` files into a proto set and point the request at it
`proto_import`	Import `.proto` files into a proto set and collection

All take the collection and request ids. See Automation tools.

Edit this pageorReport an issue

Code snippets

Generate cURL, raw HTTP, fetch, Python, Go, Rust, PowerShell and Node axios code from an HTTP request.

WebSocket

Connect to ws:// and wss:// endpoints, send text messages and read the event log. The full composer is available through tools.