Postman Mock Servers

A mock server simulates an API. It returns pre-defined responses without a real backend running anywhere. Developers use mock servers to build and test a front-end before the real API is ready, or to test specific response scenarios that are hard to trigger on a live server.

The Stage Set Analogy

Imagine filming a movie scene that takes place inside a bank. Building a real bank for one scene would be expensive and slow. A movie crew builds a stage set that looks exactly like a bank. Actors rehearse with it as if it were real.

A mock server works the same way. Your app sends a request to the mock URL and gets back a realistic-looking response. The real backend has not been built yet, but development continues unblocked.

Without Mock Server:                With Mock Server:
  Frontend waits for backend           Frontend sends request to mock URL
  Backend team finishes first          Mock server returns fake response
  Testing starts weeks later           Frontend testing starts today

How Postman Mock Servers Work

Your App / Postman Request
         │
         ▼
  Mock Server URL (hosted by Postman)
         │
         ▼
  Matches the request path and method
  to saved examples in your collection
         │
         ▼
  Returns the matching example response

The mock server reads the path, method, and optionally the query parameters of your request. It then finds a matching saved example in your collection and returns that example's response.

Create a Mock Server from a Collection

1. Go to your collection in the sidebar
2. Click the three-dot menu on the collection
3. Select Mock Collection
4. Give the mock server a name (for example: Users API Mock)
5. Choose whether to make it private (recommended) or public
6. Click Create Mock Server

Postman generates a unique URL for your mock server, for example:
https://abc12345.mock.pstmn.io

Add Examples to a Request

The mock server returns examples you save on each request. An example is a saved snapshot of a request and response pair.

Save an Example

1. Open a request in your collection (for example: GET /users)
2. Send the real request to get a real response, or type your own response
3. In the response panel, click Save as Example
4. Give the example a name: Get All Users – Success
5. Edit the example response body to contain the data you want the mock to return
6. Click Save

Example Response for a Mock

Here is what an example saved for GET /users might contain:

Request:
  GET {{mockUrl}}/users

Response (saved in example):
  Status: 200 OK
  Body:
  [
    { "id": 1, "name": "Alice Park", "role": "admin" },
    { "id": 2, "name": "Ben Carter", "role": "editor" }
  ]

When your app calls the mock URL at /users with GET, it receives exactly this response — every time.

Simulate Different Scenarios with Multiple Examples

A single request can have multiple saved examples. The mock server picks the right one based on query parameters or request body.

Request: GET /users?role=admin
  → Example: "Admin Users" response
    [{ "id": 1, "name": "Alice Park", "role": "admin" }]

Request: GET /users?role=editor
  → Example: "Editor Users" response
    [{ "id": 2, "name": "Ben Carter", "role": "editor" }]

This lets you test your frontend's handling of different data sets without any backend logic.

Simulate Error Responses

You can create examples that return error status codes to test how your app handles failures.

Add a 404 Example

1. Open the GET /users/:id request
2. Click Add Example
3. Set the response status to 404 Not Found
4. Set the body to:

{
  "error": "User not found",
  "code": 404
}

5. Save the example as Get User – Not Found

Now you can test your app's 404 handling without having to delete records from a real database.

Use the Mock URL in Postman

1. Copy your mock server URL from the Postman Mock Servers page
2. Set it as an environment variable: mockUrl = https://abc12345.mock.pstmn.io
3. Update your requests to use {{mockUrl}} as the base URL
4. Switch your environment to the mock environment and click Send

The mock server responds with your saved example instead of hitting a real backend.

Private vs Public Mock Servers

For development work, keep mock servers private. Pass your Postman API key in the request header x-api-key to authenticate.

Limitations of Postman Mock Servers

• Mock servers do not execute logic — they only match requests to examples and return the saved response
• They cannot generate dynamic calculations based on request input
• Free Postman accounts have a monthly call limit on mock servers
• Response matching is based on path, method, and query parameters only — not request body content

Summary

Postman mock servers return saved example responses without a real backend. You create a mock from a collection, add examples to requests, and point your app at the mock URL. Multiple examples on one request simulate different scenarios like success, empty results, and errors. Mock servers unblock frontend development and let you test edge cases that are hard to reproduce on a live system.