The gRPC client interface

Postman's gRPC client interface provides a variety of specialized tools, views, and controls for invoking and testing gRPC requests. For example, it includes a dropdown list that shows the methods available on the server. This topic highlights the various parts of the gRPC client interface and how to use them.

Creating a new request

Create a new gRPC request by selecting New in the sidebar. Select gRPC from the list to open a blank gRPC request in a new tab.

The request section

The request section includes the required configurations to connect to the server and run the selected method. Requests need a server URL, a service definition, and a selected method to be invoked. Based on the API requirements, you may have to pass message payloads, metadata, and authorization details along with the request. You may also have to configure TLS and other certificates based on the requirements.

Request name - If you want to test multiple requests with different configurations, you can name each of them individually and save them into a collection. Saving into a collection enables you to reuse the requests later and share them with others.
Server URL - Defines the endpoint where the service is hosted. A gRPC URL often starts with grpc:// instead of http:// or https://. While creating a new request, you can also browse through URLs you've used by selecting the URL box. This helps you create the request faster if you're testing multiple methods on the same endpoint.
Method name - Select the method you wish to invoke using this dropdown list. The list of methods is populated by the service definition. For more details about the method types, see About gRPC API requests.
Request actions - Request actions offer options for what you can do with the request:
- Save - Saves the request into a collection so that you can reuse it later or share it with others. gRPC requests can only be saved to multi-protocol collections.
- Delete - Deletes an existing request from the collection.
Share - Collaborate with team members, groups, and external users by sharing your requests with them. Learn more at Share your work in Postman.
Invoke - Once you have entered the server URL, selected the method to invoke, and defined the payload, select Invoke to invoke the request and get a response from the server.
Payload - This is the data being sent to the server in the request. A gRPC payload has the following tabs to aid the server in running the request:
- Message - Compose a message in JSON here to send along with the request. The server uses this message to perform appropriate actions and gives you a response in return.
- Authorization - Pass credentials that the server would use to authorize the connection here. You can choose from a list of auth types including API Key, Basic auth, and Bearer token. Learn more about authorizing requests.
- Metadata - Pass other metadata with the request in the form of key-value pairs. The client uses this metadata to provide more information about the call to the server.
- Service definition - A service definition informs the client of all server-supported services, methods, message payload structures, and fields and data types. A service definition is loaded automatically after you enter the URL if the server supports server reflection. Otherwise, you must load a service definition manually by selecting or importing a .proto file. Learn more about working with service definitions.
- Scripts - Postman has a powerful scripting environment that enables you to add JavaScript code (scripts) to your gRPC requests. Use scripts to perform API tests, debug your requests with the Postman Console, or dynamically read or update the values of variables. You can import packages with scripts and tests from your team's Package Library. You can also import packages from external package registries, such as npm and JSR. Learn more about scripting in gRPC requests.
- Settings - Customize the gRPC request's behavior with various options to meet your security and performance requirements. These options include the following:
  - Enable server certificate verification - Verify the server certificate when invoking a method over a secure connection.
  - Overwrite server name for certificate verification - Configure the value used to validate the common name in the server certificate.
  - Include fields with default values in the response - View response fields with default values. Turning this off will omit such fields from the response.
  - Maximum response message size - The maximum allowed message size in megabytes. To receive messages of any size, set this to 0.
  - Connection Timeout - Configure the deadline to invoke and receive the response in milliseconds. To keep the connection open indefinitely, set this to 0.
Protocol dropdown list - You can change the protocol for a new request. Select New in the sidebar and then select a request protocol, or select Add to open a new tab. Select the protocol dropdown list to the left of the request's name, and then select a different request protocol.

You can't change the request protocol after you select Save.
Enable/disable TLS - Select the lock icon to enable or disable transport layer security (TLS) for the request. Enabling TLS encrypts the data between the client and the server. Some servers require TLS.
Message actions - Select Beautify to make the composed JSON message more readable with advanced formatting. Select Use Example Message to create an example message using the schema once you have selected the method to invoke.

The response section

After invoking a method, the response data sent from the server appears in the response area.

The response section has the following items:

Response - The primary information returned by the server after the successful request run.
- Wrap lines - Selecting this button adjusts the width of the response body according to the width of the response area, making it easier to read longer responses without scrolling.
Metadata - Metadata returned by the server typically consists of information about the run.
Trailers - Trailers are metadata usually sent by the server at the end of a response stream.
Test results - The results for assertions you write in the Scripts section appear here. Based on the post-response script, the results can be one of three types: Passed, Failed, and Skipped. Learn more about scripting in gRPC requests.
Status code and Time - This is key information regarding performance and if the request was successful. You can assess the performance of the API using the time, which shows how long the request took. The status code gives you information about the request's success or errors. The status code 0 OK signifies a successful request. In case of an error, a gRPC-based implementation returns different status codes for different error scenarios which help you understand the cause and choose next steps by hovering over them.
Save Response - You can save responses to your gRPC requests as examples. For streaming methods, you must end streaming before you can save an example. See Save, edit, and share gRPC request-response examples to learn more.
Search - Look for text within the response using the Search icon .
Multiple responses - While invoking a streaming method type (client streaming, server streaming, or bidirectional streaming), the client-server communication within a single session is recorded in the response area as a series of sent and received messages in a timeline instead of a single response.
- Connection status - The connection status shows if the connection with the server is active and if messages are being streamed.
- Message stream - The message stream has the list of sent, received, and informative messages arranged in reverse chronological order (latest appears on the top).
- Expand/collapse message - You can take an in-depth look at the message content by expanding it within the message stream.
- Search for messages - You can use the high-level search input to search for particular messages.
- Message filter - Adjust the view based on the type of messages using the message filter. Instead of all messages, you can choose to view sent messages or received messages.
- Clear messages - Hides all the messages from the view, cleaning up the response area so that you can focus on the new messages. You can restore the messages using the Restore button in the hidden view.
- End Streaming - Appears when invoking a method that sends multiple messages from the client. Selecting this concludes the streaming operation between the client and the server.
- Send - Appears when invoking a method that sends multiple messages from the client. Selecting this sends the request message to the server.

In the right sidebar, you can access your gRPC request's documentation, comments, and request details.

Documentation - Select the documentation icon to view documentation for a request. When you select a method, Postman automatically generates documentation for the payload fields and data types using the protobuf definition. You can also add a description to help users understand and use the request. Select Add description, then write your content using Postman's built-in editing tools, or select Generate with Postbot to write content with Postman's AI assistant.

You can also add a description to your collection's overview or a folder in your collection. Select the collection or folder in the sidebar, then select Add collection description or Add folder description.
Comments - Select the comments icon to collaborate with your teammates as you work on an API. You can use @ to tag others to ask a question, give feedback, and discuss your API.
Info - Select the information icon to view more details about a request, including the request ID, creation date, and the date when it was last updated.