Simulate your API using a Git-backed mock server

With Native Git, you can create a local mock server that’s stored in your local Git repository. A local mock server enables you to simulate a real API server locally in a branch, where you’re making API changes. This is useful for local API development and testing when dependencies are unavailable or still under development, and before committing your changes to the Postman cloud.

You can create a local mock server from a template that you can customize or using Agent Mode. You can start the mock server to simulate API responses based on the request and response logic defined in your implementation file, and view logs for APIs the mock server handles.

Before you get started, connect your Git project to your workspace.

Create a local mock server

1. Click the Items tab in the sidebar.

2. Click .

3. Select Mock and choose how you’d like to create your local mock server:

   • Create with template - Create a mock server from a template with a basic HTTP server you can customize.
   • Create with AI - Use Agent Mode to quickly create a mock server based on endpoints in the connected Git repository.

This adds two files to the postman directory in your local Git repository:

• postman/mocks/mock-server-name.js - A JavaScript file that contains the mock server implementation. Set the request and response for simulating real API behavior.
• postman/mocks/mock-server-name.json - A JSON file that contains the mock server configuration, such as the port number and routes.

Customize your local mock server

Define how your mock server handles requests and returns responses in the mock-server-name.js implementation file. This is where you simulate the behavior of a real API.

To customize your mock server, do the following:

1. Click the Items tab in the sidebar.

2. Click Mocks.

3. Select the local mock server you want to customize.

4. Update the implementation file with your request handling logic.

   Example:

   1
   const http = require("http");
   2
   3
   const server = http.createServer((req, res) => {
   4
   if (pm.mock.matchRequest('<request-id>', req)) {
   5
       return pm.mock.sendExample('<example-id>', res);
   6
   }
   7
   8
   ...
   9
   });

Local mock servers are implemented using custom request handlers. You can use standard HTTP server patterns to control how requests are handled. For example, you can add conditionals, generate dynamic data, or implement any valid JavaScript logic.

Within these handlers, you can:

• Use pm.mock to serve responses from your saved examples.
• Use pm.state to persist data across requests and enable stateful behavior.
• Use pm.datasets to query datasets and use the data in your request handling logic.
• Use pm.test and pm.expect to add test assertions and validate request or response data.

Learn more about the pm objects available in the mock editor.

Configure local mock server details

Configure the mock server details in the mock-server-name.json file, such as the port number and routes.

To configure your mock server details, do the following:

1. Click the Items tab in the sidebar.

2. Select the local mock server you want to configure.

3. Click Edit mock configuration in the upper right to open the JSON file.

4. You can update the following details:

   • version - The version of the mock server configuration file.
   • name - The name of the mock server.
   • protocol - The protocol the mock server uses, either http or https.
   • port - The port number the mock server listens on.
   • mockSrc - The path to the JavaScript implementation file.
   • routes - An array of route objects that define the endpoints for the mock server.
   • autoRestartOnChange - A Boolean value that determines whether the mock server should automatically restart when changes are made to the configuration or implementation files.
   • logging - An object that contains logging configuration for the mock server, such as the log level and Boolean whether to show the body of requests and responses in the logs.

Use Agent Mode with local mock servers

With Agent Mode, you can generate and modify local mock servers using prompts. It understands your workspace context and can create realistic mock behavior, including multi-step workflows and data that persists across requests.

The following are example prompts you can use to create and test different API behaviors with local mock servers.

Simulate request patterns and failures

Use this prompt to create a mock server that introduces failures at specific intervals.

Create a local mock for a payments API where every third request to /charge fails with 500, and a successful one after that. It should remember attempts across requests.

Simulate an authentication flow

Use this prompt to mock a basic login and authorization flow where access depends on prior requests.

Mock a simple auth service locally: POST /login returns a token, GET /me only works if the last login token is sent, else 401.

Simulate CRUD behavior with memory

Use this prompt to create a mock service that stores and returns data across requests.

Set up a local mock cart service: POST /cart adds an item, GET /cart returns everything added so far, DELETE /cart clears it. It should remember items between requests.

Simulate idempotent operations

Use this prompt to ensure repeated requests return consistent results instead of creating duplicates.

Mock an orders API where posting the same orderId twice returns the same response instead of creating a new one.

Simulate multi-step workflows

Use this prompt to model flows where later requests depend on earlier ones.

I'm testing a 2-step OTP flow. Create a local mock: POST /otp/send generates a code, POST /otp/verify only succeeds if the code from the previous call is sent back.

Simulate runtime configuration changes

Use this prompt to create a mock that reflects updates made during execution.

Create a local mock for a feature flags service: PUT /flags/:name to turn a flag on/off, and GET /flags/:name reflects the latest value across requests.

Simulate state-dependent failures

Use this prompt to create behavior that changes based on prior interactions with specific resources.

Mock the inventory service locally: the first call to /reserve/:sku succeeds, subsequent calls for the same SKU return 409 already reserved until I call /release/:sku.

Simulate long-running processes

Use this prompt to model APIs that return different states over time.

Create a local mock for a job API: POST /jobs starts one, GET /jobs/:id returns pending first, then running, then done across polls.

Use pm methods in the mock editor

You can use some pm objects in the mock editor the same way you use them in scripts.

pm.mock

Postman provides an object called pm.mock that’s available in the mocks sandbox environment. It gives you structured, Postman-aware functions for matching incoming requests and sending responses. This includes the ability to serve responses from your existing saved Postman examples rather than hard-coding everything. To learn more, see Reference requests and examples in local mock servers.

pm.state

Postman provides an object called pm.state that’s available in the mocks sandbox environment. It provides a persistent store for managing data across requests, enabling your mock server to behave like a real service instead of returning static responses. State persists across runs until it’s cleared using pm.state.clear(). To learn more, see Persist state across requests in local mock servers.

pm.datasets

Postman provides a function called pm.datasets that enables you to access datasets and run SQL queries against them. You can run predefined views or custom queries to retrieve structured data at runtime. This enables you to use persistent, queryable data across requests, making your mock servers more dynamic and realistic. To learn more, see Manage and use datasets in scripts.

pm.test and pm.expect

The pm.test object enables you to define test assertions in your mock server implementation file. You can use it with pm.expect, which provides Chai-style expectations for validating request headers, body content, status codes, or custom variables. Test results (pass, fail, or skip) are recorded and surfaced in mock server logs. Learn more about writing tests using pm.test and pm.expect.

pm.environment

The pm.environment object provides access to variables in the active environment. To learn more, see Reference variables in Postman scripts.

pm.globals

The pm.globals object provides access to global variables at the workspace level. To learn more, see Reference variables in Postman scripts.

Start a local mock server

1. Click the Items tab in the sidebar.
2. Select the local mock server you want to start.
3. Click Start in the upper right. You can also select More actions > Start next to a local mock server in the sidebar.
4. Click Copy URL to copy the URL for the mock server.
5. Click Collections in the sidebar and create an HTTP request.
6. Send requests to the mock server URL and observe the responses, simulating a real API.

Click Stop in the upper right to stop the mock server.

Apply a simulation to a local mock server

Apply a simulation to a local mock server to introduce real-world conditions like latency, errors, and rate limits. This enables you to observe how your service behaves under stress and performance constraints, so you can address issues before deploying to staging or production.

From a mock server, you can click Simulate in the upper right to create or update a simulation.

To learn more, see Simulate real-world conditions in Postman.

View mock server logs

View details about incoming requests to your local mock server and the responses sent in the logs.

1. Click the Items tab in the sidebar.
2. Select the local mock server you started.
3. View the logs on the right in the Mock Logs pane.

You can click a request to view more details about the request and response, such as the headers and body.

Logs with the simulator icon indicate requests that ran with a simulation applied.

Click Clear logs to clear the logs for the mock server.