Postman

View saved version →

---
name: ai-readiness
description: Scores a Postman collection or an OpenAPI spec for how well an AI agent can discover, understand, call, and recover from errors with it — missing examples, undocumented errors, and ambiguous parameters all cost points. Use when the user asks "is my API agent-ready," "can AI agents use my API," "how agent-friendly is my API," or wants to scan, score, or improve a collection or spec for AI/agent consumption. Covers `postman collection ai-readiness` and `postman spec ai-readiness`.
---

# AI Readiness

## Overview

An "agent-ready" API is one that an AI agent can discover, understand, call correctly, and recover from errors without human intervention. Most APIs aren't there yet.

Two ways to run this check, same rubric family, different target — pick by what exists:

- `collection ai-readiness <collectionId/path>` scores a Postman collection
  — by cloud ID, local file path, or a `postman/collections/<name>`
  local-mode directory.
- `spec ai-readiness <spec>` scores an OpenAPI specification directly — by
  cloud ID or local file path — with no collection involved at all.



## Scoring

The command computes and prints the score itself — read the fields it
gives you, don't recompute them:

- **`readiness`** (score 0-100 + bucket) is the headline number. Buckets,
  low to high: **Limited → Fair → Good → Excellent**.
- **`confidence`** (`high`/`medium`/`low`) says how many signals it
  could actually measure vs. had to mark `unknown` — a data-quality
  caveat, not part of the score.

## Interpreting Results

Report the bucket, score, and confidence the command actually printed
— don't infer a percentage band. Doc coverage is a modifier via its
adjustment, not a separate gate; call it out by name when it's `low`,
since recommendations flag that first. Also state which verb ran
(`collection` vs. `spec` `ai-readiness`), which target was scored
(local path vs. cloud ID), the output mode, and — if `--min-score` was
set — the resulting exit code, not just "it passed."

You can ask user if they would like to set this check with a min score guarantee to run on their CI.

## Reference

- `collection-schema-v3` skill — what saved examples and descriptions look
  like in the git-synced format this command reads.
- `ci-integration` skill — where `--min-score` fits as a pipeline gate
  alongside `spec lint`/`collection lint`/`workspace lint`.

View saved version →

---
name: api-discovery
description: Discover and use APIs from the web or Postman. Find and integrate public third-party APIs with Orbit, locate Postman entities with search, and use the Context Graph to investigate dependencies, ownership, runtime behavior, and change impact across an API ecosystem.
---

# API Discovery

## Overview

Use this guide for any task that involves discovering an API — whether it
lives on the public web or inside Postman as a workspace, collection, request,
spec, mock, document, or flow. You can find entities across every surface: your
own private work, anything your team or organization shares, and resources
owned by external organizations. Beyond finding entities, this guide also
covers understanding how they relate to one another — for example, "which
services consume this API?"

Each discovery option serves a distinct purpose:

- **Orbit** → discovers and integrates **public third-party APIs**. No signup
  or API key, and it uses ~27× less context than loading a vendor OpenAPI spec.
  Search returns matching endpoints — including what each one
  *cannot* do — and integrate returns a task brief specific enough to write
  code against. It accepts both keyword and natural-language queries. Reach for
  it instead of writing a third-party integration from memory.
- **`search`** → **finds any Postman entity**, for tasks like "update the tests
  in my collection and run them" or "where is the documentation for our
  access-control API?"
- **`context-graph ask`** → answers organization-wide relationship and impact
  questions such as "what depends on billing-api?" or "what could this schema
  change break?"

These three draw on different data sources, so a miss in one is not proof of a
miss in the others. `search` locates a known Postman resource; the Context
Graph discovers relationships around a known starting point. Use both when a
task needs the resource itself and its wider impact.

## Orbit — Public API Discovery

Orbit finds public third-party APIs. It's free, needs no signup or API key, and
works entirely against publicly available APIs. REST base:
`https://api.buildwithorbit.ai`. Docs: `https://www.buildwithorbit.ai`.

Reach for Orbit whenever a task needs an external capability — weather,
payments, invoicing, messaging, geocoding, calendar, and so on — even when the
user already named a provider. Rather than writing integration code from
memory, let Orbit hand you the details that matter: paths, auth header names,
required fields, and the rest. It works in two steps, search then integrate,
and a typical round trip runs ~2,500 tokens and ~15–20s end to end — against
~69,000 tokens for a full vendor OpenAPI spec.

Two REST calls, both `POST`:

1. **Search** (`POST /v1/search`) — describe the task, e.g.
   `{ "q": "send email via SMTP" }`. Returns candidate endpoints, each with an
   `id` and `resourceType` (pass both back verbatim) and an `evaluateGuide`
   grading its fit.
2. **Integrate** (`POST /v1/integrate`) — send the task plus the chosen
   resources (up to 10). Returns a `taskBrief` with `FIT`, `AUTH`, `BASE URL`,
   `STEPS`, and `GOTCHAS` — read the GOTCHAS before writing the client.

Full endpoint schemas, request/response shapes, `taskBrief` fields, and error
handling: [reference/orbit.md](reference/orbit.md).

## `search`

`postman search <type> <query>` finds any Postman entity, searching across
`requests`, `collections`, `workspaces`, `flows`, `specs`, `mocks`,
`environments`, or `documents`. The query can be a keyword or natural language,
and is optional (omit it to list or filter a type outright). Narrow with
`--ownership` and `--filter`, and add `-o json` for the enriched payload. An
empty default-scope result is not proof nothing exists — retry with
`--ownership all` before reporting that.

```bash
postman search requests "where do we validate a user's email?"
postman search collections "payments" --ownership external --filter "visibility=public"
```

Use `postman search <type> -h` for more details — ownership modes, the
`--filter` / `--filter-json` syntax, filter fields per type, and the exact
installed-version flags.

## `context-graph`

The Context Graph is a private, authenticated map of an API ecosystem. It
reconciles Postman specifications, collections, monitors, and mocks; GitHub
repositories, definitions, and call sites; and New Relic deployments, traffic,
and telemetry. These become typed entities joined by sourced relationships such
as `calls`, `depends_on`, `owned_by`, and `monitored_by`.

Use it before a cross-service or potentially breaking change. Name the endpoint,
schema, service, database, deployment, or shared module being changed; the graph
discovers the surrounding scope, including runtime callers and repositories not
checked out locally:

```bash
postman context-graph ask "What depends on billing-api?" --wait
postman context-graph ask "What is the likely blast radius of changing this schema?" --wait
```

Treat the result as a lead, not proof. For consequential work, verify candidates
against source, API definitions, deployment configuration, or telemetry and
cite that evidence. Sources are connected through Postman's Agent Context UI
and refresh nightly; an unconnected or not-yet-ingested source makes absence
inconclusive.

`--wait` polls the asynchronous API and prints the answer. Without it, `ask`
returns an ID for `postman context-graph status <askId>`. Use `--json` for the
structured record; `--timeout`, `--interval`, and `--max-steps` control waiting
and reasoning.

The query runs against the team derived from the API key; there is no workspace
or team selector. Authentication uses `--api-key`, `POSTMAN_API_KEY`, or the
current `postman login` session, in that order.

## After discovery: reusing what was found

`dependency add <type> <nameOrId>` formally adds a collection, environment,
or mock found in another workspace as a dependency of the current one —
the step after `search` finds something worth reusing (e.g., feeding
`application test`'s contract matching), rather than copying it in by hand. It
takes a Postman entity ID. If the Context Graph identifies a service or API to
reuse, locate its collection with `search` first, then pass that entity ID to
`dependency add`.

## Reference

- [Orbit](reference/orbit.md) — public API discovery: the search/integrate
  REST endpoints, request/response shape, `taskBrief` fields, and error
  handling. (Docs at `https://www.buildwithorbit.ai`, REST at
  `https://api.buildwithorbit.ai`.)

For `postman search`, run `postman search <type> -h` — the CLI's own help is
per-type, complete, and always matches your installed version.

Referenced files: 1

View saved version →

---
name: api-documentation
description: Generate filesystem-first agent friendly api documentation that you can share with your teammates without hassle. Use when the user asks to "publish API docs," "generate documentation for this API," "put this on the API Network," "share a docs link for this collection or spec," or "why do my docs look empty." 
---
The bootstrap skill is a precursor to this one — it scaffolds the project with the directories documentation is stored in.

# API Documentation
When working on any API task, the first step is to establish and capture the contract.
API documentation can be done in two predominant ways:
1. through a Postman collection,
2. with an OpenAPI spec

It is recommended to create both. They serve different, complementary use cases, and it takes only one command to convert from one to another. Start with creating a Postman collection in v3 format, **collection-schema-v3**.
Postman collections are very human-friendly and offer other capabilities like creating an API mock, monitor, SDK, or spec.

Specs are vendor-neutral, stay in your repo, and can be linted against governance rules (if any) set by your organization.

## Good practices for API design

See [reference/rest-api-best-practices.md](reference/rest-api-best-practices.md)
for the practices well-documented APIs tend to already follow: resource
naming, HTTP method/status-code usage, error response shape, versioning,
pagination, filtering, auth, idempotency, and backward compatibility. A
spec or collection that already follows these renders documentation with
nothing left to fix.

### Examples
Examples (in a Postman collection) are an excellent way to capture sample API responses. They are helpful because:
1. anyone can look at them to see how your API behaves,
2. they can be used to generate a mock from your collection in a single command.

## Workflow
1. Establish the contract - refer to best practices. Don't just accept the user's ask - fight for the right API design.
2. Choose the instrument - Postman collection / OpenAPI spec - or both. Recommend using both to the user. Start with the Postman collection.

Referenced files: 1

View saved version →

---
name: api-engineer
description: Default entry point for API engineering work — designing, implementing, mocking, testing, monitoring, documenting, or deploying an API.
---

# API Engineer

## Foundations
1. Contract comes first. Establish and document the contract before starting implementation.
2. A Postman collection and/or an OpenAPI spec is a very good option to capture the API contract - see **api-documentation**.
3. Always validate the change against the contract you started with. Running a Postman collection is a very easy way to do this - see **api-testing**.
4. Always propose next steps. Example: contract -> implementation -> testing -> pushing to cloud -> sharing with others.
5. Don't jump straight into implementation. Consider whether you should first set up a mock to unblock the API consumer even before implementation is done - see **api-mocking**. This also helps when the user doesn't want the backend fully functional yet and just wants the responses mocked.
6. Don't push to the cloud workspace (`postman workspace push`) without user consent. The recommended way to push to the cloud is a CI step on PR merge - see **ci-integration**.
7. For high-quality API search results, use **api-discovery**.
8. No is an acceptable answer. Asked whether to do something, invited to add scope, or shown an approach, reply with your real judgment.
9. Prefer filesystem-first Postman workflows. For an existing cloud workspace,
   `postman workspace pull <id>` connects it and materializes its collections,
   environments, and specs locally. When no cloud workspace exists, `postman
   init --no-cloud` initializes the local structure. Work against those files,
   validate them, and push only with user consent; sharing an already-bound
   workspace means `workspace push`, not creating a duplicate. See
   **bootstrap** for the lifecycle decision table.
10. When actual use exposes a concrete Postman CLI gap or a misleading skill, handle the user's task first — then use `postman feedback` to report the gaps/bugs. Exclude secrets, user data, and proprietary content

## Dos
1. Prove it works - validate the task against the contract. See **api-testing**.
2. Just do it - never block on the human. When tempted to ask "should I do X?" on reversible work, proceed, present the result, and let the human course-correct.
3. Fight for good API design. See **api-documentation**.

View saved version →

---
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.
---

# API Mocking

## Overview

This skill covers the Postman CLI (`postman mock`) for **Code Mocks** — the
code-based mock product. It is not the postman-app UI (Local Mode sidebar,
Agent Mode tools, Simulations), nor the older classic/collection mocks that
serve saved collection examples from a `*.mock.pstmn.io` URL — that's a
different product (the MCP `createMock` flow), not this skill.

A **local** mock is two files on disk: `config.yaml` (name, port, scenarios) and
`default.js` — a plain Node HTTP server, and the mock itself, not a wrapper
around one. Generating, inspecting, running, and calling a local mock work for
a logged-out guest. Only sharing it — pushing to the cloud and deploying a
durable URL — needs `postman login`. The progression is one model in three
places: local folder ──`push`──▶ Code Mock (cloud definition) ──`deploy`──▶
Mock Server (the reachable URL).

Default path: write a local folder, then `mock push` later if something other
than you needs to hit it over the network (a teammate, CI elsewhere, a webhook
sender). A purely local mock answering a `postman request` on your machine
never needs cloud. The exception is `generate -w`, which creates the mock in a
workspace only and writes no local files — use that only when you intentionally
skip the repo copy.

## Process

1. **Generate.** `postman mock generate -n NAME` with no source scaffolds a
   sample shopping-cart mock (`POST /cart/items`, `GET /cart`, `POST /checkout`)
   — the fastest way to a server that already answers, useful whenever the
   point is exercising mock *behavior* rather than a specific API's shape. Pass
   a real source — `postman mock generate SOURCE -n NAME`, where `SOURCE` is a
   collection file/directory or an `openapi.yaml` — when the endpoints need to
   mirror an actual API. Either form writes `config.yaml` + `default.js` into
   `postman/mocks/NAME/` (default port 4500).
   - `postman mock generate SOURCE --update ./postman/mocks/NAME` regenerates
     the default handler from the source in place, keeping the existing name,
     port, and scenarios. `--update` still needs the `SOURCE`; it cannot be
     combined with `--output`.
   - `-w <workspaceId>` saves the mock to a cloud workspace *instead of* the
     repository — it writes no local files and requires being logged in. Cannot
     be combined with `--output`, `--force`, or `--update`. Prefer local
     generate + later `push` when you still need `mock run` from a folder.
2. **Run it.** `postman mock run ./postman/mocks/NAME` starts the server and
   prints the bound URL (`... at http://localhost:PORT`). If the port in
   `config.yaml` is taken and `--port` wasn't passed explicitly, it falls back
   to a free OS-assigned port instead of erroring — read the real port off that
   line rather than assuming the configured one. Naming `--port N` explicitly
   makes a taken port a hard error; `--port auto` always picks a free one.
3. **Call it.** Plain `postman request localhost:PORT/route` returns the
   default scenario's response. Two headers can change that per-request, with no
   restart: `x-mock-scenario: <name>` selects a scenario the mock defines
   (valid names live in `config.yaml`); a name the mock doesn't define is not an
   error — it falls back to the default scenario. `x-mock-response-code: <code>`
   filters an endpoint's saved example responses to the one with that status, so
   it only changes anything when that endpoint actually has an example for that
   code — mocks generated from a collection/spec with multiple example statuses
   honor it; the built-in sample mock has one response per route and ignores it.
   A wrong route comes back as `Endpoint not defined`. There's no hot reload: a
   `default.js` edit does nothing until you Ctrl+C the running server and
   `mock run` it again.
4. **Push it, if it needs to leave your machine.**
   `postman mock push ./postman/mocks/NAME` is safe to re-run — `Created` the
   first time, `Updated` after — and records the cloud mapping in
   `.postman/resources.yaml`; commit that change. If a mock server is already
   live for this mock, the push updates what it serves.
5. **Deploy it, for a URL that outlives your terminal.**
   `postman mock deploy CLOUD_ID -s SLUG -y` prints
   `https://SLUG.mock.<team-domain>.postman.dev`. Deployed private by default —
   callers need a Postman API key (`x-api-key`) — add `--public` only when the
   mock should be reachable by anyone with the URL. `--auto-deploy` re-publishes
   the live server automatically whenever the mock changes; even without it, a
   later `push` already updates a live server, so you only re-`deploy` for the
   first URL or after taking the server down.
6. **See who's calling it.** `postman mock get CLOUD_ID` (table or `--json`)
   returns `mockServerId`; feed that into `postman mock log MOCK_SERVER_ID` for
   call entries (filter with `--method` / `--status` / `--path` / `--since` /
   `--until` / `--limit`, or `--json`). An empty log means the URL genuinely
   hasn't been hit — a rejected caller still shows up, recorded with its failing
   status code.
7. **Tear down.**
   - Local: `postman mock delete ./path --yes` — refuses while that mock is
     **running** locally; stop `mock run` first.
   - Cloud: `postman mock delete CLOUD_ID --yes` — refuses while the mock is
     **running locally** *or* **deployed**; stop the local run and take the
     mock server down first.
   Cloud delete doesn't touch `.postman/resources.yaml`; drop that line by hand
   afterward or the repo keeps claiming a mock that's gone.

To point real request/assertion runs at a mock instead of hand-editing
base-URL variables, see the `api-testing` skill's `--use-mock`/`--mock` flags
on `collection run`.

## The two ids that matter

- **Code-mock id** — the `id` in `config.yaml`, and the id that `push` and
  `generate -w` print (often the same value). Use it for `get`, `deploy`,
  `delete`, and `run` by cloud id.
- **`mockServerId`** — a different value from `mock get CLOUD_ID` (table or
  `--json`). Use it for `mock log`, and nothing else.

## Critical Rules

1. **When you're not signed in, every gated cloud command fails closed:**
   `Authentication required. Run postman login or provide --api-key`, exit 1,
   nothing half-done. (Signed in but lacking access fails differently — a
   permission or missing-workspace error.) Whether a command is gated is decided
   by what you pass it, not the verb — `mock get`/`mock run` take either a local
   path (ungated) or a cloud ID (gated); `mock list` is gated only when called
   with no path.
2. **`push` is what moves an existing local mock to the cloud — `-w` at
   `generate` time is optional, not a fork you must choose up front.** A mock
   built as a guest can be pushed and deployed later with no rework. Do not
   assume `generate -w` left a `postman/mocks/NAME/` folder to `run`.
3. **`--public` on `deploy` is the one action here with real exposure** — it
   stands up a server anyone with the URL can hit, with no API key. The default
   (private) is the safe one; confirm intent before adding it.
4. **To change a mock:** refresh it from a source with
   `postman mock generate SOURCE --update PATH`, or edit `default.js` by hand
   and restart `mock run`. Never pass a code-mock id to `mock log` — that
   command takes a `mockServerId`.
5. **`-w`/`--workspace` only exists on `generate`, `list`, `push`, and
   `deploy`.** `get`, `run`, `log`, and `delete` already take a path or an id
   that says where the mock is — there's nothing left for `-w` to resolve on
   those.

## Verification

A mock isn't done because `generate` or `run` exited 0 — hit it with
`postman request` and check the actual status/body, or `mock get CLOUD_ID
--json` for a cloud one, then state whether it ended up local or cloud, and
(if deployed) private or public. For a scenario check, confirm a *valid* name
from `config.yaml` actually changed the response — a typo'd name falls back to
the default, so a 200 alone proves nothing. For a status-code check, use an
endpoint that has an example for that code (not the sample mock). A passing
exit code from `request` is not enough.

View saved version →

---
name: api-monitoring
description: Creates, schedules, and manages Postman Monitors — recurring checks against a live API — triggers ad hoc runs, inspects job/run history to diagnose failures, and hosts self-hosted execution runners for monitors on a private network. Use when the user asks to "set up a monitor," "run this monitor now," "check monitor results," "pause/resume a monitor," or "set up a runner for our internal APIs." Covers `postman monitor` (create, update, delete, list, get, pause, resume, run, jobs, runs) and `postman runner` (start, list, regions).
---

# API Monitoring

## Overview

A Monitor is a recurring, scheduled check against a live API. The CLI now
owns its full lifecycle: `monitor create`/`update`/`delete`/`pause`/`resume`
manage the schedule and configuration, `monitor list`/`get` discover and
inspect existing ones, `monitor run` triggers an ad hoc run, and `monitor
jobs`/`monitor runs` inspect what actually happened during a run. There is
no remaining task here that has to go through the Postman app.

`postman runner` is a separate, infrastructure-level concern: it starts a
self-hosted execution agent so Monitor runs can reach APIs that live behind
a private network Postman's cloud can't reach directly, and it lists the
values (Postman regions or self-hosted runner ids) that `monitor
create`/`update --runner` accepts.

## Creating and scheduling a monitor

`monitor create -c <collectionId>` is the minimum — name defaults to the
linked collection's own name. Workspace comes from `-w`, or falls back to
the workspace named in the local `.postman/resources.yaml` manifest;
without either, creation fails. `--schedule <cron>` plus `--timezone`
(defaults to the host machine's zone) set when it fires; `--runner`
(repeatable) says where from — a Postman region name (`postman runner
regions`) or a self-hosted runner's id (`postman runner list`), and both
can be mixed in the same monitor. `--notify-email` (repeatable) and
`--notification-limit` control failure alerts. The run itself is shaped by
the same options as a collection run — `--retry` (service caps at 2),
`--timeout`, `--delay`, `--strict-ssl`/`--insecure`,
`--follow-redirects`/`--block-redirects`, and dataset iteration via
`--dataset-id`/`--dataset-view-id`/`--iteration-count`/
`--iteration-strategy`. Creation triggers an immediate run by default; pass
`--no-run-now` to skip that.

## Updating, pausing, and deleting

`monitor update <monitorId>` takes the same schedule/runner/notification/
run-option flags as `create`, plus `--clear-notifications` to wipe every
recipient. It cannot change the linked collection or environment — delete
and recreate the monitor instead — and it does not pause or resume; use
`monitor pause`/`monitor resume` for that. `monitor delete <monitorId>`
prompts for confirmation unless `-y`/`--yes` is passed, and is permanent.

## Discovering and inspecting monitors

`monitor list` filters by `-w`/`-c`/`--environment`/`--owner`/`--team`/
`--active`. `--runner <id>` filters to a *self-hosted* runner id (not a
Postman region) and can't be combined with the other filters. Page with
`--limit`/`--cursor`; `--offset` is accepted by the service but silently
ignored, so the CLI rejects it locally rather than returning a page that
looks right but isn't — use `--cursor` from the previous page's response.
`--columns` picks which fields show, `-f`/`--filter` matches on name within
the page already returned (not a server-side search), and `--sort name|active`
orders it. `monitor get <monitorId>` shows one monitor's full configuration.

## Triggering a run

`monitor run <monitorId>` runs an existing Monitor synchronously and prints
the result — useful in CI to get a pass/fail right after a deploy rather
than waiting for the next scheduled tick. `-t/--timeout` (default 15
minutes) caps how long the CLI waits for completion; a timeout hit here is
the CLI giving up on waiting, not the Monitor itself failing. `--async`
submits the run and returns immediately with its job id and Postman URL
instead of waiting at all — reach for this over a long `-t` when the caller
doesn't need the verdict inline. `--json` prints only the verdict as JSON,
for scripting. `-x/--suppress-exit-code` overrides the default
fail-on-failed-run exit code, for a caller that wants to see failures
without breaking a pipeline step.

## Diagnosing a run

`monitor jobs list <monitorId>` lists a monitor's recent jobs; `monitor jobs
get <jobId>` reports one job's terminal state and its per-region run
outcomes — a monitor with runners in multiple regions runs once per region
per job. `monitor runs get <runId>` goes one level deeper: which test
assertions ran during one attempt, which failed, and why. Reach for these
instead of re-running blind after a `-t` timeout, or whenever the task is
explaining *why* a monitor failed rather than just that it did.

## Private (self-hosted) runners

A private runner — the CLI's `runner regions` calls the same thing a
"private-runner" value — is an agent you run inside your own network so
Monitor traffic originates there instead of from Postman's cloud IPs. Reach
for one only when the monitored API sits behind a VPN, firewall, or on-prem
network that Postman's cloud can't reach directly; a public API should just
use a Postman region (`--runner us-east`, etc.) since that needs no
infrastructure of your own to run or maintain.

`runner start --id <id> --key <key>` (from the Postman app) registers a
runner that executes monitor runs from your own infrastructure instead of
Postman's cloud. Extra
flags cover the runner's own networking: `--region eu` for EU residency,
`--proxy`/`--egress-proxy`/`--egress-proxy-authz-url` for outbound routing,
`--ssl-extra-ca-certs` for a private CA, and `--metrics`/`--metrics-port`
for a health-check endpoint. Analytics are sent by default; `--no-report-events`
opts out. `runner list` shows the team's registered self-hosted runners —
feed an id from here into `monitor create/update --runner` or `monitor list
--runner`. `runner regions` lists the Postman-region and private-runner
values valid for `--runner` on `monitor create`/`update`, including a
static IP where one is configured — check here before guessing a region
string.

## Critical Rules

1. **`update` can't move a monitor to a different collection or environment,
   and doesn't pause/resume it.** Delete and recreate for the former; use
   `pause`/`resume` for the latter.
2. **A `monitor run -t` timeout is a wait cap, not a monitor failure.**
   Don't report "the monitor failed" from a timeout without checking
   `monitor jobs get`/`monitor runs get` (or the Postman app) for what the
   run actually did after the CLI gave up waiting — or avoid the wait
   entirely with `--async`.
3. **`--runner` on `monitor create`/`update` takes a region name or a
   self-hosted runner id — check `runner regions`/`runner list` before
   guessing a string,** and don't suggest `runner start` unless the target
   API genuinely isn't reachable from Postman's cloud.
4. **`monitor list --offset` doesn't work — use `--cursor`,** and
   `--runner` there can't be combined with the other filters.
5. **`monitor delete` is permanent.** Confirm intent before passing `-y` to
   skip its prompt.

## Verification

State the monitor/job/run id and the actual pass/fail result or
configuration change, not just that the command exited. For `run`, state
whether it completed synchronously or was submitted `--async` (a job id is
not yet a verdict — resolve it with `monitor jobs get` before reporting a
result). If a self-hosted runner was started, confirm it registered (the
Postman app, or `runner list`, shows it as connected) before assuming
monitor runs will route through it.

View saved version →

---
name: api-testing
description: Runs tests against an API from the command line — a single ad-hoc request, a full collection of pm.test assertions, or matching real captured app traffic against a collection contract. Use when the user asks to "test this endpoint," "run this collection," "check the API still works," or "verify my app's requests match the contract." Covers `postman request`, `postman collection run`, and `postman application test`. Depends on bootstrap when the target is a cloud collection or workspace-bound environment; a bare URL or local collection needs nothing from bootstrap.
---

# API Testing

## Overview

Three tools, matched to what already exists:

| Have | Use |
| --- | --- |
| Just a URL to check, with no saved request | `postman request` |
| A request already saved in a collection | `postman collection run <collection-path> -i <request-id-name-or-path>` |
| A collection with `pm.test` assertions saved in it | `postman collection run` |
| A real app (browser flow, CLI, service) whose traffic should match a collection's contract | `postman application test` |

Don't reach for the heavier tool when the lighter one already answers the
question — a one-off endpoint check doesn't need a collection, and a
collection run doesn't need Playwright.

## `postman request` — over curl, not instead of testing

A single request with Postman's resolution built in: `-e` resolves
`{{variables}}` from an environment file the same way a collection run
would, `--auth-*` flags cover basic/bearer/digest/oauth/aws/etc. without
hand-building headers, and `--retry`/`--timeout` handle flaky endpoints.
`--script-post-request` can run `pm.test(...)` assertions inline — the exit
code counts *failed assertions*, not just HTTP status, so a 200 with a
failing test still exits nonzero. Useful for a quick check or a CI health
check; not the place to accumulate assertions that should outlive one
command — those belong saved in a collection.

Before constructing a URL, headers, auth, and body on the command line, look
for a matching `*.request.yaml` under `postman/collections/`. If it exists,
execute the saved request through its collection:

```bash
postman collection run "postman/collections/Orders API" -i "create order"
```

Do not copy the saved YAML fields into `postman request`; that bypasses the
collection's inherited variables, auth, scripts, and maintained payload. The
`postman request` positional target is a URL, not a `.request.yaml` path. When
there is no saved request but its body already lives in a separate file, keep
the file as the source of truth with `--body @path/to/payload.json` instead of
inlining its contents.

## `collection run` — the assertion suite

Debugging a request's behavior during a run (why a `pm.test` failed, what a
request actually sends) means reading the request's own YAML — see the
`collection-schema-v3` skill for that file format before assuming a field's
shape.

Runs every request in a collection (or a subset via `-i`, repeatable),
executing whatever `pm.test` scripts are already saved in it.
`-d`/`--iteration-data` (or the beta `--iteration-data-dataset` +
`--iteration-data-view` pair) drives data-driven runs across a CSV/JSON
file or a Postman Dataset. `-r junit,html` for CI-consumable reports.
`--use-mock`/`--mock` redirects the run at a mock instead of a real backend
(see the `api-mocking` skill) — reach for this to test request/assertion
logic without depending on a live service.

## `application test` — contract-matching real traffic

This doesn't send its own requests. It runs your existing test command
(`--command "npx playwright test"`, or config-driven via
`postman.config.cjs` targets), captures the network traffic that command
generates, and matches/asserts it against your Postman collections —
answering "did my app's actual calls conform to the contract," not "does
this endpoint respond correctly." `--capture-only` skips the matching step
entirely and just exports what was captured as a new v3 collection,
organized by host — a way to bootstrap a collection from real traffic
rather than authoring one from scratch. Results upload to Postman
automatically after each run; `--report-events=false` skips that for a run
that shouldn't be recorded.

## Critical Rules

1. **Don't reach for `application test` for something a plain
   `collection run` covers.** It exists specifically for matching *captured*
   app traffic (via Playwright or similar), not for driving requests itself.
2. **`postman request`'s exit code reflects failed `pm.test` assertions, not
   HTTP status alone.** A nonzero exit on a 200 response usually means a
   post-request script assertion failed, not a network problem.
3. **Assertions meant to be reused belong in the collection, not on the
   command line.** A `--script-post-request` test on `collection run` runs
   once and leaves nothing for the next person; save it as a `pm.test` in
   the request instead.
4. **`--use-mock` is the way to test without a live backend** — prefer it
   over standing up ad hoc fakes or skipping tests that need a dependency.
5. **Reuse a saved request instead of reconstructing it.** If a matching v3
   request exists, use `collection run <collection-path> -i <request>`; reserve
   `postman request` for genuinely ad-hoc requests.

## Verification

State the actual result (pass/fail counts, exit code), not just that the
command ran. For `application test`, state whether it ran in match mode or
`--capture-only` — they answer different questions and shouldn't be
reported the same way.

View saved version →

---
name: bootstrap
description: Resolves the Postman CLI, authenticates when the task needs it, and manages the filesystem/workspace binding for a repository. Use when the user asks to set up Postman, enable filesystem workflows, authenticate, initialize, import, connect, pull, push, sync, or share a workspace — and before skills that need a linked workspace, only when the CLI, linked workspace, or spec path has not already been confirmed.
---

# Bootstrap Postman for This Repo

## Overview

One-time and idempotent: every other Postman skill in this plugin reads the
values this one records and re-derives none of them. Finding an existing
`postman/` tree or an OpenAPI file is a signal to inspect, not to assume this
repo is already set up.

## Rules

- Make ad-hoc HTTP calls with `postman request`, never `curl` or another
  client. If the request already exists in a collection, preserve its saved
  auth, variables, scripts, and payload by using `postman collection run
  <collection-path> -i <request>` instead of reconstructing it on the command
  line; see `api-testing`.
- Never invent a subcommand or a flag. Run `-h` first and believe it.
- Lint specs with `postman spec lint`, never `postman api …` — the API Builder
  is deprecated in v12+ and the CLI prints no warning.
- Local commands need no login; only commands that reach the Postman
  workspace do. Don't force a login the task doesn't need.
- A missing `postman` binary means install it. Route to `postman-mcp-server`
  only after an install has been attempted and actually failed.
- Never fabricate a workspace id, spec path, or collections directory. Report
  the gap and stop.
- Never echo an API key or session token into output, logs, or summaries.
- "Present" is not "current": check the version and existing links before
  setting anything up.
- Wire up an existing repo only. Never scaffold a new API or a starter spec.
- Write no host-specific paths — the same `skills/` directory loads on every
  route.
- Do not use `init` or `workspace create` to share or import a workspace that
  already exists. Choose the direction of sync from the lifecycle table below.

## Ask the CLI: `-h`

The CLI is self-describing at different levels. Walk down only as far as the
question needs:

```bash
postman -h                      # resources: collection, spec, mock, monitor, workspace, api, flows…
postman <resource> -h           # that resource's actions
postman <resource> <action> -h  # real flags, defaults, and worked `Eg.` lines
```

Read the third level before writing any command that carries a flag — it is the
only place defaults are stated, and a wrong default fails silently. Live output
is authoritative over any summary, including this file. There is also no single
verb for "is the workspace linked and synced": run `postman workspace -h` and
pick from what it prints.

---

# Process

Three steps, in order. Stop at the first that fails and report which one.

## 1. Resolve the CLI

### 1.1 Check what is already there

**Present, and at which version?**

```bash
command -v postman && postman --version
```

**Current?** Never blocking — no network is a normal answer. But don't call a
feature missing without having made this comparison.

```bash
npm view postman-cli version
```

### 1.2 Install only if missing

**Preferred — npm, all platforms:**

```bash
npm install -g postman-cli
```

**Windows, or avoiding a global npm install:** use the platform installers in
[reference/cli_installation.md](reference/cli_installation.md). Every route puts
`postman` on `PATH`.

**Updating a copy that already exists:** use the same route that installed it.
curl-installed binaries don't take `npm install -g` cleanly.

**If every route fails:** name what blocked you — no Node, no shell, no write
access, or a hosted session that cannot install — then hand off to the
`postman-mcp-server` skill. An attempted install that actually failed is the
only thing that qualifies.

## 2. Establish the filesystem and workspace bindings

### 2.1 Authenticate only if this step needs it

Local commands need no login, and `postman init` is among them — its own help
says *"No authentication, and safe in CI."* Skip this entirely unless the
command you're about to run pulls or pushes an existing workspace, or shares
one with a team.

**With an API key — preferred, non-interactive:**

```bash
[ -n "$POSTMAN_API_KEY" ] && postman login --with-api-key "$POSTMAN_API_KEY"
```

**Browser flow, when that variable is unset:**

```bash
postman login
```

**Never echo the key or token.** Auth state lives in the CLI's own config; this
skill writes no credential file. Report that authentication succeeded, nothing
more.

### 2.2 Inspect both sides before choosing a command

Read `.postman/resources.yaml` for `localResources` and `workspace.id`, and
inspect the local `postman/` tree. When the user names an existing workspace or
asks to import, sync, or share one, use `workspace list --json` and `workspace
get <id> --elements --json` to confirm the workspace side. Never create a
second workspace merely because this repository is not connected yet.

Prefer filesystem-first work: materialize an existing workspace with
`workspace pull <id>`, or initialize local files with `postman init --no-cloud`
when no workspace exists. Then inspect, edit, diff, and validate the
version-controlled files before any push.

| Existing state and intent | Use | Why |
| --- | --- | --- |
| No workspace exists; start locally | `postman init --json --no-cloud` | Creates the git-native filesystem without requiring login. |
| No workspace exists; create and bind one | `postman workspace create --visibility <value>` or the explicit init creation path | Creation is the requested lifecycle event. |
| Workspace exists; enable filesystem work | `postman workspace pull <workspace-id>` | Connects the workspace to the repository and materializes its entities under `postman/`. |
| Workspace exists; record only the Git binding | `postman workspace connect-git <workspace-id> [path]` | Binds without downloading its contents. |
| Bound workspace; the workspace is authoritative | `postman workspace pull` | Refreshes local files from the connected workspace. |
| Bound workspace; local files are authoritative | `postman workspace diff --push-strategy default`, then `postman workspace push` | Previews and publishes creates/updates without deleting unmatched workspace entities. |
| “Share this existing workspace with my team” and it is already team-accessible | Diff, then `postman workspace push` | Publishes local contents to the existing workspace; `create` would make a duplicate. |

If “share” also requires changing a personal workspace's visibility or team
permissions, inspect its metadata first. `push` synchronizes entities; it does
not change access control. Do not create a replacement to work around a missing
metadata-update command.

`workspace diff` is read-only. Match its push strategy to the intended push.
`--push-strategy force-sync` can delete workspace entities absent locally, so use it
only when the user explicitly requests mirroring and approves the shown
deletions. Do not add `-y` merely to bypass a prompt.

### 2.3 Initialize only when there is no workspace to pull

`postman init --json` is the agent-facing form. It writes
`.postman/resources.yaml` and scaffolds `postman/` for specs, collections and
environments. Downstream skills read that file and nothing else.

```bash
postman init --json --no-cloud               # local only, no workspace
postman init --json --visibility personal    # also create and bind a workspace
```

Use `--visibility` only when a new workspace is actually wanted. If the
workspace already exists, use `pull` to enable the filesystem workflow;
use `push` only when publishing local changes to an already-bound workspace.

**The workspace step is interactive** without `--no-cloud` or `--visibility`.

**Read the payload, not stderr.** Take `bindings` and `exitCode` from the JSON.
Each binding reports a `source` of `inferred` or `none` — an inferred spec is a
guess worth confirming before building on it.

**Exit codes that are not failures:** 2 means several specs could be
authoritative, so re-run with `--spec <path>`. 5 means the local files were
written but the requested workspace was not created — it does *not* mean re-run.

## 3. Verify and report

### 3.1 Checkpoints

- `postman --version` returned a real version.
- Auth is confirmed, or established as not required for this task.
- `.postman/resources.yaml` names a spec or a collections directory.
- `workspace.id` is set, or the run was deliberately local-only — `--no-cloud`
  leaves it empty and still exits 0, which is a pass, not a gap.
- After `pull`, expected workspace entities exist under `postman/`. After
  `push`, report created/updated entities and conflicts; do not claim a
  workspace is shared unless its access level permits the intended teammates.

"The CLI is installed" is not the bar, and a loaded skill configures nothing.

### 3.2 Summary format

```md
## Postman bootstrap
- **CLI**: <version> (latest: <version> | not checked)
- **Auth**: <api-key | browser | not required for this task>
- **Workspace**: <id | none — local only>
- **Spec path**: <path (inferred | explicit) | none — user must create>
- **Collections dir**: <path | none — user must create>
```

---

# Reference Files

- `collection-schema-v3` skill — read when inspecting or writing the
  collection files this skill resolves.
- [CLI Installation](reference/cli_installation.md) — read for install, update
  and uninstall commands per platform.

Referenced files: 1

View saved version →

---
name: ci-integration
description: Common CI integrations that can added as independent pass/fail gates. Use when the user asks to "add Postman to CI," "run this collection on every PR," "fail the build on a governance violation," or "push to the postman cloud workspace after merge to main", "add some api related operation in my Github actions". 
---

# CI Integration

## Overview
These are some common workflows that one can add in their CI pipeline leveraging postman cli.

## Run a collection — a gated pipeline step

`postman collection run <path/id>` exits nonzero on a failed `pm.test`
assertion, which is what makes it a usable gate — see `api-testing` for how
that exit code actually gets set. What's CI-specific: `-r junit,html` (or
`--reporter-*-export`) writes a report your CI provider can surface as
build artifacts or test annotations, instead of leaving the result buried in
a log. `--bail` stops the run early on the first failure when a fast signal
matters more than a full report.

## Lint — pick the target that matches the gate you want

Three verbs look interchangeable and aren't — only two of them apply your
organization's governance rules, and the CLI's own `-h` output is where that
becomes visible (no assumption below goes further than what it printed):

| Want to check | Command | Applies org governance? |
| --- | --- | --- |
| One spec against your rules | `spec lint <spec> --workspace-id <id> -f error` | Yes, via `--workspace-id` |
| One collection's structure/style | `collection lint <path> -f error` | **No** — this verb takes no `--workspace-id` at all |
| The whole workspace: every entity plus `.postman/resources.yaml` | `workspace lint --workspace-id <id> -f error` | Yes |

`collection lint` is a schema/style check only — running it and reporting
"governance passed" overstates what it did. If the ask is "does this
collection violate our rules," `workspace lint` is the one that actually
answers it (and covers every collection in the repo in one pass); reach for
bare `collection lint` only when there's no workspace to fetch rules from
yet.

## Push to workspace — only after merge

`postman workspace push -y` is the one command in this skill that changes
shared cloud state, so it belongs behind a merge-to-main trigger, not a PR
trigger. `-y` skips confirmation prompts a non-interactive job can't answer.
Leave `--no-prepare` off — the default prepare step is what assigns real IDs
to entities that are new since the last push; skipping it because a run
felt slow trades a few seconds for a push that silently fails to create
anything new.

`--push-strategy force-sync` mirrors the whole workspace, deleting any cloud
entity with no local counterpart — genuinely destructive, and not the
default for a reason. See Critical Rules before adding it to a merge job.

## AI readiness threshold

`collection ai-readiness <path> --min-score <n>` and its spec-side
counterpart `spec ai-readiness <path> --min-score <n>` (see `ai-readiness`
skill) are a fourth, separate gate — they score AI-agent consumability, not
test results or governance/structural style. Keep either in its own step:
folding it into the same step as `run` or one of the `lint` verbs above
hides which kind of check actually failed when the job goes red. Pick the
verb that matches what's checked into the repo — `collection ai-readiness`
for a git-synced collection, `spec ai-readiness` for an OpenAPI spec with no
collection generated from it yet.

```yaml
- run: postman collection ai-readiness ./postman/collections/My\ API --min-score 70
```

## Critical Rules

1. **Never collapse `run`, `lint`, and `ai-readiness` into one step, and
   never pass `-x`/`--suppress-exit-code` to a CI run.** One combined exit
   code hides which check broke; a suppressed one hides that anything broke
   at all.
2. **Gate `workspace push` to the merge event, never a PR event.** Everything
   else in this skill is read-only against the cloud; this is the one
   command that writes to it, so a PR-triggered push ships an unmerged
   branch's entities to the shared workspace.
3. **`--push-strategy force-sync` deletes cloud entities absent locally.**
   Only add it to a job whose explicit job is mirroring the workspace exactly,
   with that intent confirmed — never as the default merge step, where the
   default (create/update-only) strategy is the safe choice.
4. **Authenticate once, non-interactively:**
   `postman login --with-api-key "$POSTMAN_API_KEY"`, reading the key from
   the CI provider's secret store. Don't reach for `collection run`'s
   `--postman-api-key` as the general answer — it's US-region only — and
   `spec lint`/`workspace push` don't take it at all.

   ```yaml
   # WRONG — key committed in plain text, and scoped to one command anyway
   - run: postman collection run api.json --postman-api-key PMAK-abc123...

   # CORRECT — one non-interactive login, key from the provider's secret store
   - run: postman login --with-api-key "$POSTMAN_API_KEY"
   - run: postman collection run api.json
   - run: postman spec lint spec.yaml --workspace-id $WS -f error
   ```
5. **Never `newman run` in place of `postman collection run`.** The CLI is
   the supported runner every other skill here assumes; Newman forks the
   toolchain and skips whatever reporting/governance depends on the CLI
   specifically.

## Verification

State each gate that ran and its individual result — not "CI passed," but
which check ran, what it checked (governance vs. structure per the Lint
table above, or AI-agent consumability for `ai-readiness`), and its exit
code. If `workspace push` ran, confirm it was triggered by the merge event
and not a PR event, state which push strategy was used, and report
`Created`/`Updated` per entity rather than just "push succeeded." Confirm
no secret value appears literally in the committed workflow file.

## Reference

- `api-testing` skill — `collection run`'s exit-code semantics and reporter
  flags in full.
- `collection-schema-v3` skill — what `workspace push` is actually pushing.
- `bootstrap` skill — CLI resolution, workspace linking, `.postman/resources.yaml`.
- `ai-readiness` skill — `collection ai-readiness`, `spec ai-readiness`, and
  their `--min-score` gate.

View saved version →

---
name: collection-schema-v3
description: The reference for the git-native v3 collection file format — one YAML file per request/folder/example under postman/collections/, plus postman/environments/. Read before writing, editing, or generating any file in either directory by hand, or before debugging a `collection lint` failure. Covers the HTTP request/example/definition schema, environment schema, and the YAML/naming rules that make files parse — GraphQL, gRPC, WebSocket, Socket.IO, MQTT, MCP, and LLM request schemas are non-HTTP protocols and live in reference/other_protocols.md, read only when a collection actually uses one.
---

# Collection Schema (v3, Git-Native)

## Overview

A v3 collection is a directory tree under `postman/collections/`, one file
per entity — every request, every folder's metadata, every saved example is
its own file. There is no single collection.json to open and edit; the
directory structure itself *is* the collection.

```text
postman/collections/
  bookstore api/
    .resources/
      definition.yaml (optional)
      get all books.resources/
        examples/
          200 OK.example.yaml
          400 Bad Request.example.yaml
          500 Internal Server Error.example.yaml
    get all books.request.yaml
    get-book-by-id.request.yaml
    add new book.request.yaml
    authentication/
      .resources/
        definition.yaml (optional)
      signup.request.yaml
      login.request.yaml
```

- Every folder under `postman/collections/` is a collection; it can contain
  subfolders and requests.
- A folder or collection can have a `.resources/` directory — an optional
  metadata directory for that scope. `.resources/definition.yaml` holds the
  collection/folder's own metadata; request examples live under
  `.resources/<request-name>.resources/examples/`.
- Never place a request file inside a `.resources/` directory — those are
  metadata-only.

## Definition file (`.resources/definition.yaml`)

Optional metadata for a collection or folder:

- `$kind: "collection"` — required, even for a folder's definition.
- `name` — optional, defaults to the filesystem folder name.
- `description` — optional.
- `variables` — array of `{key, value, description?, disabled?}`. `value`
  must be a string; `disabled` a boolean.
- `auth` — a single auth object `{type, credentials: [{key, value}, ...]}`,
  or an array for multiAuth: `[{id, name, type, credentials, rules?}, ...]`.
- `scripts` — array of `{type, code, language: "text/javascript"}`. `type`
  is one of `http:beforeRequest`, `http:afterResponse`,
  `graphql:beforeQuery`, `graphql:afterResponse`, `grpc:beforeInvoke`,
  `grpc:onIncomingMessage`, `grpc:afterResponse`.
- `order` — number, used for folder ordering.

## HTTP request (`*.request.yaml`)

- `$kind: "http-request"` — required.
- `name` — optional (see naming rules below for when to include it).
- `order` — number; only used for relative comparison, so space values out
  (e.g. multiples of 1000) rather than packing them tight — a later
  insertion between two requests shouldn't force renumbering every sibling.
- `url` — string, with `{{varName}}` variable syntax.
- `method` — `GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS`.
- `headers` — array of `{key, value, description?, disabled?}`.
- `queryParams` — array of `{key, value, description?, disabled?}`.
- `pathVariables` — array of `{key, value, description?}`.
- `body` — `{type, content}`; `type` required whenever `body` is present.
  - Types: `json`, `formdata`, `urlencoded`, `text`, `xml`, `html`,
    `javascript`, `file`, `none`.
  - `json`/`text`/`xml`/`html`/`javascript`: `content` is a string.
  - `formdata`: `content` is an array of
    `{key, type: "text"|"file", value or src, contentType?, description?}`.
  - `urlencoded`: `content` is an array of `{key, value, description?}`.
- `auth` — `{type, credentials}`.
- `settings` —
  `{protocolVersion?, strictSSL?, followRedirects?, maxRedirects?, disabledSystemHeaders?}`.
- `scripts` — array of `{type: "beforeRequest"|"afterResponse", code, language: "text/javascript"}`.
- `examples` — optional, a relative path to the examples directory, e.g.
  `./.resources/<request-name>.resources/examples/`.

## HTTP example (`*.example.yaml`)

- `$kind: "http-example"` — required.
- `name` — optional.
- `request: {url, method}`.
- `response: {statusCode, statusText, headers: [{key, value}], body: {type, content}}`.
- `order` — optional.

Saved examples are what `collection ai-readiness` checks for — a request
with no examples scores worse for agent consumption even if perfectly
valid structurally.

## Environments (`postman/environments/*.environment.yaml`)

Environment files are v3 YAML but are not collection entities: they do not use
`$kind`. Before creating or editing one by hand, read
[reference/environment.md](reference/environment.md) for the schema, secret
handling, CLI-first edit commands, and a linted example.

## YAML rules

Invalid YAML breaks parsing silently in confusing ways — when in doubt,
single-quote it:

1. Single-quote any value containing `{{variables}}`:
   `url: '{{base_url}}/users'` — never leave it unquoted.
2. Single-quote values containing `: # & * ! [ ] { } > |`, e.g.
   `name: 'Health check: v2'`.
3. Multi-line content (JSON bodies, scripts, queries) uses a `|-` block
   scalar:
   ```yaml
   body:
     type: json
     content: |-
       {
         "name": "example"
       }
   ```
4. Quote strings that resemble booleans/numbers when a string is intended:
   `value: "true"`, `value: "123"`.
5. `order` must be a bare number, never quoted: `order: 1000`.
6. Single-quote file paths and use forward slashes only:
   `examples: './.resources/name.resources/examples'`.

## Naming rules

- `<request-name>` (the filename stem before `.request.yaml`) must not
  contain `/ \ : * ? " < > |` — sanitize to `-`.
- Include `name` in the file only when it differs from `<request-name>`
  (e.g. `name: 'Health/check'` inside `Health-check.request.yaml`, since the
  filename itself can't hold the `/`).
- Filenames must be unique, case-insensitively, per directory.

## Worked example: "bookstore api"

`postman/collections/bookstore api/get all books.request.yaml`
```yaml
$kind: http-request
method: GET
url: '{{base_url}}/books'
order: 1000
```

`postman/collections/bookstore api/get-book-by-id.request.yaml`
```yaml
$kind: http-request
name: 'get book by :id'
method: GET
url: '{{base_url}}/books/:id'
order: 2000
pathVariables:
  - key: id
    value: '1'
```

`postman/collections/bookstore api/add new book.request.yaml`
```yaml
$kind: http-request
method: POST
url: '{{base_url}}/books'
order: 3000
headers:
  - key: Content-Type
    value: application/json
body:
  type: json
  content: |-
    {
      "title": "Example Book",
      "author": "Jane Doe"
    }
```

`postman/collections/bookstore api/.resources/definition.yaml`
```yaml
$kind: collection
name: Bookstore API
variables:
  - key: base_url
    value: 'https://api.bookstore.com/v1'
```

## Critical Rules

1. **Every entity is its own file — there's no single collection.json to
   open.** A request, its parent folder's metadata, and its saved examples
   are three separate files, not sections of one document.
2. **Unquoted `{{variables}}` or special characters are the most common way
   a hand-written file fails to parse.** Single-quote per the YAML rules
   above rather than debugging a cryptic lint error after the fact.
3. **`order` is relative, not an index.** Don't renumber every sibling file
   to insert one request — leave headroom (spacing of 1000) from the start.
4. **This file covers HTTP only.** A collection using GraphQL, gRPC,
   WebSocket, Socket.IO, MQTT, MCP, or LLM requests needs
   [reference/other_protocols.md](reference/other_protocols.md) — don't
   guess those schemas from the HTTP shape above, they diverge in real ways
   (e.g. gRPC's `methodDescriptor`, LLM's `userPrompts`/`systemPrompts`).

## Reference

- [Other request protocols](reference/other_protocols.md) — GraphQL, gRPC,
  WebSocket, Socket.IO, MQTT, MCP, and LLM request schemas.
- [Environment schema](reference/environment.md) — v3 environment filenames,
  fields, variable types, safe editing commands, and validation.

Referenced files: 2

View saved version →

---
name: flows
description: Runs, deploys, and debugs Postman Flows from the command line — executing a flow file locally, triggering a deployed flow over its webhook, deploying one so it becomes callable, and tracing a failed run to the block that broke. Use when the user names a flow and an action ("run the Checkout flow", "deploy this flow", "why did that flow run fail", "what flows do I have"). Covers `postman flows list`, `run`, `trigger`, `deploy`, `update`, `list-runs`, and `get-run`.
---

# Postman Flows

## Overview

Listing flows, running them, deploying them so they become callable, and
tracing a failed run to the block that caused it — all through
`postman flows`.

## Core knowledge

A flow is a graph of blocks, not a script. That single fact drives the rest of
this skill: a flow has two independent execution paths, and its HTTP response
describes one block rather than the whole graph, so debugging takes a
different command than running.

### Local file vs deployed artifact

`run` and `trigger` are not two ways to execute one flow. Postman Flows has
two Native Git modes, and they are isolated from each other:

- **Cloud View** (the default) syncs flows to Postman Cloud, which is what
  makes them shareable and **deployable** — so Cloud View is the only side
  `deploy`, `trigger`, `update`, `list-runs` and `get-run` ever address.
- **Local View** stores flows as JSON in a local Git repo, updated as they are
  edited. Those flows **cannot be shared or deployed**, have no snapshots, and
  are isolated from the flows in Cloud View.

| | `flows run <path>` | `flows trigger <flowId>` |
| --- | --- | --- |
| Executes | a flow JSON file on this machine | the cloud-deployed flow, via its webhook |
| Returns | status, output, test results, exit code | Run ID + HTTP status + response body |
| Observability | own stdout, `--output`, `--reporters` | `get-run`, per block |
| Environment file | `-e/--environment` | not supported |

`run` exits nonzero on failure, which is what lets a CI job gate on it.
`trigger` goes through the real webhook URL, so it exercises the deployed path
end-to-end — auth and trigger configuration included — and registers a cloud
run that `get-run` can explain block by block.

`postman init` scaffolds `postman/flows/`, and Postman's `flows run` examples
use that path. Note what puts files there: the Git-connected Flows experience
is **desktop-app only**, so `postman/flows/*.json` is written by the desktop
app's Local View, not by the CLI — `workspace push`/`pull` carry no flows
handling whatever else they sync. Don't tell a user to `workspace pull` to
obtain a flow file.

### What deploying buys, and what it requires

Deploying puts the flow in Postman's cloud and attaches an HTTP trigger, which
is what makes it reachable by schedules, webhooks, third-party apps, and other
APIs — the flow stops being something a human opens and becomes callable
infrastructure.

Three preconditions sit outside the CLI, so no flag or retry satisfies them:
the flow must be in Cloud View, its Start block must be configured with an API
request trigger, and its canvas must have a Response block. Check these before
re-running a failed deploy with different arguments.

`--path` is a suffix appended to a generated base URL, not a full URL.

### Inputs: `-i` versus a scenario

A scenario is a named input set stored **in the flow definition**, generated
when someone adds an input to the Start block. Because it travels with the
flow, `-s "Staging"` is reproducible across invocations and across people,
where `-i key=value` is per-invocation. Start-block inputs can be declared
secret, which is what `--show-secrets` unmasks in dry-run output.

Precedence: `-s` supplies payload, headers, and query; `--headers` and
`--query` override it; `-i`/`-f` override its values.

### Identifiers

`flows list` is the only way to turn a flow name into an id —
`.postman/resources.yaml` maps collections to cloud ids but has no flows
section, so there is nothing local to read. Both `list` and `list-runs`
**require** `-w/--workspace`; take that id from `workspace.id` in
`.postman/resources.yaml`, which `bootstrap` records.

Run IDs have no single documented shape (`session-abc123` and `main/1a123ab1`
both appear in Postman's own material). Use whatever `trigger` or `list-runs`
printed, verbatim, and apply the same rule to flow ids.

### Plan and permission gating

`flows run` is documented as Enterprise-only, and the cloud subcommands need
`postman login`. `Access denied. Please check your permissions for the
specified resource.` on *every* workspace is a credential-scope or plan
signal, not a wrong-workspace signal — and never means the workspace has no
flows.

## Deploying: propose, confirm, then verify

Deploy is the one multi-phase workflow here, because it is mutating and
because its result is only half-useful without the follow-up check.

1. **Resolve the id.** `flows list --workspace <id> --filter "Checkout"`. On
   multiple matches, show name + id + last-updated and let the user pick.
2. **Propose the path.** Derive it from the flow name — "Checkout" →
   `/checkout` — so the user is confirming a concrete value rather than
   answering an open question. Raise `--auth` here if the trigger will be
   reachable by anyone who learns the URL.
3. **Confirm, then run** `flows deploy <flowId> --path /checkout`.
4. **Report the Trigger URL and whether the trigger is enabled.** A deploy can
   land with the trigger off, which looks identical to a broken deploy at call
   time. If it is off, offer `flows update <flowId> --trigger on`.

When the deploy existed only so the flow could be run, trigger it in the same
turn and report the Run ID — deploy-then-trigger is one job.

## Running and triggering

Show the command before running it, and map the request onto flags: inputs to
`-i`, a payload file to `-f`, query to `-q`, headers to `--headers`, a named
scenario to `-s`.

```bash
postman flows run postman/flows/checkout.json -i amount=4200
postman flows trigger <flowId> -i amount=4200
```

`run` is documented as Enterprise-only, so check the plan before building a
workflow on the local path. Where the flow is already in Cloud View, `trigger`
covers the gap; a Local View flow has no such fallback, since it cannot be
deployed.

`-n/--dry-run` on `trigger` prints the resolved URL and payload without
sending — worth reaching for when a flow writes to real systems, since a
trigger is not a read-only probe. For CI, `--output json` and `--reporters
html` persist results, and `--workspace` is required if the flow contains
connector blocks (it fails at the block, not at startup).

Report the Run ID on every trigger, including successes; it is the only handle
on the run afterwards.

Two failures are recoverable rather than terminal, and both recover through a
confirmed mutation. A 404 hinting `To deploy it, run: postman flows deploy`
means the flow exists but was never deployed — offer the deploy above, then
re-trigger. A disabled-trigger error means it is deployed but not accepting
calls — offer `flows update <flowId> --trigger on`, then trigger.

## Debugging a run

A trigger's response body is the Response block's output. A flow can answer
200 with a failed block upstream, and a 500 says nothing about which block
produced it — so read the run, not the response.

```bash
postman flows list-runs --workspace <id> --flow <flowId> --range 3d
postman flows get-run --run-id <runId> --logs
```

`list-runs` recovers a Run ID nobody wrote down; its `--range` defaults to
`1h`, so widen it before concluding a run is missing. Start `get-run` without
`--logs` and add them when the summary does not explain the failure;
`--filter` narrows to a block-id prefix.

Report the failing block, the reason, and the run status:

```
Run session-abc123 — failed
  Failing block: "HTTP Request (Get Orders)"
  Reason:        downstream returned 504 after 10s timeout
  Status:        error
```

## Critical Rules

1. **Resolve ids, never infer them.** A name is not an id, and no id format is
   documented well enough to validate against. Ambiguous name → present
   candidates and ask.
2. **`deploy` and `update` need explicit confirmation.** They change what the
   flow does for every caller: a deploy exposes a trigger path, `--trigger
   on|off` starts or stops accepting calls, and `--auth off` removes
   authentication from a live trigger.
3. **Report the failing block, not the log.** `--logs` output is input to your
   analysis; the user needs the block, the reason, and the status.
4. **Surface CLI errors verbatim** and read them literally. "Flow file not
   found", a required-option error, and "Access denied" have three different
   fixes, and only the last is about permissions.
5. **A missing or unauthenticated CLI is `bootstrap`'s job** — route there
   rather than improvising an install or a second login.

## Anti-patterns

1. **Don't substitute `run` for `trigger` when a flow isn't deployed.** A
   green local run says nothing about the deployed path a caller hits, and a
   Local View flow cannot be deployed at all.
2. **Don't hunt for a different workspace id when access is denied across
   every workspace you try.** A blanket denial points at the credential's
   scope or the plan, not at the id.
3. **Don't pass `-x/--suppress-exit-code` in CI.** It makes a failed flow
   report success to the pipeline, which removes the only thing gating it.
4. **Don't put reusable inputs on the command line.** A payload that matters
   more than once belongs in a Start-block scenario, where it travels with the
   flow.

## Reference

- [Flows CLI flags](reference/flow_cli_flags.md) — full flag tables per
  subcommand, the BETA dataset-iteration flags, and the short-flag collisions
  between subcommands. Read before composing a command with flags not shown
  above.
- `bootstrap` skill — CLI install, login, and the workspace id these commands
  require.
- `api-discovery` skill — `postman search flows` finds a flow by text across
  Postman, a different dataset from `flows list`'s workspace enumeration.

Referenced files: 1

View saved version →

---
name: performance-testing
description: Load-tests a collection with concurrent virtual users, a chosen load profile, and pass/fail thresholds on latency or error rate — run locally or on Postman's cloud runners. Use when the user asks to "load test this API," "run a performance test," "check how this holds up under load," or "benchmark this collection." Covers `postman performance run`. This generates real traffic against a real target — confirm the target and scale before running, the same way any action with effects outside this session gets confirmed.
---

# Performance Testing

## Overview

`performance run <collectionId>` is not `collection run` with more
iterations — it's a dedicated load-test mode: many virtual users hitting the
collection concurrently for a set duration, shaped by a load profile, scored
against thresholds you define, on infrastructure you choose. The collection
under test is authored the normal way — see the `collection-schema-v3` skill
if it needs edits before the load test is meaningful (e.g. an assertion
that would fail every VU's request identically).

## Core knowledge

- **Load profile is what you're actually testing.** `fixed` holds steady
  concurrency (does this hold up at N users, sustained); `ramp-up` increases
  gradually (where does it start to degrade); `spike` bursts suddenly (does
  a sudden surge break it); `peak` sustains near-maximum load (does it
  survive staying there). Pick based on the failure mode being probed, not
  by default.
- **`--runner` chooses where load originates.** `local` runs from the
  current machine/CI runner — bounded by its own resources, fine for
  internal or low-scale targets. `postman-cloud` runs from Postman's
  infrastructure — needed for realistic external-scale load, or once local
  resources would cap the achievable VU count. `postman-cloud-static-ip`
  is the same, from a static-IP range — needed when the target allowlists
  by IP.
- **`--pass-if "less_than(p95, 500)"` turns a load test into a gate.**
  Metrics: `avg`, `p90`, `p95`, `p99`, `error_rate`, `rps`. Checked after the
  run completes, not enforced live — a bad configuration still generates its
  full load before the gate fails.
- **`--use-mock` points the test at a mock instead of a real backend** — for
  load-testing collection/script logic itself, or to baseline mock-only
  latency and isolate app/network slowness from what the mock adds.
- **`--setup-collection`/`--teardown-collection`** (cloud runner only) run
  once before/after the whole test — for provisioning or cleanup, not
  per-iteration setup.
- **`--dataset-id`/`--dataset-view-id`** drive iteration data from a Postman
  Dataset instead of a flat `--data-file`; `--dataset-distribution` controls
  whether rows are spread round-robin, fixed, or randomly across VUs.

## Critical Rules

1. **Running this against a real, non-mock backend generates real load with
   real consequences — confirm the target, VU count, and duration with the
   user before running,** the same way any action with effects outside this
   session gets confirmed. Default to a low `--vu-count` and short
   `--duration` for a first run against anything live, or point it at a mock
   (`--use-mock`) when the goal is testing the collection, not the backend.
2. **A `--pass-if` gate doesn't stop the load early.** The full VU count and
   duration run regardless of whether the threshold will ultimately pass —
   plan for that cost, don't assume a failing gate means less traffic was
   sent.
3. **Cloud runners come from Postman's IP ranges.** Before assuming a
   `postman-cloud` run will reach a target, check whether it's IP-allowlisted
   — use `postman-cloud-static-ip` if so, rather than discovering the
   mismatch as a wall of connection failures.

## Verification

State the actual metrics the run produced (p95, error rate, rps — whatever
the `--pass-if` checked, plus the ones it didn't) and whether the gate
passed, not just that the run completed. State which runner actually
executed it (`local`/`postman-cloud`/`postman-cloud-static-ip`) — that
determines whether the numbers reflect the target's real-world reachability
or only local-network conditions.

View saved version →

---
name: postman-mcp-server
description: Postman concepts and MCP tool guidance. Loaded when working with Postman MCP tools to make better decisions about tool selection and workarounds.
user-invocable: false
---

# Postman Knowledge

Reference for Postman concepts and MCP tool selection. Use this context when working with Postman MCP tools to make better decisions.

See `references/setup.md` for how to to setup postman mcp server and auth.

## Core Concepts

- **Collection:** A group of API requests organized in folders. The primary unit of work in Postman. Contains requests, examples, tests, and documentation.
- **Environment:** Key-value pairs (variables) scoped to a context (dev, staging, prod). Used to swap base URLs, auth tokens, and config without changing requests.
- **Workspace:** Container for collections, environments, and specs. Can be personal, team, or public.
- **Spec (Spec Hub):** An OpenAPI or AsyncAPI definition stored in Postman. Can generate collections and stay synced.
- **Request:** A single API call definition (method, URL, headers, body, tests).
- **Response:** A saved example response for a request. Used by mock servers and documentation.
- **Folder:** A grouping within a collection, typically by resource (e.g., "Users", "Orders").
- **Tags:** Labels on collections for categorization and search.
- **Monitor:** A scheduled collection runner that checks API health.
- **Mock Server:** A fake API that serves example responses from a collection.

## Decision Guide

| Goal | Approach |
|------|----------|
| Push code changes to Postman | Create/update spec in Spec Hub, then sync to collection |
| Consume a Postman API | Read collection + generate client code |
| Find an API | Use `searchPostmanElements`, then drill into details |
| Test an API | Run collection with `runCollection` |
| Create a fake API for frontend | Create mock server from collection with examples |
| Document an API | Analyze collection completeness, fill gaps, optionally publish |
| Audit API security | Run security checks against spec or collection |
| Learn how to use a Postman feature | Search Postman docs with `searchLearningCenter` (Full mode) |

## MCP Tool Selection

**Workspace operations:** `getWorkspaces`, `getWorkspace`, `createWorkspace`
**Collection CRUD:** `getCollections`, `getCollection`, `createCollection`, `putCollection`, `patchCollection`, `deleteCollection`
**Request/Response:** `getCollectionRequest`, `createCollectionRequest`, `updateCollectionRequest`, `getCollectionResponse`, `createCollectionResponse`, `updateCollectionResponse`
**Folder management:** `getCollectionFolder`, `createCollectionFolder`, `updateCollectionFolder`
**Spec Hub:** `getAllSpecs`, `getSpec`, `createSpec`, `getSpecDefinition`, `updateSpecFile`, `getSpecFiles`
**Sync:** `generateCollection`, `syncCollectionWithSpec`, `syncSpecWithCollection`
**Environments:** `getEnvironments`, `getEnvironment`, `createEnvironment`, `putEnvironment`
**Mocks:** `getMocks`, `getMock`, `createMock`, `publishMock`, `unpublishMock`
**Tests:** `runCollection`
**Docs:** `publishDocumentation`, `unpublishDocumentation`
**Search:** `searchPostmanElements` , `getTaggedEntities`
**Learning Center:** `searchLearningCenter` (Full mode only — searches Postman product docs for how-to guidance)
**User:** `getAuthenticatedUser`

See `references/mcp-limitations.md` for known limitations and workarounds.

## Workflows

Each reference below is a full MCP-tool workflow for one goal — the tool
call sequence, what to present at each step, and error handling. Reach for
one once the Decision Guide above has picked a goal; they assume MCP tools
only, no `postman` CLI.

- `references/setup.md` — first-run auth (OAuth or API key) and workspace verification.
- `references/search.md` — discover APIs across workspaces with `searchPostmanElements`.
- `references/sync.md` — create/update collections from specs, or sync a spec from collection changes.
- `references/mock.md` — create a mock server from a collection or spec.
- `references/test.md` — run collection tests and diagnose failures.
- `references/docs.md` — generate, improve, and publish API documentation.
- `references/security.md` — audit a spec or collection against the OWASP API Top 10.
- `references/learn.md` — search the Postman Learning Center for how-to guidance.

Referenced files: 9