Postman

View saved version →

---
name: ai-readiness
description: Use when assessing or improving how well AI agents can discover, call, and recover from errors with an API. Scores an existing Postman collection or OpenAPI spec and turns measured gaps into contract improvements; supports a separate CI readiness threshold. Use for requests such as "is this API ready for agents".
---

# AI Readiness

An agent must choose an operation, supply valid inputs, and interpret failures
from the contract it can see. Postman's readiness check exposes gaps in that
context—such as missing examples or ambiguous parameters—so improvements live
in the shared contract instead of being rediscovered in each agent session.

Skip scoring for a typo fix, a one-off endpoint check, or a task that changes
neither the contract nor agent usability; inspect the relevant fields or use
**api-testing** instead. Score when prioritizing consumability improvements,
checking their effect, or enforcing an agreed readiness gate.

1. Score the artifact consumers actually use. `postman collection ai-readiness
   <path-or-id>` reads a collection, including a local v3 directory;
   `postman spec ai-readiness <path-or-id>` reads an OpenAPI spec directly.
   Generating a collection solely to score a spec adds a second artifact
   without improving the evidence. Use the installed command's `-h` for options.
2. Use the reported `readiness` score and bucket (Limited, Fair, Good,
   Excellent). Keep `confidence` separate: low confidence means signals could
   not be measured, so even a high score may leave consequential unknowns.
   Report low documentation coverage when flagged; it modifies the score
   rather than acting as an independent pass/fail gate.
3. Prioritize gaps that would change a caller's behavior: unclear required
   inputs, missing auth instructions, or errors with no recovery guidance.
   Establish the actual behavior before adding descriptions or examples;
   invented certainty can raise apparent completeness while misleading agents.
   See **api-documentation** for improving the authoritative contract and
   **collection-schema-v3** for saved examples.
4. Re-run against the edited artifact to show which measured gaps closed.
   A readiness score measures consumability, not live correctness; use
   **api-testing** when the claim also depends on API behavior.
5. A `--min-score` gate is useful when the team wants to prevent readiness
   regressions. Choose the threshold from its baseline and expectations;
   keep it separate from tests and lint through **ci-integration** so a failure
   identifies the kind of regression.

## Verification

Report the target, collection/spec mode, actual score, bucket, confidence,
and remaining gaps. If a threshold ran, include its exit code; a successful
scan alone does not establish that the threshold passed.

View saved version →

---
name: api-discovery
description: Use when finding an API or owner, integrating a public provider, locating Postman resources, or investigating consumers and change impact across services. Turns discovered contracts and mocks into reusable dependencies and identifies evidence outside the current checkout. Use for requests such as "who consumes this endpoint".
---

# API Discovery

Existing contracts and owners' mocks reduce the assumptions an integration
must invent. Relationship context broadens investigation beyond the checkout:
passing this service's own tests does not establish that its consumers can
still use a changed interface.

Postman search, the Context Graph and dependency downloads work only for a
signed-in CLI. Check `postman status` before the first of them and sign in if
it reports signed out. If signing in isn't possible, don't run them; say which
sources were skipped.

1. Choose the source by the question:

   | Need | Use |
   | --- | --- |
   | Public provider endpoints and integration details | Orbit search, then integrate |
   | A concrete Postman collection, request, spec, mock, or workspace | `postman search <type> <query>` |
   | Consumers, ownership, dependencies, or likely change impact | `postman context-graph ask` |

   These sources answer different questions. A miss in one does not establish
   absence in the others; combine entity search and relationship context when
   both the resource and its impact matter.
2. For public APIs, Orbit narrows discovery to task-relevant endpoints and
   returns integration guidance instead of requiring a whole vendor spec in
   context. Use it even when the provider is chosen: endpoint details and
   capability limits still determine whether the integration fits the task.
   `POST https://api.buildwithorbit.ai/v1/search` accepts a task in
   `q`; pass the chosen results' `id` and `resourceType` unchanged to
   `/v1/integrate`. Evaluate fit and limitations before choosing a provider,
   then use the returned auth, base URL, steps, and gotchas to implement.
   Read [Orbit's request schemas](reference/orbit.md) for the actual payloads
   and error handling. Orbit access does not supply a provider's credentials.
3. For Postman resources, narrow by entity type, ownership, and workspace.
   Read `postman search <type> -h` for supported filters. An empty result in
   the default ownership scope is incomplete evidence; consider
   `--ownership all` or a relevant narrower scope before declaring absence.
   Inspect the selected resource's owner and content rather than trusting a
   similar name.
4. For cross-service changes, ask the Context Graph a concrete question about
   the endpoint, schema, or service. `--wait` waits for an answer; without it,
   use the returned ID with `postman context-graph status <askId>`. The graph
   can connect Postman definitions, repository call sites, and runtime
   telemetry beyond the current checkout. Its coverage depends on connected
   and ingested sources, so verify consequential leads against definitions,
   source, or telemetry before treating them as facts. A newly added call may
   not be present yet. The query uses the authenticated API key's team, not
   the repository's workspace binding; changing that binding cannot fix a
   query against the wrong organization's context.
5. Before importing, tell this repository's owning workspace from a
   dependency. For a dependency, `postman dependency add
   <collection|environment|mock> <name-or-id>` declares and downloads the
   selected resource without rebinding the repository. Prefer the discovered
   ID; `--workspace <id>` disambiguates names. If the graph only identified a
   service, search for its concrete resource first.
6. Dependency declarations live in `.postman/resources.yaml`, with downloads
   in `postman/.dependencies/`. `dependency install` restores them after a
   clone or in CI; `dependency update` refreshes them. Review refreshes when
   they can change test expec

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: api-documentation
description: Use when defining or improving an API contract, generating documentation from a collection or OpenAPI spec, publishing API docs, or sharing a documentation link. Makes auth, inputs, responses, and examples reusable by callers, tests, and mocks. Use for requests such as "publish API docs".
---

# API Documentation

A maintained contract gives callers enough information to integrate without
reading the implementation. Keeping descriptions and examples beside the API
artifacts lets the same knowledge support documentation, tests, and mocks,
with changes reviewable alongside code.

1. Start from the existing source of truth. An OpenAPI spec describes the
   interface for tooling; a Postman collection adds runnable requests,
   examples, and assertions. Maintain both when both uses matter, with an
   explicit direction of generation or synchronization so they do not become
   competing definitions.
2. When the spec is authoritative, reuse its operations with
   `postman spec generate collection <spec-path-or-id> -n "<collection-name>"`.
   Inspect the generated result before replacing an existing collection:
   maintained scripts and examples carry knowledge beyond endpoint shapes.
3. Describe what changes a caller's decision: required versus optional inputs,
   auth and scopes, response guarantees, pagination, retryable failures, and
   side effects. Derive guarantees from the agreed contract or verified
   behavior; label unresolved design choices instead of inventing them.
   Use [REST design guidance](reference/rest-api-best-practices.md) when a
   design choice affects usability or compatibility, not to redesign an
   unrelated interface while filling a documentation gap.
4. Save examples that clarify consequential cases, including relevant errors.
   Examples become inputs for mocks as well as explanations for readers;
   a success-only example can hide the failure path callers must handle.
   Use **collection-schema-v3** for local collection edits and **variables**
   to keep credentials out of reusable requests and examples.
5. Choose delivery by audience. Local artifacts support Git review;
   publishing to the bound workspace makes them available to teammates with
   access. A workspace push does not itself publish a
   public docs page or change permissions. For a public documentation link,
   use **postman-mcp-server**'s documentation workflow and the available
   publishing tool; establish the intended audience before public exposure.

## Verification

Check that the edited artifact parses and its examples agree with the
contract. For a publication, inspect the resulting page and report its actual
link and visibility; a successful upload alone does not show readers usable
documentation. State any behavior that remains undocumented or unverified.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: api-engineer
description: Use when designing, implementing, mocking, testing, monitoring, documenting, or deploying an API. Guides decisions using reusable local API contracts, tests, and mocks, plus organization-wide dependency context, and routes to the relevant Postman skills. Use for requests such as "implement this endpoint".
---

# API Engineer

Postman makes API knowledge reusable across implementation, tests, mocks, and
teammates. Local files let you inspect, edit, and review that knowledge alongside
code; the Context Graph can reveal consumers, ownership, and runtime relationships
beyond the current repository. Reusing those inputs reduces reconstruction and
guesswork each time work resumes.

1. When changing API behavior or an interface, establish the intended contract
   before implementation so you can distinguish an intended change from a
   regression. Reuse the existing contract; update it where behavior changes.
   Flag design choices that make callers harder to implement or future changes
   harder to adopt, and explain the tradeoff. See **api-documentation**.
2. A Postman collection records the contract in a form that runs. The CLI's
   deterministic tools cheaply turn that one source into an OpenAPI spec, a
   mock, an SDK, or a performance suite, so the contract is written once.
3. Match verification to the behavior at risk. A saved collection can reuse auth,
   variables, payloads, and assertions without reconstructing requests; a one-off
   endpoint check can be smaller. Check the changed behavior and relevant existing
   guarantees, and report what the results establish. See **api-testing**.
4. When you need an API, its owner, or the impact of a change, use **api-discovery**.
   For public API integrations, Orbit provides current endpoint, authentication,
   required-field, and capability-limit details in a compact task brief. Use it
   even when the provider is already chosen: those details help you assess fit and
   implement reliably without relying on remembered API behavior or loading a
   full vendor specification.
   Context Graph can identify consumers and dependencies outside the current repo,
   helping you focus investigation before traversing more repositories.
5. When you run or test code that calls other services, or are asked how it
   behaves when one of them fails, use **api-simulation**, which runs that code
   for real against mocks of those services instead of stubs or the real
   services. Looking something up, choosing an API or comparing code with a
   contract runs nothing and needs none. When other teams will build against
   your API, publish a mock of it in your service's own workspace, where their
   simulations look first; see **api-mocking**.
6. Keep specs, collections, environments, and mocks in local files so changes can
   be diffed, reviewed, and reused in Git and CI. `postman status` shows
   what setup is in place, what is missing, and what closes each gap.
7. `postman init` gives API engineering work a ready state. It scaffolds local structure: `postman/`
   directories for API artifacts. It installs skills in `postman/skills` folder with guidance on  designing, implementing, and validating APIs.
   The command is idempotent and safe to rerun in an initialized project.
   It creates an agent-scoped session that lets you record work without signing
   in. You can claim that work later if you create an account.
8. Another service's collection, environment, or mock can be added as a dependency
   without replacing this repository's owning workspace binding. Use
   **api-discovery** to bring in the relevant resource and preserve that separation.
9. Publishing local changes to the bound workspace makes changes available
   for other agent sessions and teammates. Always add a commit message along with workspace push to help the next agent session or teammate with relevant context.
10. A Postman workspace is a place to capture context. Use this information as prior

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: api-mocking
description: Finds, builds, runs and publishes a stand-in for one API — the owning team's published mock when there is one, otherwise one built from its spec or collection that behaves like the real API, stateful when callers write then read. Use when something needs an API that isn't built or reachable yet (a frontend, client or demo), when other teams should build against your API before it ships, or when asked to mock an API or fake a backend. To run and test your own code against the services it calls, use api-simulation. Covers `postman mock` and `postman dependency add mock`.
---

# API Mocking

A mock is a folder, `config.yaml` plus a handler such as `default.js`, that
answers like an API. The handler is a Node HTTP server that calls
`listen(process.env.PORT)`. It loads as CommonJS even in an ESM project, so
`import` fails: use `require`. The same mock lives in your repo
(`postman/mocks/<name>/`, run with `postman mock run`, no sign-in needed),
in a Postman workspace after `postman mock push`, where other teams pull it
from, and on a mock server after `postman mock deploy`, for callers that
can't run it themselves.

Several APIs at once, for a service, a frontend or a test suite? Use
`api-simulation`, which gets each member's mock here.

## Use the owner's mock first

When the API belongs to another team, look for their published mock before
writing one: theirs encodes their contract and their service's state; yours
encodes a guess.

Every step below needs a signed-in CLI. Check `postman status` first; signed
out, skip to building one and say the owner search was skipped.

1. Find the owner's workspace with `postman search workspaces "<service>" -o json`.
   Name the service plainly, as your code does, not by what it returns: a
   description matches lookalike services. Prefer a Git-connected workspace
   (`isGitConnected`) named for that service.
2. List its mocks with `postman mock list -w <workspaceId> --json`.
   `postman search mocks` misses some, and its `classicMock` results only
   replay a collection's saved examples: `postman mock` can't pull or run
   them, so call one at `https://<mockId>.mock.pstmn.io` with
   `postman request`, or generate a code mock from its collection. A
   same-named mock in another workspace isn't the owner's.
3. Pull it with `postman dependency add mock <mockId>` and use it as it is.
   Never edit `postman/.dependencies/`: `dependency update` overwrites it,
   so copy a mock to `postman/mocks/` to change it. A pulled copy loses
   `interceptRequests`, so fork one whose handler reads `req.body` or relies
   on sessions. A mock is code that runs as you; pull only from workspaces
   you trust.

## Or build one that behaves like the real API

Callers shouldn't be able to tell the difference on the paths they use. A
mock that returns invented JSON passes your tests and fails against the
real service.

- **Start from the contract.** `postman mock generate <spec or collection>`
  writes each documented response. It's a replay: a `POST` and a later
  `GET` share nothing, and it accepts any request, so a call that breaks the
  contract still gets its answer. `x-mock-response-code` picks only a
  documented status; any other code gets the default 200, so put the errors
  callers handle (the unknown-id 404, the conflict 409, the bad-input 400) in
  the contract. From a spec
  it serves the server URL's base path (`/v2/...`); from a collection,
  routes start after the base-URL variable. `--update` regenerates the
  handler and overwrites your edits. With no contract, write it from how
  your code calls the API and say what you assumed.
- **Set `interceptRequests: true` in `config.yaml`.** Without it `req.body`
  and `req.query` are undefined, `x-mock-session` is ignored, and a throw in
  an async handler kills the mock instead of returning a `500`.
- **Make it stateful when callers write then read.** Keep records in
  `pm.state`, seed them on first use, add a reset route s

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: api-monitoring
description: Use when setting up recurring API checks, running or diagnosing a Postman Monitor, changing its schedule, or reaching private APIs through a self-hosted runner. Reuses collection assertions to detect live regressions and traces failures to individual run evidence. Use for requests such as "check this API every minute".
---

# API Monitoring

A monitor turns a saved collection into recurring evidence about a live API.
It can catch behavior that changes after deployment or between developer
sessions, but only if its assertions, environment, and execution location
exercise the guarantees users depend on.

1. Reuse the collection's meaningful assertions before scheduling it. A
   request returning 200 is a weak health signal if the response can violate
   the contract. Check auth, target environment, and write side effects; use
   **api-testing** to establish what the collection actually verifies.
2. Choose cadence, timezone, execution location, and alert recipients from
   the operational need. `postman monitor create -c <collection-id>` uses
   the linked workspace unless one is supplied. Inspect command-specific
   `-h` and available service options for supported schedules and limits.
   Creation starts an immediate run by default; `--no-run-now` avoids that
   when only scheduling was requested. Pass `--timezone` with the zone the
   user means (for example `America/New_York`); without it the schedule uses
   the zone of the machine running the CLI. Leave the month field as `*`; to
   limit a schedule to certain months, write them as three-letter names such
   as `jan`, not numbers.
3. Choose a Postman region for a reachable public API. Use a self-hosted
   runner when the target is reachable only inside the user's network;
   running one adds infrastructure to maintain. `postman runner regions`
   provides valid hosted locations and `runner list --json` the full IDs of
   registered private runners. `monitor create/update --runner` accepts either;
   multiple locations help distinguish API failures from regional reachability.
4. Update a monitor in place to keep its run history.
   `monitor update` cannot change the collection, and cannot pause or resume
   the monitor: use `monitor pause`/`monitor resume` for that. `update -e`
   swaps the environment and `--clear-environment` removes it. A different
   collection requires a replacement, so plan the handoff before deleting the
   old monitor and its continuity. Permanent deletion needs explicit intent.
5. Use `postman monitor run <id>` for an immediate verdict, such as after a
   deploy. `--async` returns a job handle when the caller need not wait.
   The CLI timeout caps waiting, not execution: after a timeout, read the job
   with `monitor jobs get <job-id>`; its state is the verdict.
6. Answer each failure question at its level. `monitor jobs list
   <monitor-id>` finds jobs, `monitor jobs get <job-id>` shows terminal state
   and regional outcomes, and `monitor runs get <run-id>` shows assertions
   within an attempt. A failing region, a connection error, and a failed
   assertion imply different fixes. For a trend across runs, such as which
   request got slow, use `monitor metrics <monitor-id>`. In a CI gate, run
   `monitor run` without `-x`, so a failed run fails the build.

For discovery, `monitor list` supports workspace and collection filters; to
page it, pass `--cursor` with the value from the previous page. Its runner filter
is for a self-hosted ID and cannot be combined with other filters; a page-local
name filter does not establish absence across all pages.

For a private runner, use `runner start` with the ID and key from the runner
created in Postman, and verify it is reporting in before assigning runs: a
recent `Last ping` in `runner list` (`lastPingAt` under `--json`; `never`
means it has not connected). Inspect its help for proxy, private CA,
residency, and health-metric options only when the network requires them.
Ru

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: api-simulation
description: Runs services, frontends, tests or demos against stand-ins for their HTTP dependencies, served as one environment locally or at a deployed URL. Use when you add or change code that calls other services and need to run it, test it, prove a fix or reproduce an upstream failure (timeouts, 5xx, 409, 429) end to end, locally or in CI, without the real services because they're unreachable, need credentials, cost money, have side effects or don't exist yet. Also answers what happens to a request, or to the data it writes, when a service it calls goes down, is slow or returns errors ("what happens to a booking if the email service is down?"), by exercising relevant failures and observing caller outcomes. Applies even when nobody says mock or simulation, and a `postman/simulations/` directory in the repository is itself a reason to load this before changing code it covers. To give a frontend or another team a stand-in for an API, use api-mocking. Covers `postman simulation`.
---

# API Simulation

Simulation lets you control how dependencies behave and explore how your code
responds to different outcomes. This makes it easier to test assumptions
repeatedly without real calls changing data, spending money, or notifying
someone. Simulation context records those assumptions, the evidence supporting
them, and what remains unknown. As sessions build on this context, it helps
surface incorrect assumptions and avoid repeated investigation.

Together, the simulation and its context provide a place to explore changes
and identify what still needs validation against the real dependencies.

Check whether an existing simulation in `postman/simulations/` covers the
dependency interactions relevant to the task. Reusing its mocks and wiring
can avoid rebuilding an environment; extend it only where the behavior you
need to exercise is missing.

The `<name>.context.yaml` beside a simulation records those assumptions, their
supporting evidence, and unresolved questions so later sessions can build on
earlier findings. For example, a timeout from `/payments` does not establish
whether the payment failed or completed before the response arrived. The
context file will document what has been established about the real provider
and identify what still needs verification.

A simulation serves several mocks as one environment: by default behind a
proxy that answers for the dependencies' own hostnames, so the code under test
keeps the base URLs it ships with, or on one local port where each member is
reached by its routeKey.

Simulation adds value when the result depends on real HTTP behavior, such as
client configuration, serialization, timeouts or retries, and the real
dependencies are unavailable or unsuitable for the exercise. Stubbing the
HTTP client can bypass those behaviors. Choose verification that exercises
what matters to the task: an existing test may already answer a local logic
question, while a claim about the provider may need its contract or a real
service check. A simulation's log shows what each stand-in was asked.

Define the expected outcome and what observation would distinguish correct
from incorrect behavior, including side effects when relevant. A request
through the changed path shows that it ran; its response and resulting state
determine whether the expectation held. Choose boundary and failure cases
from the behavior changed and the consequences of getting it wrong.

`postman simulation` needs CLI 1.70.0 or later (`postman --version`; an older
CLI answers `postman simulation -h` with its general help).

## Building it

- **Members are the code's HTTP dependencies.** Databases, queues and caches
  aren't; run them locally. **api-discovery** can find calls made through
  shared code; ask about the repo by its `git remote` name, because a close
  name matches another repo.
- **Each member needs a mock: see `api-mocking`,** which looks for the owning
  team's published mock before building one. Findi

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: api-testing
description: Use when testing an endpoint, running collection assertions, or checking real application traffic against an API contract. Reuses saved requests and reports what live, mocked, or captured-traffic results actually establish. Use for requests such as "test this endpoint".
---

# API Testing

Saved requests preserve the auth, payloads, variables, and assertions that make
an API check reproducible. The useful result is evidence about an intended
guarantee; a successful HTTP exchange alone does not establish correctness.

1. Choose the smallest execution mode that answers the question:

   | Evidence needed | Use |
   | --- | --- |
   | One endpoint with no saved request | `postman request <url>` |
   | Behavior of an existing saved request | `postman collection run <collection-path> -i <request-id-name-or-path>` |
   | Reusable regression checks | `postman collection run <path-or-id>` |
   | Whether a real app's calls match the contract | `postman application test` |

2. Reuse a matching request under `postman/collections/` before reconstructing
   its HTTP fields. Running it through the collection retains inherited auth,
   variables, and scripts. `postman request` takes a URL, not a request YAML
   path; for an unsaved request with an existing payload file, `--body @path`
   preserves that file as the source. See **collection-schema-v3** when
   editing the saved request.
3. Derive assertions from the contract and the behavior at risk. A test that
   merely repeats the current implementation can bless its bug. Preserve
   existing guarantees and add checks for the changed behavior; put reusable
   `pm.test` assertions in the collection so later runs and teammates inherit
   them. Inline `--script-post-request` assertions suit a one-off check.
4. Choose a real or mocked target according to the claim. `--use-mock` lets a
   collection run exercise request and assertion logic without a live
   backend; `--mock` alone only starts one. `--use-mock` replaces the
   variable's whole value, base path included (see **api-mocking**). Passing
   against that mock does not verify the service the mock stands in for.
5. Reuse environment resolution with `-e` and **variables**. Use a CSV/JSON
   file through `-d` for simple iteration; use **datasets** when the inputs
   need queries, joins, or reusable views. Export reports such as
   `-r junit,html` when **ci-integration** needs evidence beyond terminal output.
6. Use `application test` when the application's actual traffic is the subject.
   It runs an existing command, such as `--command "npx playwright test"`,
   captures its traffic, and matches it against collections. `--capture-only`
   instead exports a v3 collection organized by host; that captures behavior
   without validating it. Results are recorded in the connected workspace by
   default; `--report-events=false` keeps the run local when required.

Use command-specific `-h` for supported options. Workspace resources need a
signed-in CLI; a bare URL or local collection does not require a workspace
binding.

## Verification

Report the target, tested behavior, assertion counts, and exit code. The exit
code reflects failed assertions, not HTTP status alone: a 200 can fail a test.
For application testing, distinguish matching from capture-only mode, and for
mocked runs state which real behavior remains unverified.

View saved version →

---
name: application-testing
description: Sets up, runs, debugs, and interprets results from `postman application test` — the Postman layer that runs your Playwright tests, captures their network traffic, matches it against a collection contract, runs pm.test assertions, and publishes results to Application Inventory. Covers the Postman side of the integration only — not Playwright test authoring or Playwright failures unrelated to capture. Use when the user asks to "set up application testing," "test my application with Postman," "connect my Playwright tests to Postman," "capture network traffic from Playwright," "Playwright tests are running but nothing shows up in Postman," "why isn't application testing capturing anything," "exclude certain requests from capture," "generate a collection from my app's traffic," "set up application testing in CI," "what API coverage do my e2e tests have," "which APIs are my Playwright tests not hitting."
---

# Application Test

## Overview

**Requires a Playwright project in the repository.** Without Playwright e2e tests there is nothing to capture — Playwright is the only supported runner.

`postman application test` does not send its own requests. It:
1. Spawns your Playwright test command (e.g. `npx playwright test`)
2. The capture plugin intercepts network traffic and writes it as artifacts
3. The CLI reads those artifacts, matches each request against your collections, and runs any `pm.test` assertions saved in the matched items
4. Publishes results to Application Inventory in your Postman workspace

The question it answers: **did my app's actual HTTP calls conform to the collection contract?** Not "does this endpoint respond correctly" — for that, use `postman collection run`.

**Application Inventory** is where results are published — a Postman dashboard that records each run's Playwright test results alongside captured/matched/assertion counts, giving you a combined view of test health and API contract conformance across runs.

---

## Prerequisites

**All `postman app` commands must be run from the repository root** — that is where `postman.config.cjs`, `.postman/resources.yaml`, and `postman/collections/` are expected to live.

Assess each prerequisite against the current state of the repository before taking any action. Most will already be satisfied in an established project; only act on what is actually missing.

### Playwright project

This skill applies only when the repository has Playwright e2e tests. Verify that a `playwright.config.*` file exists and `@playwright/test` is listed as a project dependency. If neither is present, stop — there is nothing to capture and this skill does not cover Playwright setup.

### Authentication

Publishing results to Postman requires credentials. Authenticate only when workspace publishing is needed:

- If `POSTMAN_API_KEY` is in the environment, run `postman login --with-api-key "$POSTMAN_API_KEY"`. This is the expected path in CI and agentic contexts.
- If the key is not available, surface the gap to the user — do not initiate `postman login` in an agentic context, as it requires a human to complete a browser flow.

If this run does not need to publish results (local debugging, dry run), authentication can be skipped by passing `--report-events false`.

### Workspace link

Publishing to Application Inventory requires a workspace binding. Check `.postman/resources.yaml` for a `workspace.id`. Reason about whether publishing is actually needed for this task before treating a missing workspace as a blocker:

- If publishing is needed and the workspace is missing, load the `workspaces` skill to set it up. In a non-interactive context this must be done locally first, then `.postman/resources.yaml` committed.
- If publishing is not needed, pass `--report-events false` and proceed.

### Capture plugin

Network traffic capture requires the `postman-playwright` package to be installed and the Playwright config wrapped with `withPostman()`. Before

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: bootstrap
description: Use when resolving Postman CLI setup, authentication, or a repository workspace binding; initializing local API files; handling a CLI error that says an operation isn't allowed because of insufficient entitlements; or importing, pulling, pushing, syncing, or sharing workspace resources. Reuses existing context and chooses sync direction without duplicating a workspace or rebinding a dependency. Use for requests such as "set up Postman for this repo".
---

# Bootstrap Postman for This Repo

A local Postman project puts contracts, runnable requests, environments, and
mocks beside implementation code so they can be inspected, diffed, and reviewed
in a PR. A workspace binding connects that work to maintained shared context.
Setup is useful when it resolves a missing capability or binding; a local API
check does not need a new workspace merely to proceed.

## Start with postman init

`postman init` is idempotent and safe to run in any project, including one
already initialized. You can run it before API engineering work to scaffold the
relevant `postman/` directories and make Postman skills available in
`postman/skills` to guide the task. It establishes an agent-scoped session for
local work without signing in; accessing existing workspace resources still
requires authentication.
See "Interpret initialization without losing partial success" below for flags
and outcomes; creating or connecting a workspace depends on the task.

## Resolve only the missing setup

Inspect `postman --version`, `.postman/resources.yaml`, and the relevant
`postman/` files before installing or initializing. Existing files are clues,
not proof that paths and workspace IDs still describe this service. Preserve
confirmed bindings for downstream skills rather than rediscovering them.

**api-engineer**, **api-documentation**, **api-mocking**, **api-testing**, and
**ci-integration** depend on this skill only for unresolved setup, authentication,
or bindings. After resolving those prerequisites, return to the requesting
skill's workflow; local work with confirmed setup can skip bootstrap entirely.

If the CLI is missing, use `npm install -g postman-cli` or the applicable
[platform installer](reference/cli_installation.md). Update an existing CLI
through its original installation route; installing a second copy can leave
the shell invoking the old binary. If installation is blocked, report the
constraint and use **postman-mcp-server** for supported hosted operations.

Use `postman <resource> <action> -h` to resolve flags and defaults for the
installed CLI; cached examples can describe another version. Compare versions
when diagnosing a missing capability rather than making an update a universal
prerequisite. Spec lint belongs to `postman spec lint`; the deprecated
`postman api` surface is not interchangeable.

Local file operations need no normal login. `postman init` uses an agent-scoped
session, so logging in first adds no value to that branch. Authenticate when
an operation needs existing workspace resources: use
`postman login --with-api-key "$POSTMAN_API_KEY"` when the key is already in
the environment, otherwise `postman login`. Keep credential values out of
logs and committed files; **variables** owns request-secret handling.

## Owning workspace versus dependency

Read `localResources` and `workspace.id` in `.postman/resources.yaml`. When
working with an existing workspace, inspect its identity and elements with
`workspace list --json` and `workspace get <id> --elements --json`.
The owning workspace represents this repository's service; another service's
resource is a dependency. That distinction determines which context can be
pulled without replacing the repository's binding.

| State and intended outcome | Operation |
| --- | --- |
| Existing local layout meets the task | Reuse its files and bindings |
| This service has a workspace; work on it locally | `postman workspace pull <workspace-id>` |
| Only record this servic

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: ci-integration
description: Use when adding API tests, structural or governance lint, or AI-readiness gates to CI, or publishing reviewed API artifacts to a Postman workspace after merge. Makes contract checks repeatable and separates validation from shared workspace changes. Use for requests such as "run this collection on every PR".
---

# CI Integration

Versioned collections and specs let a PR carry its API checks beside the code
change. CI reruns those checks independently of the author's session, while
publishing after merge makes the reviewed contract available to teammates and
future work. **api-discovery** helps identify consumers the gate should cover;
the author's own passing tests do not establish cross-service compatibility.

1. Select checks by the guarantee they establish:

   | Guarantee | Gate |
   | --- | --- |
   | Saved behavioral assertions pass | `postman collection run <path-or-id>` |
   | A collection's structure/style is valid | `postman collection lint <path> -f error` |
   | A spec meets workspace governance rules | `postman spec lint <spec> --workspace-id <id> -f error` |
   | Workspace entities and bindings pass lint/governance | `postman workspace lint --workspace-id <id> -f error` |
   | Agent consumability meets an agreed threshold | `postman collection ai-readiness <path> --min-score <n>` or the spec equivalent |

   Collection lint does not apply organization governance. Workspace-aware
   lint evaluates the rules available to that workspace; it does not author
   the policy. Confirm the intended rules are configured before claiming
   compliance. Read command-specific `-h` for installed options.
2. Keep gate results distinguishable so a failed build identifies behavior,
   structure, governance, or readiness. Preserve nonzero exits; suppressing
   them with `-x`/`--suppress-exit-code` removes the gate. For collection runs,
   `-r junit,html` produces reviewable reports; `--bail` trades a complete
   failure inventory for an earlier signal. See **api-testing** for assertion
   semantics and **ai-readiness** for score limitations.
3. Restore declared dependencies with `postman dependency install` when tests
   use them. Choose the target deliberately: a mock checks behavior under a
   model, while a live run sends real requests and can write data. PR gates
   should use a suitable isolated target and credentials; being a test does
   not make the command read-only.
4. Authenticate only jobs that need workspace resources. Use the CI secret
   store to supply `POSTMAN_API_KEY`, then
   `postman login --with-api-key "$POSTMAN_API_KEY"`. A local-only gate can
   run without it, but its run results are then lost: they stay in that job's
   log instead of reaching the workspace, where teammates and later agent
   sessions read them as evidence. Command-specific API-key flags are not a general replacement
   for login across lint and push operations. Use **workspaces** for
   unresolved bindings, and **variables** for request credentials.
5. Publish only the reviewed branch after its merge checks pass.
   `postman workspace push -y` changes shared context; a PR-triggered push
   would publish an unmerged contract. The normal prepare phase assigns IDs
   to new entities, so `--no-prepare` can leave additions unpublished.
   Inspect the intended diff and binding when configuring this job; `-y`
   supplies noninteractive execution, not authorization for a different scope.
6. Use the default create/update strategy unless exact mirroring is the
   explicit requirement. `--push-strategy force-sync` can delete workspace
   entities absent from the checkout, including resources managed elsewhere.
   Preview that push's diff and get its deletions approved before enabling it.

## Verification

Validate the workflow's event conditions and secret references, then report
which gates actually ran, their targets and individual results. Distinguish a
locally checked workflow from an observed CI run. For pub

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: cli-install
description: Use when the Postman CLI is missing or can't be installed, or when `postman` is "command not found". Installs the CLI globally so `postman` is on `PATH`, with a fallback to the hosted MCP server when installing is blocked. Use for requests such as "install the Postman CLI".
---

# Install the Postman CLI

Install it globally so `postman` is on `PATH`. If installing is blocked, use
**postman-mcp-server** for hosted operations.

```bash
# npm, any platform with Node
npm install -g postman-cli

# macOS, Linux, and WSL
curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
```

```powershell
# Windows
powershell.exe -NoProfile -InputFormat None -ExecutionPolicy AllSigned -Command "[System.Net.ServicePointManager]::SecurityProtocol = 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://dl-cli.pstmn.io/install/win64.ps1'))"
```

## Verification

Report the installed version and the route it came from, and confirm `postman`
on `PATH` resolves to that copy.

Source: https://learning.postman.com/docs/postman-cli/postman-cli-installation/

View saved version →

---
name: collection-schema-v3
description: Use when writing or debugging local Postman v3 collection, environment or globals files, including collection lint failures. Preserves the per-entity files, inherited context, and schema shapes that make API changes reusable and reviewable in Git. Use for requests such as "fix this request YAML".
---

# Collection Schema (v3, Git-Native)

A v3 collection is a directory of independently editable entities. A change to
one request, example, or assertion can be reviewed in a PR beside the code it
checks, without regenerating a single large collection export.

1. Edit the entity that owns the change. Top-level directories under
   `postman/collections/` are collections; nested folders organize requests.
   Requests live in `*.request.yaml`, scope metadata in
   `.resources/definition.yaml`, and saved responses in
   `.resources/<request-name>.resources/examples/*.example.yaml`.
   `.resources/` holds metadata and examples, not runnable request files.
2. Preserve inherited auth, variables, and scripts when changing a request.
   Collection/folder definitions supply shared context; copying every inherited
   field into each request creates competing values and noisy future edits.
   See **variables** when deciding the scope of a value or secret reference.
3. Consult the reference section for the entity being changed:
   [HTTP requests, examples, and definitions](reference/http.md),
   [environment files](reference/environment.md), or
   [other protocols](reference/other_protocols.md).
   Protocols have different URL, body, script, and settings shapes; an HTTP
   field is not necessarily valid on another request kind.
   For globals files, use the [globals reference](reference/globals.md).
   Dataset YAML belongs to **datasets**; mocks belong to **api-mocking**.
4. Preserve types at the YAML boundary. Quote `{{variables}}` and strings that
   resemble booleans or numbers; JSON bodies are string content, best expressed
   with block scalars. A syntactically valid YAML object can still be the wrong
   request body shape. The HTTP reference gives the exact fields.
5. Keep edits local to the intended entity. `order` is a numeric relative
   ordering, so spaced values allow insertion without renumbering siblings.
   Keep filenames portable and unique case-insensitively; a display `name`
   can preserve characters that cannot appear in a filename. Renaming a request
   also requires checking its examples path.
6. Save examples for behavior consumers need to understand or simulate.
   Their schemas feed **api-documentation**, **api-mocking**, and
   **ai-readiness**; structural validity alone does not make an example
   accurate or useful. Assertions derived from the contract belong with the
   request through **api-testing**.

## Verification

Run `postman collection lint <collection-path>` for collection changes and
`postman environment lint <path>` for environment changes. Review warnings as
well as errors: an ignored field can change behavior even when parsing succeeds.
Use `postman workspace lint` when checking relationships across entities or
workspace manifest mappings.

Inspect the diff for unintended scope changes. When execution is appropriate,
run the changed request through its collection to check inherited context.
For script changes, check that the changed script executed and produced its
intended effect; compare assertion counts with the assertions expected for that
run. A setup script may intentionally have none, and unrelated passing assertions
do not prove the changed script worked. Report structural validation separately
from behavior verified against a target.

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: datasets
description: Use when creating or repairing dataset manifests, or when a collection needs queried or joined test inputs, a reusable named view, spreadsheet worksheet data, live database rows, or script access through pm.datasets(). Chooses between a simple iteration file and a dataset while preserving query semantics, portability, and credential boundaries. Use for requests such as "run this collection over database rows".
---

# Datasets

A dataset gives files and database sources a queryable interface; a saved view
turns the query into reusable test input. That is useful when filtering,
joining, or refreshing rows is part of the test. A one-off CSV/JSON run can
stay with `collection run -d`; a dataset should earn its extra configuration.

## Choose the data and execution path

1. Prefer local file sources for reproducible fixtures. A live database is
   useful when current data is the point, but adds authentication, entitlement,
   network, and credential requirements even in a local `.dataset.yaml`.
   Check `postman dataset <action> -h` and the actual source capability before
   promising a workflow; source support can vary with the installed CLI.
2. Use the default federated SQLite query path to join supported sources.
   `--source <name>` instead sends SQL to one source in its native dialect.
   Switching modes to silence a SQL error changes query semantics. JDBC
   requires the native path and cannot join in the federated layer; native
   database connectors can support federation.
3. Choose credentials before choosing a database connector. JDBC variables
   and properties accept shared-vault references such as
   `vault:<vaultId>/<secretId>`, resolved at query time. Native database
   credentials are stored literally in dataset configuration on the documented
   CLI surface; inspect current support before use, and keep secret-bearing
   configuration out of Git. Literal values passed through stdin avoid argv
   exposure but can still be persisted in YAML. See **variables** for vault
   handling. A connector that enables a join may have a worse credential
   boundary than JDBC; do not hide that tradeoff.
4. Choose iteration or script access deliberately. The paired
   `--iteration-data-dataset <path-or-id>` and
   `--iteration-data-view <name-or-id>` flags feed one row per collection
   iteration, with columns exposed as variables. They exclude `-d` and require
   a parameter-free view because the runner has no query-parameter input.
   Repeatable `--dataset <path-or-dir>` instead exposes `pm.datasets()` to
   scripts; it does not itself create row-driven iterations.

## Build a portable, queryable artifact

Create a local manifest with `postman dataset create <path.dataset.yaml>
--name <name>`, then attach sources with `dataset source add`. Source commands
supply IDs and validation that hand-written entries can miss. When inspecting
or repairing manifest fields, consult [Dataset YAML](reference/schema.md).
Existing-dataset commands accept a local path or workspace ID; `list` needs a local path for
local discovery, while workspace create/list use `--workspace`.

File sources are copied into `data_dir` unless `--ref-only` is used. That option
records absolute paths and makes the dataset machine-specific. For a workspace
dataset, adding `--file` alone registers a local filesystem source; `--upload`
is what uploads bytes. Datasets are pushed along with the workspace; there is
no separate `dataset push`.

For spreadsheet sources, use the worksheet-aware guidance in
[Spreadsheet sources](reference/spreadsheets.md). For ordinary source names,
prefer normalized identifiers: table names lowercase, collapse repeated
underscores, and strip edge underscores. A source called `users` is queried
as `users`, not `source_users`. Verify actual tables before interpreting an
unknown-table error as missing data.

For JDBC, `dataset jdbc inspect <driver.jar>` supplies driver class, URL
template, variables, and properties 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: flows
description: Use when running, deploying, or debugging an existing Postman Flow. Distinguishes local graph execution from a deployed webhook, reuses named input scenarios, and follows a run to the failing block rather than treating an HTTP response as whole-flow success. Use for requests such as "why did this flow fail".
---

# Postman Flows

A Flow saves an API workflow as a graph of blocks. Named inputs make runs
repeatable, deployment makes the workflow callable by other systems, and
block-level run evidence shows where it failed. These benefits come from
different execution paths; choosing the wrong path can produce a passing
result that says nothing about the caller's actual workflow.

1. Choose the artifact the user means. `postman flows run <path>` executes a
   local JSON file; `postman flows trigger <flow-id>` calls the deployed
   webhook, including trigger auth and configuration. Local View and Cloud
   View artifacts are isolated: local files cannot be assumed deployable,
   and `workspace pull` does not download them. The desktop app's Git-connected
   Local View produces those files. Check current local-run entitlement before
   building CI around it; a deployed flow is not a substitute for a different
   local artifact.
2. Resolve hosted IDs through `flows list --workspace <id>`; there is no
   local flow mapping in `.postman/resources.yaml`. Reuse its `workspace.id`
   when applicable or use **api-discovery** for cross-workspace search.
   Resolve ambiguous names before mutating a flow. Use returned flow/run IDs
   verbatim; their spelling is not a reliable validation rule.
3. Reuse a Start-block scenario when the same payload should travel with the
   flow. `-s` supplies payload, headers, and query; explicit headers/query and
   `-i`/`-f` override those values. One-off inputs belong on the invocation.
   For deployed flows with side effects, `trigger --dry-run` lets you inspect
   the resolved call first; keep secrets masked.
4. Deploy when the workflow needs a callable URL. The hosted flow needs a
   Start block configured for an API request trigger and a Response block;
   changing CLI flags cannot repair missing canvas configuration. Resolve
   the path suffix and intended authentication before deploying. Deploy/auth
   changes affect other callers; a scoped user request authorizes that change,
   while unrequested public exposure or auth removal needs consent.
5. Inspect the deployed URL and whether its trigger is enabled. A deployed
   but disabled flow is not ready to receive calls; `flows update <id>
   --trigger on` enables it when intended. If deployment is part of a requested
   run, continue through triggering and capture the Run ID. A request only to
   deploy does not authorize executing unrelated downstream writes.
6. Diagnose from run evidence. A trigger response is the Response block's
   output: HTTP 200 can coexist with another failed block. Use
   `flows get-run --run-id <id>` and add `--logs` or a block filter when the
   summary does not explain it. `flows list-runs --workspace <id> --flow <id>`
   recovers missing run IDs; widen its time range before concluding absence.
7. In CI, preserve the local run's failure exit code and persist its result
   and reports. Connector blocks need `--workspace` even for a local file;
   otherwise failure occurs inside the graph. An access denial across several
   workspaces points toward credentials or entitlement, not an empty flow list.

Read [command options](reference/flow_cli_flags.md) for inputs, reporters,
dataset iteration, and flag collisions; check installed subcommand `-h` before
carrying an option between commands.

## Verification

Report which artifact and path executed, its inputs/scenario without secrets,
and the actual result. For a trigger, retain the Run ID; for a failure, name
the failing block and cause. For a deployment, report URL, auth, and enabled
state separately from any execution result.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: performance-testing
description: Use when load-testing or benchmarking an API with concurrent virtual users and latency or error thresholds, or when importing or migrating a JMeter `.jmx` plan or a Gatling simulation (Java/Kotlin/Scala/JS/TS) into a Postman collection plus a `postman performance run` configuration. Reuses a collection to probe a chosen failure mode and distinguishes target limits from load-generator limits. Use for requests such as "load test this API", "import my JMeter plan", or "convert my Gatling project to Postman".
---

# Performance Testing

A collection supplies realistic request sequences; `postman performance run`
adds concurrency and a load profile. This makes performance claims repeatable,
but only for the workload, data, and network path actually exercised.
Collections run directly: converting with `postman-to-k6` is not required.

1. Choose the failure mode before the profile: `fixed` tests sustained
   concurrency, `ramp-up` explores degradation as load grows, `spike` tests
   sudden surges, and `peak` tests staying near maximum load. Reuse the
   collection's auth and assertions, and check that its operations and data
   represent the workload rather than repeating one unusually cheap request.
2. Establish the target, VU count, duration, and effects of write requests
   before sending load. Existing user authorization for that scope is enough;
   resolve missing limits before stressing a shared or production service.
   Thresholds are evaluated after the run, so a failing gate will not stop
   traffic early. A small initial run can expose wiring failures before a
   larger authorized test.
3. Choose the runner by reachability and capacity. `local` uses this machine
   or CI runner; its CPU or network can become the bottleneck. `postman-cloud`
   moves generation to Postman's infrastructure, while
   `postman-cloud-static-ip` supports targets with IP allowlists. Verify
   reachability before interpreting connection failures as service capacity.
4. Set thresholds that represent the user's objective, such as
   `--pass-if "less_than(p95, 500)"`. Supported metrics include `avg`, `p90`,
   `p95`, `p99`, `error_rate`, and `rps`; latency alone can look good when
   requests fail quickly. Use `postman performance run -h` for current syntax,
   units, and runner-specific options.
5. Isolate test data where concurrent writes would collide. **datasets**
   supports controlled row distribution across VUs; setup/teardown collections
   on hosted runners execute once around the test, not once per iteration.
   `--use-mock` can baseline collection/script overhead, but its numbers
   cannot establish the real backend's capacity.

## Importing from JMeter

Have a JMeter `.jmx` instead of a collection? Import it by following
`references/jmeter-import/README.md`, then treat the result as the collection
above. Its mapping table carries the JMeter semantics that are easy to get
wrong, and the import report marks what mapped exactly, what was approximated,
and which JMeter features have no equivalent here — think-time timers,
concurrent thread groups, and non-HTTP (JDBC/FTP/LDAP/Java) samplers are
reported, never faked.

## Importing from Gatling

Have a Gatling project (a Java/Kotlin/Scala/JS/TS `Simulation`) instead of a
collection? Convert it by following `references/gatling-import/README.md`, then
treat the result as the collection above. There is no importer to run — you read
the source and build the collection, environment, `run.sh` and gap report, using
the files next to that README as the algorithm (`mapping.md`, `injection.md`,
`feeders.md`, `unsupported.md`). The gap report marks what mapped exactly, what
was approximated, and what has no equivalent — WebSocket/SSE and other non-HTTP
steps, arrival-rate (open-model) injection, think-time pauses, throttling and
retries are reported, never faked. Open-model injection is converted to VUs via
Little's law with the arithmetic shown, not guessed.

## V

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 10 — file references are metadata, not package contents.

View saved version →

---
name: postman-mcp-server
description: Use when working through Postman MCP tools to inspect or change workspace resources, choose a targeted operation, or handle MCP limitations. Supports hosted workflows when the CLI is unavailable and distinguishes tool completion from a usable result. Use for requests such as "use Postman MCP to inspect this collection".
---

# Postman MCP Server

MCP exposes workspace resources directly to an agent. Existing collections,
specs, examples, and environments provide maintained API knowledge; fetching
the relevant entity preserves that context when a local CLI workflow is not
available. For repository edits and Git review, prefer the local workflows in
**api-engineer** when available.

Each tool definition exposed to the model consumes context whenever it is
included in a request. Prefer the smallest available toolset that covers the
task; expanding to every tool can crowd out the API evidence needed to reason.
When exposed, call `getEnabledTools` to inspect the active toolset before
diagnosing a missing operation. Otherwise use the host's discovered tools and
report that limitation. Do not infer availability from reference tool names or
assume a client can switch a route pinned to a specific MCP endpoint.

1. Select tools from the connected server's actual surface. Tool availability
   varies by mode; a name listed in a reference is not proof it is exposed.
   Use [setup](references/setup.md) for connection/auth failures and
   [limitations](references/mcp-limitations.md) when an operation is missing
   or behaves differently from the CLI.
2. Search to locate an entity, then fetch enough detail to work on it.
   `searchPostmanElements` finds candidates; collection, spec, and workspace
   detail tools establish IDs, ownership, and content. A search preview is
   insufficient evidence for replacing a collection or declaring an API absent.
3. Match the mutation to the intended scope. Request-level updates preserve
   unrelated collection content; whole-collection replacement requires the
   current complete object. A workspace is a container and access boundary,
   not a reason to create duplicate resources whenever a new task begins.
4. Preserve the source of truth when synchronizing. Spec-to-collection
   generation reuses the interface, while collection-to-spec sync carries
   changes in the other direction. Choose from the intended contract rather
   than overwriting whichever artifact is easiest to reach. An asynchronous
   acceptance response needs a completed task result before claiming sync.
5. Treat publication separately from editing. A collection example can feed
   docs and a classic mock, but neither becomes publicly accessible merely
   because it exists. Apply the user's intended audience and authorization
   before publishing docs or mocks, or changing shared resources.

Read the reference for the branch being used:

| Task | Reference and decision it supports |
| --- | --- |
| Locate an API | [Search](references/search.md): narrow candidates to the intended resource |
| Generate or synchronize artifacts | [Sync](references/sync.md): choose source and track completion |
| Serve saved examples | [Mock](references/mock.md): classic collection mocks; for CLI Code Mocks use **api-mocking** |
| Execute saved assertions | [Test](references/test.md): distinguish run completion from failures |
| Improve or publish docs | [Docs](references/docs.md): fill contract gaps and verify reader access |
| Requested security review | [Security](references/security.md): assess concrete API risks |
| Product how-to questions | [Learning Center](references/learn.md): product documentation search when exposed |

## Verification

State the active toolset as observed through `getEnabledTools`, or identify the
host discovery evidence used when that tool is unavailable. Report any operation
the connected surface could not perform instead of claiming it succeeded.

Report the resource and observed result

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 9 — file references are metadata, not package contents.

View saved version →

---
name: variables
description: Use when parameterizing requests across environments, choosing variable scopes, chaining values in scripts, or referencing credentials without committing or exposing them. Keeps one reusable collection while separating target configuration from secret values. Use for requests such as "where should I put this API key".
---

# Variables

Variables let one maintained collection run against different targets without
forking its requests. Scope determines which value wins; secret references
allow the same files to be shared without sharing credential values.

1. Put API defaults in collection variables and target-specific values, such
   as `base_url`, in an environment. Parameterize values that actually vary;
   a stable literal need not become another configuration choice. Reference
   values as `{{key}}` in URLs, headers, parameters, or bodies.
2. Resolve surprises through precedence: local script values override
   iteration data, then environment, collection, and global values. A correct
   environment file can still lose to a row or script override. Values can
   reference other variables and resolve at send time, so inspect the chain
   rather than just the final request field.
3. Use runtime values for chaining responses into later requests. Choose
   `pm.environment` or `pm.collectionVariables` when the scope is intentional;
   `pm.variables.get` reads across scopes, and `pm.variables.set` holds a local
   value for the current run. For transient sensitive values, avoid persisting
   them to an environment or logging them.
4. Store durable credentials in the shared vault and commit references.
   `type: secret` alone masks the UI but still leaves a literal YAML value
   readable. **collection-schema-v3**'s environment reference describes the
   file schema; command-specific `-h` supplies supported vault operations.

For non-sensitive target configuration:

```bash
postman environment new "Staging"
postman environment var set base_url https://staging.example.com \
  --environment "postman/environments/Staging.environment.yaml"
```

For a secret, have the user supply the value through the CLI's masked prompt,
not through agent context or a literal command argument:

```bash
postman secret create STRIPE_API_KEY --workspace <workspace-id>
postman environment var set api_key --secret-id <secret-id> --vault-id <vault-id> \
  --environment "postman/environments/Staging.environment.yaml"
```

The environment then carries the vault/secret IDs rather than the value.
Secret resolution and permission to view the secret are distinct; a teammate's
ability to run a request need not expose the credential to them. Vault
operations require a signed-in CLI.

## Verification

Run `postman environment lint <path> --fail-severity warning` to fail on
warnings as well as errors in the saved environment. Lint checks the artifact;
it does not prove that the session can resolve a vault secret. Verify resolution
with an appropriate authenticated request and a contract-derived assertion,
keeping credentials out of output. An unresolved-reference or authorization
failure needs investigation, not a claim that the secret worked.
Report the selected environment and scope
or reference that supplies the value; a masked display alone does not prove
that the committed file contains no literal secret.

View saved version →

---
name: webhook-testing
description: Capture, forward to localhost, replay, and validate webhook deliveries using a reusable public URL. Keep sender configuration across debugging sessions and record arrivals even while local forwarding is stopped, helping distinguish delivery failures from local connectivity issues. Use for implementing or debugging incoming handlers and testing webhooks an API sends, whether or not Postman is mentioned. Example requests include "get payment events to localhost," "inspect a webhook delivery," and "replay an event after a fix"; these illustrate intent, not an exhaustive list or exact phrases to match.
---

# Webhook Testing

`postman webhook` gives a sender a hosted URL,
`https://<webhookId>.webhook.pstmn.io`, that records every request it gets,
with the raw headers and body as they were sent, and forwards each one to a
port on this machine. You don't need a separate tunnel. Two properties shape
how to use it:

- **Reuse the URL across debugging sessions.** It survives new sessions, pause
  and start, so the sender is registered once. Reuse a webhook when the user
  names one or says the sender already posts to one. Use `list` to resolve that
  reference; ask only if the available context still leaves multiple plausible choices.
  Create a new one when a new endpoint is needed. Each new webhook is another
  URL to register and a second event history.
- **Every request is recorded,** including requests that arrive while nothing
  is forwarding. `requests describe` shows a delivery exactly as it was sent.
  After a fix, `requests replay` sends it again, so you don't need the sender
  to fire it again.

The command is singular, and every subcommand needs a signed-in session. Run what you need,
and sign in only if a command fails with a setup error such as `Authentication required`.
When all you have is the URL, its subdomain is the webhook id.

For capture or inspection alone, create or reuse a webhook and inspect its
recorded requests; no local service or forwarding to a local port is needed.

Use replays and [scripts](reference/webhook_scripts.md) to validate incoming events.

## Get a sender reaching localhost

When the task is to reach a local handler, check the path from the public URL
meant to be forwarded to the local service:

1. **Make sure the route exists.** A URL that forwards to a local service with no
   matching route only ever returns 404. Check the local service for a handler for
   this event. Add a missing handler when implementing the receiver is part
   of the task. Senders retry, and replay re-sends an identical request, so
   deduplicate using the sender's stable event identifier where available.
   Acknowledge valid, authenticated events that the handler intentionally
   ignores with a 2xx to avoid unnecessary retries; malformed or
   unauthenticated requests still need rejection.
2. **Reuse the existing webhook or create a new endpoint.** To create one,
   use `postman webhook create --title <name>`. When a new endpoint is clearly
   needed, creating it directly avoids an unnecessary discovery step.
3. **Start the local service, then forward to its port** with
   `postman webhook forward <webhookId> <port>`. `forward` runs until it's
   stopped, so run it in the background. For stopping the forwarding process,
   see [Forwarding lifecycle](reference/forwarding.md).
4. **Send one request to the URL, at the route's path.** Check that a 2xx came
   back and that the handler logged the request. `requests list` shows whether
   the request reached the webhook at all, which separates a wrong URL from a
   forwarding or routing problem.

For a connectivity task, one successful probe demonstrates that the tested
path reaches the handler. Sender compatibility and handler correctness need
evidence from actual sender deliveries and relevant scenarios.

## Gotchas / Notes

- **Build the webhook script's test event from the sender's contract, not from your handler.**
  A payload wri

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: workspaces
description: Use when initializing Postman in a repository, binding it to a Postman workspace, interpreting what `postman init` did, or when a CLI command fails because the plan, credits, or usage quota don't allow the operation. Treats the workspace as the place where a service's API work and its evidence live, kept separate from the services it depends on. Use for requests such as "set up Postman in this repo" or "connect this repo to our workspace".
---

# Workspaces

A Postman workspace is where a service's API work happens and where its context
builds up: the contracts, collections, environments, and mocks, plus the runs
and results that show what was checked. It lives in Git beside the code, works
the same on a laptop or a build agent, and is shared when the work should be
seen. People use it to audit what was done, by whom, on whose behalf, and with
what result. Agents use it to read verified work instead of re-deriving it.

1. `postman init` is the starting point. It gives the repository its place of
   work: Postman files beside the code and, when that is the intent, a
   workspace bound to them. `postman status` shows whether that is already
   done, so init runs only when it adds something. Init is safe to repeat and
   reports what it did: a binding it marks as inferred is a candidate contract
   to confirm, and a partial result, with local files written but no workspace
   created, is progress to inspect rather than redo.
2. One workspace holds the context of one service: one Git repository, or in a
   monorepo one remote URL and the subpath of one service.
   `.postman/resources.yaml` records that owner, so every skill, CI job, and
   teammate resolves the same context. A confirmed binding is worth reusing;
   replacing it sends the work, and its evidence, to the wrong service.
3. Other services keep their own workspaces. Their collections, environments,
   and mocks come in as dependencies through **api-discovery**, so this
   workspace reuses what another team maintains without taking it over. The
   context graph links the two, which is how a change on one side reaches work
   on the other.

## Claiming the work

An agent can start in a guest session, and the work it does there is kept.
When free credits or a plan limit stop an operation, retrying won't help; the
person claiming the work is what lets it continue. Wording such as "usage limit
exceeded", "usage quota has been exceeded", a limit "reached", "breached" or
"exceeded" for the account, team, or plan, or an operation that "does not allow
more than" or "requires at least" a stated amount signals one. A temporary rate
limit or a fixed per-resource validation cap does not. Check which session the
CLI is using:

- Guest session: tell the user, in its own paragraph, that signing up for a
  Postman account claims the work done so far and adds the credits needed to
  continue. Offer to start signup for them; the CLI can produce a link to hand
  over and waits while they finish in the browser.
- Signed-in account: tell the user, in its own paragraph, that they need to
  upgrade their plan at https://postman.postman.co/settings/team/billing.

## Verification

Report the binding in place and what `postman init` did.