> This page is for Postman Docs, version Latest (v12) (default).
> For other versions, use one of these documentation indexes:
> - Latest (v12) (default): https://learning.postman.com/latest-v-12/llms.txt
> - v11: https://learning.postman.com/v11/llms.txt

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt.

# Create a code-based API mock in Postman

> Create a code-based API mock in Postman or the Postman CLI, understand its files, generate one with Agent Mode, and edit how it runs.

Create a [mock](/docs/design-apis/mock-apis/mocks/overview) 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 \[#create-a-mock]

> **Tip**
>
> Before you create a mock in Local View, [connect your Git project to your workspace](/docs/use/native-git/setup/#connect-your-git-project-to-your-workspace) using Native Git.

In the sidebar, click ![Add icon](https://assets.postman.com/postman-docs/aether-icons/v12/action-add-stroke.svg#icon) and select **Mock**. The mock is created and available in the ![Items icon](https://assets.postman.com/postman-docs/aether-icons/v12/descriptive-items-stroke.svg#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](#about-the-mock-files).

You can also create a mock from the Postman CLI. Use [`postman mock generate`](/docs/postman-cli/postman-cli-mock#postman-mock-generate) to build a mock from an OpenAPI specification, a collection, or a dataset, then [`postman mock run`](/docs/postman-cli/postman-cli-mock#postman-mock-run) to start it locally.

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

* [Customize your mock](/docs/design-apis/mock-apis/mocks/customize-a-mock#customize-your-mock) — Edit the JavaScript implementation to define how the mock handles requests and returns responses.
* [Use pm methods in the mock editor](/docs/design-apis/mock-apis/mocks/customize-a-mock#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](/docs/design-apis/mock-apis/mocks/scenarios-and-behaviors#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](#edit-a-mock) — Update settings like the mock's name and port number.

### About the mock files \[#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](#edit-a-mock) and the list of [scenarios](/docs/design-apis/mock-apis/mocks/scenarios-and-behaviors#manage-scenarios-in-a-mock). Each scenario entry includes its name, the path to its implementation file, and any [behaviors](/docs/design-apis/mock-apis/mocks/scenarios-and-behaviors#apply-behaviors-to-a-scenario) 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](/docs/design-apis/mock-apis/mocks/customize-a-mock#customize-your-mock). 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.

> **Note**
>
> 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 \[#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.

> **Tip**
>
> In Local View, you can also use Agent Mode to generate a mock based on endpoints in your connected Git repository. Select ![Options icon](https://assets.postman.com/postman-docs/aether-icons/v12/action-options-stroke.svg#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]

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](/docs/design-apis/mock-apis/mock-servers/from-a-mock#configure-a-deployed-mock-server).

1. Click the ![Items icon](https://assets.postman.com/postman-docs/aether-icons/v12/descriptive-items-stroke.svg#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](https://assets.postman.com/postman-docs/aether-icons/v12/icon-action-options-stroke.svg#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](/docs/postman-cli/postman-cli-simulator#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**.