Postman # Postman Plugin **Powering API engineering for agents** The Postman plugin brings filesystem-first API development and organization-wide API context to coding agents. It enables agents to design, mock, test, document, monitor, and ship APIs directly from Claude Code, Cursor, and Codex. Every operation produces inspectable files or CLI commands that fit naturally into Git and CI, while the Postman Context Graph helps agents understand dependencies, ownership, runtime behavior, and the likely impact of a change. [Install](#install) · [Highlights](#highlights)
## Install Install Postman in every compatible coding agent detected on your machine: ```bash npx @postman/postman-plugin@latest ``` One command configures **Antigravity, Claude Code, Codex, GitHub Copilot CLI, Cursor, Factory Droid, Kimi Code, OpenCode and Pi**. Run it again to update, `status` to see what's installed, and `remove` to uninstall; `--agent ` limits any of them to one agent. Keep `@latest`: without it, npx runs any older copy of the installer installed globally or in the current project. To uninstall: ```bash npx @postman/postman-plugin@latest remove ``` `remove` uninstalls the plugin, then removes what it installed alongside it: the Postman marketplace in Claude Code, Codex, Copilot CLI and Factory Droid, once no plugin still installs from it; the approval of Postman's Codex session-start hook that releases before 0.7.2 wrote; and OpenCode's cached copy. Running it again cleans up what an earlier `remove` left behind. In Claude Code it also uninstalls a `postman@claude-plugins-official` copy, but never Anthropic's `claude-plugins-official` marketplace itself, nor another agent's settings, and it leaves project-scoped installs in place. Factory Droid lists project installs only for the current directory, so one elsewhere keeps working but stops getting updates once the marketplace is gone. Cursor Marketplace and Kimi Code installs can only be removed inside those apps; `remove` says how. You can also use the following commands to install individually: ### Antigravity ```bash agy plugin install https://github.com/postmanlabs/postman-plugin ``` Run the same command again to update; `agy plugin uninstall postman` removes it. In the Antigravity app, **Customizations → Plugins → + Install from URL** takes the same URL. ### Claude Code [View Postman on Claude Plugins](https://claude.com/plugins/postman) ```bash claude plugin marketplace add postmanlabs/postman-plugin claude plugin install postman@postman ``` This marketplace follows `main`, so versioned plugin releases reach you without waiting for Anthropic's catalog. Changes between version bumps do not update an already installed copy. Claude Code doesn't auto-update third-party marketplaces by default: turn it on under **/plugin → Marketplaces → postman → Enable auto-update**, and new versions install in the background once a session starts. The installer turns it on unless you already turned it off. If an existing `postman` marketplace is pinned to a tag, commit or another branch, the installer stops with instructions to switch it to `main` before proceeding. Postman is also listed in Anthropic's marketplace as `postman@claude-plugins-official`, which updates only when Anthropic merges a bump. Install one or the other: with both enabled, Claude Code loads every skill twice and runs only one copy's hooks. The installer uninstalls the official copy when it installs this one. Existing users need to rerun the installer above after the installer release containing this migration is published. Plugin auto-update alone does not switch marketplaces. Project and local installs stay in place; migrate those in their own projects to avoid continuing to load the official copy alongside this one. ### Codex [View Postman on ChatGPT Plugins](https://chatgpt.com/plugins/postman?open_in_app) ```bash codex plugin marketplace add postmanlabs/postman-plugin --ref main codex plugin marketplace upgrade postman codex plugin add postman@postman ``` These commands track `main`, and Codex updates the plugin from it when a session starts. ### Cursor [View Postman on the Cursor Marketplace](https://cursor.com/marketplace/postman) ```text /add-plugin postman ``` ### GitHub Copilot CLI ```bash copilot plugin marketplace add postmanlabs/postman-plugin copilot plugin install postman@postman ``` `copilot plugin marketplace update postman`, then `copilot plugin update postman`, updates it. Sign in to Postman's MCP server with `/mcp` inside a Copilot CLI session. ### Factory Droid ```bash droid plugin marketplace add https://github.com/postmanlabs/postman-plugin.git droid plugin install postman@postman-plugin --scope user ``` `droid plugin marketplace update postman-plugin`, then `droid plugin update postman@postman-plugin --scope user`, updates it. Sign in to Postman's MCP server with `/mcp` inside a Droid session. ### Kimi Code Inside a Kimi Code session: ```text /plugins install https://github.com/postmanlabs/postman-plugin/tree/main ``` Then run `/new` to start a session with the plugin. Run the same command again, then `/new`, to update; `/plugins remove postman` removes it. Sign in to Postman's MCP server with `/mcp-config login plugin-postman:postman`. ### OpenCode ```bash opencode plugin add github:postmanlabs/postman-plugin ``` That is OpenCode 2.0.4 or later. On OpenCode 1.14.33 or later the command is `opencode plugin --global github:postmanlabs/postman-plugin`. [opencode/README.md](opencode/README.md#install) has how to update and remove it, and the older clone-and-loader install. ### Pi [View Postman in Pi's package gallery](https://pi.dev/packages/@postman/postman-plugin) ```bash pi install npm:@postman/postman-plugin ``` `pi update npm:@postman/postman-plugin` updates it. Sign in to Postman's MCP server with `/mcp login postman` inside a Pi session. The shell's `pi mcp login` doesn't load extensions, so it reports no server named `postman`. ## Highlights ### Filesystem-first API development All postman resources have a filesystem representation, so your agent can work with the API ecosystem through the interface it understands best: files. API specifications, collections, environments, examples, mocks, documentation, and Flows can live beside the application code. The git-native [v3 collection schema](skills/collection-schema-v3/) makes this especially agent-friendly. A collection is a directory tree under `postman/collections/`, where every request, folder definition, and saved example is its own YAML file. Environments use the same file-first model under `postman/environments/`. HTTP, GraphQL, gRPC, WebSocket, Socket.IO, MQTT, MCP, and LLM requests all have defined schemas the agent can follow. That means the agent can: - Read or change one request without rewriting a large collection export. - Generate requests and examples directly from an API specification. - Produce small, reviewable Git diffs and resolve changes with normal code review workflows. - Lint and test the files locally before anything is shared with a Postman workspace. ### Context Graph: know what breaks before you make a change A repository can show what an endpoint calls, but rarely who calls it, whether those consumers are active in production, where they are deployed, or which team owns them. The Context Graph fills that gap with a private, authenticated, organization-wide map of your API ecosystem. It reconciles signals from the systems where API knowledge already lives: - **Postman workspaces:** specifications, collections, monitors, and mocks - **GitHub:** repositories, API definitions, and source-level call sites - **New Relic:** deployments, runtime traffic, latency, errors, and telemetry The [`api-discovery`](skills/api-discovery/) skill lets the agent start with the thing you plan to change and ask one natural-language question: ```bash postman context-graph ask "What could break if we change the billing API?" --wait ``` The graph discovers the surrounding scope—including repositories that are not checked out locally—before the agent starts editing code. It refreshes nightly as services, deployments, ownership, and runtime relationships change. In Postman's controlled benchmark across 468 repositories, starting with this map used **up to 74% fewer tokens, 52% fewer tool calls, and 72% lower cost**. Accuracy also improved in 18 of 21 scored prompt-model pairs. Most graph queries completed in roughly 20–40 seconds. Read the methodology and results in [Introducing the Context Graph API: One Map of Your API Ecosystem](https://blog.postman.com/introducing-the-context-graph-api-one-map-of-your-api-ecosystem/). ### File-first API mocks The [`api-mocking`](skills/api-mocking/) skill creates a working mock from an OpenAPI specification or collection and stores the implementation beside the API code. The agent can run it locally, add success and failure scenarios, and test consumers without waiting for the real service to be ready or available. The mock stays local until you choose to push and deploy it. When teammates or external systems need access, the same mock can become a durable hosted URL without rebuilding it in another tool. Pushed to the service's own workspace, it's the mock other teams' simulations pull first. ### Develop against simulated dependencies The [`api-simulation`](skills/api-simulation/) skill runs your code (a service you're changing, a frontend, a test suite or a demo) for real against stand-ins for the HTTP services it calls, served together on one port from one `.sim.yaml`. Each stand-in is the owning team's mock when they publish one. It reuses an existing `.sim.yaml`, proves a change with a request through the changed path, and answers "what happens if X goes down" by running each failure. Pushing the simulation is optional and needs your approval. It needs Postman CLI 1.70.0 or later: ```bash postman simulation run postman/simulations/orders-dev.sim.yaml --port 4900 ``` The service under test is never mocked. It runs for real, so a passing run shows the change works against what the mocks model; it doesn't replace a run against the real upstreams. The simulation can also run in CI, and any dependency can take injected latency, error, rate-limit, or chaos conditions to exercise failure paths. ## How Postman builds context `postman init` is idempotent and safe to run in any project. Run it before API engineering work to create the relevant local directories and make Postman skills available to guide the task, even if the project is already initialized. See [workspaces](skills/workspaces/SKILL.md) for init's workspace options and binding. Work done in a Postman folder produces artifacts: collection runs, lint results, request history, mock deployments. When that folder is connected to a Postman workspace after `postman init`, those artifacts are published to it as they are produced. The workspace persists that context for future work and enables teammates, reviewers, and other agents to share and build on what the agent did. What each command contributes to the connected workspace: | Command | What it publishes | | --- | --- | | `postman collection run` | Run results and run history | | `postman application test` | Test run results | | `postman spec lint` | Lint results, including violation counts and pass/fail | | `postman workspace push` | Local workspace contents, persisted as context for future work and sharing with others | | `postman runner start` | Runner processing and health activity | | `postman flows run` | Flow run results | | `postman request` | Agent's API interaction activity | Publishing happens by default. To change this workflow, you can set `--report-events=false` per invocation. ### Anonymous usage counts The CLI records command usage surface — a minimal, unauthenticated count with no workspace, user, or payload attached. ### The MCP fallback The plugin registers Postman's hosted MCP server as a fallback for when the CLI cannot run. MCP tool calls reach Postman by design and are not governed by the CLI flags above; skip installing the MCP server if you do not want that path. ## License Apache-2.0 — see [LICENSE](LICENSE).