Update to Postman

{
  "name": "api-mocking",
  "description": "Stands up a fake backend that behaves like a real API — from a collection or an OpenAPI spec, running locally or pushed to Postman's cloud for a durable URL — plus request-time scenario and status-code overrides for testing failure paths. Use when the user asks to \"mock this API,\" \"create a mock server,\" \"fake the backend,\" \"run tests without hitting the real API,\" or \"simulate an error/out-of-stock response.\" Covers `postman mock`. Depends on bootstrap for the workspace id only once a mock is pushed to the cloud (`-w`, or the workspace linked in `.postman/resources.yaml`) — generating and running a mock locally needs nothing from bootstrap.",
  "included_files": [],
  "skill_md_contents": "---\nname: api-mocking\ndescription: Stands up a fake backend that behaves like a real API — from a collection or an OpenAPI spec, running locally or pushed to Postman's cloud for a durable URL — plus request-time scenario and status-code overrides for testing failure paths. Use when the user asks to \"mock this API,\" \"create a mock server,\" \"fake the backend,\" \"run tests without hitting the real API,\" or \"simulate an error/out-of-stock response.\" Covers `postman mock`. Depends on bootstrap for the workspace id only once a mock is pushed to the cloud (`-w`, or the workspace linked in `.postman/resources.yaml`) — generating and running a mock locally needs nothing from bootstrap.\n---\n\n# API Mocking\n\n## Overview\n\nThis skill covers the Postman CLI (`postman mock`) for **Code Mocks** — the\ncode-based mock product. It is not the postman-app UI (Local Mode sidebar,\nAgent Mode tools, Simulations), nor the older classic/collection mocks that\nserve saved collection examples from a `*.mock.pstmn.io` URL — that's a\ndifferent product (the MCP `createMock` flow), not this skill.\n\nA **local** mock is two files on disk: `config.yaml` (name, port, scenarios) and\n`default.js` — a plain Node HTTP server, and the mock itself, not a wrapper\naround one. Generating, inspecting, running, and calling a local mock work for\na logged-out guest. Only sharing it — pushing to the cloud and deploying a\ndurable URL — needs `postman login`. The progression is one model in three\nplaces: local folder ──`push`──▶ Code Mock (cloud definition) ──`deploy`──▶\nMock Server (the reachable URL).\n\nDefault path: write a local folder, then `mock push` later if something other\nthan you needs to hit it over the network (a teammate, CI elsewhere, a webhook\nsender). A purely local mock answering a `postman request` on your machine\nnever needs cloud. The exception is `generate -w`, which creates the mock in a\nworkspace only and writes no local files — use that only when you intentionally\nskip the repo copy.\n\n## Process\n\n1. **Generate.** `postman mock generate -n NAME` with no source scaffolds a\n   sample shopping-cart mock (`POST /cart/items`, `GET /cart`, `POST /checkout`)\n   — the fastest way to a server that already answers, useful whenever the\n   point is exercising mock *behavior* rather than a specific API's shape. Pass\n   a real source — `postman mock generate SOURCE -n NAME`, where `SOURCE` is a\n   collection file/directory or an `openapi.yaml` — when the endpoints need to\n   mirror an actual API. Either form writes `config.yaml` + `default.js` into\n   `postman/mocks/NAME/` (default port 4500).\n   - `postman mock generate SOURCE --update ./postman/mocks/NAME` regenerates\n     the default handler from the source in place, keeping the existing name,\n     port, and scenarios. `--update` still needs the `SOURCE`; it cannot be\n     combined with `--output`.\n   - `-w <workspaceId>` saves the mock to a cloud workspace *instead of* the\n     repository — it writes no local files and requires being logged in. Cannot\n     be combined with `--output`, `--force`, or `--update`. Prefer local\n     generate + later `push` when you still need `mock run` from a folder.\n2. **Run it.** `postman mock run ./postman/mocks/NAME` starts the server and\n   prints the bound URL (`... at http://localhost:PORT`). If the port in\n   `config.yaml` is taken and `--port` wasn't passed explicitly, it falls back\n   to a free OS-assigned port instead of erroring — read the real port off that\n   line rather than assuming the configured one. Naming `--port N` explicitly\n   makes a taken port a hard error; `--port auto` always picks a free one.\n3. **Call it.** Plain `postman request localhost:PORT/route` returns the\n   default scenario's response. Two headers can change that per-request, with no\n   restart: `x-mock-scenario: <name>` selects a scenario the mock defines\n   (valid names live in `config.yaml`); a name the mock doesn't define is not an\n   error — it falls back to the default scenario. `x-mock-response-code: <code>`\n   filters an endpoint's saved example responses to the one with that status, so\n   it only changes anything when that endpoint actually has an example for that\n   code — mocks generated from a collection/spec with multiple example statuses\n   honor it; the built-in sample mock has one response per route and ignores it.\n   A wrong route comes back as `Endpoint not defined`. There's no hot reload: a\n   `default.js` edit does nothing until you Ctrl+C the running server and\n   `mock run` it again.\n4. **Push it, if it needs to leave your machine.**\n   `postman mock push ./postman/mocks/NAME` is safe to re-run — `Created` the\n   first time, `Updated` after — and records the cloud mapping in\n   `.postman/resources.yaml`; commit that change. If a mock server is already\n   live for this mock, the push updates what it serves.\n5. **Deploy it, for a URL that outlives your terminal.**\n   `postman mock deploy CLOUD_ID -s SLUG -y` prints\n   `https://SLUG.mock.<team-domain>.postman.dev`. Deployed private by default —\n   callers need a Postman API key (`x-api-key`) — add `--public` only when the\n   mock should be reachable by anyone with the URL. `--auto-deploy` re-publishes\n   the live server automatically whenever the mock changes; even without it, a\n   later `push` already updates a live server, so you only re-`deploy` for the\n   first URL or after taking the server down.\n6. **See who's calling it.** `postman mock get CLOUD_ID` (table or `--json`)\n   returns `mockServerId`; feed that into `postman mock log MOCK_SERVER_ID` for\n   call entries (filter with `--method` / `--status` / `--path` / `--since` /\n   `--until` / `--limit`, or `--json`). An empty log means the URL genuinely\n   hasn't been hit — a rejected caller still shows up, recorded with its failing\n   status code.\n7. **Tear down.**\n   - Local: `postman mock delete ./path --yes` — refuses while that mock is\n     **running** locally; stop `mock run` first.\n   - Cloud: `postman mock delete CLOUD_ID --yes` — refuses while the mock is\n     **running locally** *or* **deployed**; stop the local run and take the\n     mock server down first.\n   Cloud delete doesn't touch `.postman/resources.yaml`; drop that line by hand\n   afterward or the repo keeps claiming a mock that's gone.\n\nTo point real request/assertion runs at a mock instead of hand-editing\nbase-URL variables, see the `api-testing` skill's `--use-mock`/`--mock` flags\non `collection run`.\n\n## The two ids that matter\n\n- **Code-mock id** — the `id` in `config.yaml`, and the id that `push` and\n  `generate -w` print (often the same value). Use it for `get`, `deploy`,\n  `delete`, and `run` by cloud id.\n- **`mockServerId`** — a different value from `mock get CLOUD_ID` (table or\n  `--json`). Use it for `mock log`, and nothing else.\n\n## Critical Rules\n\n1. **When you're not signed in, every gated cloud command fails closed:**\n   `Authentication required. Run postman login or provide --api-key`, exit 1,\n   nothing half-done. (Signed in but lacking access fails differently — a\n   permission or missing-workspace error.) Whether a command is gated is decided\n   by what you pass it, not the verb — `mock get`/`mock run` take either a local\n   path (ungated) or a cloud ID (gated); `mock list` is gated only when called\n   with no path.\n2. **`push` is what moves an existing local mock to the cloud — `-w` at\n   `generate` time is optional, not a fork you must choose up front.** A mock\n   built as a guest can be pushed and deployed later with no rework. Do not\n   assume `generate -w` left a `postman/mocks/NAME/` folder to `run`.\n3. **`--public` on `deploy` is the one action here with real exposure** — it\n   stands up a server anyone with the URL can hit, with no API key. The default\n   (private) is the safe one; confirm intent before adding it.\n4. **To change a mock:** refresh it from a source with\n   `postman mock generate SOURCE --update PATH`, or edit `default.js` by hand\n   and restart `mock run`. Never pass a code-mock id to `mock log` — that\n   command takes a `mockServerId`.\n5. **`-w`/`--workspace` only exists on `generate`, `list`, `push`, and\n   `deploy`.** `get`, `run`, `log`, and `delete` already take a path or an id\n   that says where the mock is — there's nothing left for `-w` to resolve on\n   those.\n\n## Verification\n\nA mock isn't done because `generate` or `run` exited 0 — hit it with\n`postman request` and check the actual status/body, or `mock get CLOUD_ID\n--json` for a cloud one, then state whether it ended up local or cloud, and\n(if deployed) private or public. For a scenario check, confirm a *valid* name\nfrom `config.yaml` actually changed the response — a typo'd name falls back to\nthe default, so a 200 alone proves nothing. For a status-code check, use an\nendpoint that has an example for that code (not the sample mock). A passing\nexit code from `request` is not enough.\n"
}