Skip to navigation
Test APIs with PostmanMock an APIMocks

Create a code-based API mock in Postman

View as Markdown

Create a mock to build a code-based stand-in for an API with custom JavaScript request handlers. You can create an empty mock to write yourself, or use Agent Mode to generate one from your context.

Create a mock

Before you create a mock in Local View, connect your Git project to your workspace using Native Git.

In the sidebar, click Add icon and select Mock. The mock is created and available in the Items icon Items tab under Mocks in the sidebar.

If you’re in Local View, Postman generates files for your mock in your local Git repository. To learn more, see About the mock files.

You can also create a mock from the Postman CLI. Use postman mock generate to build a mock from an OpenAPI specification, a collection, or a dataset, then postman mock run to start it locally.

After creating your mock, you can customize its behavior and settings:

  • Customize your mock — Edit the JavaScript implementation to define how the mock handles requests and returns responses.
  • Use pm methods in the mock editor — Use built-in objects like pm.mock and pm.state to serve saved examples and add stateful behavior.
  • Manage scenarios in a mock — Add named scenarios to model different situations your API might encounter, each with its own implementation and behaviors.
  • Edit a mock — Update settings like the mock’s name and port number.

About the mock files

In the Postman desktop app in Local View, Postman generates a folder for each mock in the postman/mocks/ directory in your local Git repository. The folder is named after the mock and contains:

  • config.yaml — A YAML file with the mock settings and the list of scenarios. Each scenario entry includes its name, the path to its implementation file, and any behaviors applied to it, stored under the scenario’s conditions key. The default scenario is marked with default: true.
  • A <scenario-name>.js file for each scenario — A JavaScript file with that scenario’s request handling implementation. Endpoints are defined in the code using // @endpoint comments. Each // @endpoint comment lists the route in the sidebar and lets you send a request to it from the code on hover.

Any changes you make in Postman are reflected in these files, and updates to the files are reflected in Postman.

When working in Local View, make sure to commit the mock folder to your Git repository. This ensures your teammates get the latest mock files.

Use Agent Mode to create a mock

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

In Local View, you can also use Agent Mode to generate a mock based on endpoints in your connected Git repository. Select Options icon More actions > Scan endpoints next to a mock in the sidebar.

The following are example prompts you can use to create different API behaviors with mocks.

Mock request patterns and failures
Create a mock for a payments API where every third request to /charge fails with 500, and a successful one after that. It remembers attempts across requests.
Mock an authentication flow
Mock an auth service locally: POST /login returns a token, GET /me only works if the last login token is sent, else 401.
Mock CRUD behavior with memory
Set up a mock cart service: POST /cart adds an item, GET /cart returns everything added so far, DELETE /cart clears it. It remembers items between requests.

Edit a mock

Edit a mock to control how it runs on your machine, such as the port number and restart behavior. To configure a deployed mock server, see Configure a deployed mock server.

  1. Click the Items icon Items tab in the sidebar.

  2. Click Mocks.

  3. Select the mock you want to edit.

  4. In the upper right of the editor, select Options icon > Edit.

  5. You can edit the following details:

    • Name — The name of the mock.
    • Port — The local port number for the mock. If the specified port is already in use, the mock falls back to an available port assigned by the OS.
    • Origin — Host URLs this mock can stand in for or intercept. When you run the mock in a simulation’s proxy mode, calls to these hosts are routed to the mock. A simulation copies origin when it’s created, so changing it afterward doesn’t update an existing simulation. Edit the member in the .sim.yaml file or recreate the simulation to pick up the change.
    • Auto-restart on change — By default, mocks restart when the handler or configuration changes. Deselect the checkbox to turn off this behavior.

  6. Click Save.