The GraphQL client interface

This guide is a high-level overview of the GraphQL client interface.

Postman has a special client for GraphQL requests called the GraphQL client. When you create a GraphQL request in Postman, the GraphQL client loads automatically. The GraphQL client has features that enable you to create and execute GraphQL requests more efficiently.

The GraphQL client automatically fetches a GraphQL API's schema and uses introspection to show you the available data fields. You can explore a GraphQL API's data fields and construct queries by selecting fields or entering code in an editor. For requests with multiple queries, you can select specific queries and run them individually.

The GraphQL client interface has three main sections:

The request section
The response section
The right sidebar

If you are using the Postman web app, you must use the Postman Desktop Agent. See About the Postman Agent for more information.

The request section

In the GraphQL client's request section, you can enter an endpoint in the URL box as you would in the regular Postman request interface. But the GraphQL client adds GraphQL-specific features, including an interactive schema explorer.

Protocol dropdown list - Change the protocol for a new request. Select the protocol dropdown list then select a request protocol.

You can't change the request protocol after you save the request.
URL box - Enter the GraphQL server's URL here. You can also select this field to browse URLs you've already used.
Tabs - The following tabs are available:
- Query - The Query tab has three subsections: the schema explorer, the query editor, and the variables editor.
- Authorization - You can enter authorization credentials here. You can choose from a list of auth types including API key, basic auth, and bearer token. Learn more about authorizing requests.
- Headers - The Headers tab enables you to pass headers with the request in the form of key-value pairs. The client uses these headers to provide information about the call to the server.
- Schema - The Schema tab enables you to select an API and save it to the request. You can use GraphQL introspection, select an API from a Postman workspace, or import a schema from a local file or a URL. You can also select a specific published release of an API. The GraphQL client populates the schema explorer with fields from the chosen schema.
- Scripts - The Scripts tab accesses Postman's powerful scripting environment that enables you to add JavaScript code (scripts) to your GraphQL requests. You can use scripts to write API tests, debug your requests by logging them to the Postman Console, or dynamically read or update the values of variables.
Schema explorer - When you enter a GraphQL server's endpoint in the URL box, the endpoint's schema appears here. The schema explorer is also an interactive visual query editor where you can browse and select fields and arguments to build queries in the query editor.
Save button - Saves the request to a collection. GraphQL requests can't be saved to collections that contain HTTP requests.
Query button - Executes the selected query. If there are multiple queries, a dropdown list is available where you can select individual queries to execute.
Query editor - Build and edit queries here. You can enter queries manually or build them with the schema explorer. You can create multiple queries in the query editor and run them individually.
Variables editor - Create and edit your request's variables here. The variables editor is collapsed by default. Select the arrow next to Variables to expand it.

The response section

When you execute a query, the response from the server appears here. The GraphQL client's response section is similar to Postman's regular response viewer.

The GraphQL client response section has the following tabs:

Body - Shows the data returned by the server for the fields in the query. You can format the body with Pretty and Table.
Headers - Shows headers returned by the server.
Test Results - Shows results for assertions in the scripts section. Results can be one of three types: Passed, Failed, or Skipped.

Multiple responses

For subscription-type queries that return multiple responses over a persistent connection, the response section shows a list of messages in reverse chronological order, with the most recent message at the top. The messages can contain responses from the server or other information about the request like subscription confirmations or completion messages.

Select a message to expand it and see its contents. You can search for specific messages with the search icon . You can also filter for all messages, responses only, or other types of messages. Select Clear messages to remove all the messages from the response section. You can select Restore to show them again.

The GraphQL client's right sidebar gives you access to documentation, comments, and information about your request.

Documentation - View descriptions of the fields and arguments in your query. Postman automatically generates detailed documentation tailored to each request, pulling relevant descriptions and type information from the schema. You can add descriptions by selecting Add description then entering your content using Postman's built-in editing tools. You can also select Generate with Postbot to use Postman's AI assistant to document your request.
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 details about your request, like the request ID and creation date.