*** title: Create examples of request responses to illustrate API use cases approved: 2025-08-20T00:00:00.000Z max-toc-depth: 2 topictype: procedure -------------------- 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 add examples 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](/docs/design-apis/mock-apis/set-up-mock-servers/), so developers and testers can start [writing code](/docs/tests-and-scripts/write-scripts/test-scripts/) against your API, even before it's complete. In addition, you can include examples in your API's [public documentation](/docs/publishing-your-api/publishing-your-docs/) to help anyone in the world who uses your API. ## Add an example An example is always associated with a [request](/docs/sending-requests/create-requests/create-requests/) in a [collection](/docs/sending-requests/create-requests/intro-to-collections/), 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](/docs/sending-requests/response-data/responses/) in Postman, you have the option to save it as an example. 1. Click the

**Items** tab in the left sidebar. 2. Click **Collections**. 3. Open a request and click **Send**. 4. In the response pane, select

**Save Response**. For [gRPC examples](/docs/sending-requests/grpc/using-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](/docs/sending-requests/create-requests/create-requests/) and the [response](/docs/sending-requests/response-data/responses/) look, including the status code and response body. 1. Click the

**Items** tab in the left sidebar. 2. Click **Collections**. 3. Select

**View more actions** next to a request and then select **Add example**. 4. Enter a name for the example. 5. Edit the request part of the example. * Add any parameters or headers as needed. * Enter the request body and select a content type. 6. 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. 7. Click **Save**. ## 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. Click the

**Items** tab in the left sidebar. 2. Click **Collections**. 3. Select a request, and then select an example to open it. 4. Click **Try** to open the example as a request in a new tab. The request automatically sends in the new tab. 5. 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. Click the example's name to open it in a separate tab. 6. Optionally, you can click **Save** to save the new request to a new or existing collection in your workspace. 7. Choose a location to save the new request, and then click **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. Click the

**Items** tab in the left sidebar. 2. Click **Collections**. 3. Select a request, and then select an example to open it. 4. Make any changes to the example request or response. 5. Click **Save**. To edit an example after trying it, do the following: 1. Click the

**View more actions > Update example**. You'll receive confirmation once the example is updated. The new request isn't automatically saved. 8. Optionally, you can click **Save** to save the new request to a new or existing collection in your workspace. 9. Choose a location to save the new request, and then click **Save**. ## Share an example You can share examples with collaborators by going to the example you want to share in the sidebar. Click

**View more actions** next to the example you want to share, then select **Share**. For more details about sharing examples, see [Share your work in Postman](/docs/collaborating-in-postman/sharing/). ## Add comments to an example 1. Select

**Comments** in the right sidebar and enter your comment. 2. Click **Comment** to add your comment. You can learn more about [using comments to collaborate on examples](/docs/collaborating-in-postman/comments/). ## 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. Click the

**Items** tab in the left sidebar. 2. Click **Collections**. 3. Click

**View more actions** next to an example, and then select **Duplicate**. 4. Make any changes to the example request or response. 5. Click **Save**. ## 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. Click the

**Items** tab in the left sidebar. 2. Click **Collections**. 3. Click

**View more actions** next to an example, and then select **Delete**. 4. Click **Delete** to confirm. ## Use examples in documentation Postman automatically [generates documentation](/docs/publishing-your-api/document-a-collection/) for every collection you create. The generated documentation [includes any examples](/docs/publishing-your-api/authoring-your-documentation/#including-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](/docs/design-apis/mock-apis/set-up-mock-servers/). You can [publish your documentation](/docs/publishing-your-api/publishing-your-docs/) 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 [Set up a Postman mock server](/docs/design-apis/mock-apis/set-up-mock-servers/). * To learn how to include examples in your API documentation, visit [Document a collection in Postman](/docs/publishing-your-api/document-a-collection/).