Create examples of request responses to illustrate API use cases

Examples show your API endpoints in action and give more details on how requests and responses work. You can add an example to a request by saving a response, or you can create an example with a custom response to illustrate a specific use case. Once you've created examples, you can use them to set up a mock server or add more detail to your API documentation.

Understanding examples

In Postman, an example is a pairing made up of a request and a related response. Each example includes a request part (method, URL, parameters, headers, and body) and a response part (status code, body, and headers). You create examples by adding them to requests in collections, and one request can have multiple examples.

Having multiple examples for one request is useful for illustrating the different ways an endpoint can respond to a request. You might have examples that respond with different status codes (such as 200 or 404) or that return different data (or no data at all).

Examples are useful in several ways. Developers and testers can refer to examples to better understand how an endpoint functions in different scenarios. Examples can also be used to set up mock servers, so developers and testers can start writing code against your API—even before it's complete. In addition, you can include examples in your API's public documentation to help anyone in the world who uses your API.

Add an example

An example is always associated with a request in a collection, and a request can have more than one example. To add an example to a request, send the request and then save the response as an example. You can also manually add an example to a request and define a custom response. After adding an example using either method, you can edit it at any time to make changes.

For optimal Postman performance, example responses must be smaller than 5 MB.

Save a response as an example

When saving a response in Postman, you have the option to save it as an example.

1. Select Collections in the sidebar.

2. Open a request and select Send.

3. In the response pane, select Save as Example for HTTP, GraphQL, and gRPC responses, or Save Response for WebSocket, Socket.IO, and MQTT responses.

   

For gRPC examples with streaming methods, you must end the stream before saving the response/message stream as an example.

Add a custom example

With a custom example, you can define how both the request and the response look, including the status code and response body.

1. Select Collections in the sidebar.

2. Select the more actions icon next to a request and then select Add example.

   

3. Enter a name for the example.

4. Edit the request part of the example.

   • Add any parameters or headers as needed.
   • Enter the request body and select a content type.

5. Edit the response part of the example.

   • Enter a Status Code (such as 200 or 404).
   • Enter the response body and select a content type.
   • Add any headers as needed.

6. Select Save to save the example.

Try an example

Examples are stored in a collection with their associated requests. You can try an example by opening the example as a request in a new tab.

1. Select Collections in the sidebar.

2. Select a request, and then select an example to open it.

3. Select Try to open the example as a request in a new tab. The request will automatically send in the new tab.

   

4. Review the request and response details.

   

   The new request isn't automatically saved.

   The name of the example you're trying is next to the request's name in the workbench. Select the example's name to open it in a separate tab.

   

5. Optionally, you can select Save to save the new request to a new or existing collection in your workspace.

6. Choose a location to save the new request, and then select Save.

   

Edit an example

You can edit an example at any time to remove sensitive tokens, change the status code, or make any other adjustments.

To edit an example, do the following:

1. Select Collections in the sidebar.
2. Select a request, and then select an example to open it.
3. Make any changes to the example request or response.
4. Select Save to save the example.

To edit an example after trying it, do the following:

1. Select Collections in the sidebar.

2. Select a request, and then select an example to open it.

3. Select Try to open the example as a request in a new tab.

   

4. Make any changes to the new request.

5. Select Send.

6. In the response pane, select the more actions icon and then select Update example. You will receive confirmation once the example is updated.

   

   The new request isn't automatically saved.

7. Optionally, you can select Save to save the new request to a new or existing collection in your workspace.

8. Choose a location to save the new request, and then select Save.

   

Share an example

You can share examples with collaborators by going to the example you want to share in the sidebar. Select the more actions icon next to the example you want to share, then select Share.

For more details about sharing examples, see Share your work in Postman.

Add comments to an example

1. Select the comments icon in the right sidebar and enter your comment.
2. (Optional) Select the Watch collection checkbox to be notified when there are changes to the collection that the example is in.
3. Select Comment to add your comment.

You can learn more about using comments to collaborate on examples.

Duplicate an example

Duplicate an example to add a new example using an existing example as a base. You can then edit the copied example to change the name, status code, or any other part of the request or response.

1. Select Collections in the sidebar.
2. Select the more actions icon next to an example, and then select Duplicate.
3. Make any changes to the example request or response.
4. Select Save to save the example.

Delete an example

Deleting an example removes it from the collection and from the associated API documentation. Any mock servers you have set up can no longer use the example to return a response.

1. Select Collections in the sidebar.
2. Select the more actions icon next to an example, and then select Delete.
3. Select Delete to confirm.

Use examples in documentation

Postman automatically generates documentation for every collection you create. The generated documentation includes any examples that have been added to the collection. If you edit an example, the documentation is automatically updated with your changes.

Examples give more details and clarification for your API and help your team to work together on API development. Front-end developers, back-end developers, and testers can all work in parallel, using the examples in the documentation for guidance or to set up mock servers.

You can publish your documentation to make your examples publicly available to anyone in the world.

Next steps

You can use examples to set up a mock server and enhance your documentation.

• To learn how to use examples to set up a mock server, visit Configure and use a Postman mock server.
• To learn how to include examples in your API documentation, visit Document a collection in Postman.