OpenAI Codex has quickly become one of the most widely used coding agents out there, and it’s easy to see why: it writes real code, runs it, and keeps iterating until the tests pass. What Codex doesn’t know on its own is whether the API you’re calling actually behaves the way you think it does. It also has no way to tell whether a mock exists for the endpoint you haven’t built yet, or whether your team already solved this exact problem somewhere in a Postman workspace.
That’s why we’re thrilled to launch the Postman plugin for Codex today. It brings Postman’s agent skills straight into your Codex sessions. Ask it something like @Postman turn this OpenAPI spec into a working mock server, and it runs the actual Postman CLI underneath instead of Codex guessing at curl commands from memory. In this post, I’ll walk through the two ways to install it, then show two of the skills doing real work: discovering an API that already exists, and mocking one that doesn’t yet.
What you’ll need #
- OpenAI Codex (CLI, IDE extension, or the Codex app)
- Node.js 18 or later, if you’re installing through the Postman CLI
- A Postman account (the free plan works, and it’s only required once you push a mock or search a workspace)
Two ways to install the plugin #
The skill files live in one repository, postmanlabs/postman-plugin, and every install path points back at the same skills/ directory. That means the skills you get from the Postman CLI and the skills you get from the Codex plugin marketplace are identical. Pick whichever fits how you already work.
Option 1: Install with the Postman CLI
If you’d rather scaffold skills at the repository level, so both you and any headless agent working in that repo can use them, install the Postman CLI:
npm install -g postman-cli
Then, from a new or existing project:
postman init
postman init pulls the current skills from the Postman skills repository and writes them into your project, alongside SKILL.md files that tell Codex how and when to use them. It also links the repository to a Postman workspace, which is what search and context-graph need to find your team’s existing collections later. Skills drift over time, so check in on them with:
postman skills status
Run postman skills update when that command reports you’re behind. Add --strict in CI if you want a stale skill set to fail the build instead of quietly falling out of date.
Option 2: Install from the Codex plugin marketplace
If you’re working in a single Codex session and don’t need the skills committed to the repository, install the plugin directly:
codex plugin marketplace add postmanlabs/postman-plugin
codex plugin add postman@postman
Or skip the terminal: open Codex, go to Plugins, search for “Postman,” and select Add.
The plugin listing shows what it can do before you install anything: build a collection and run tests, mock a spec, or score an API for AI-readiness.
This path also wires up the MCP server at mcp.postman.com, so tool calls Codex makes against Postman are authenticated and traceable back to the plugin, not just the skill files sitting on disk.
Say hello with @Postman #
However you installed it, Codex now resolves @postman as a mention, the same way it resolves a file path or a task:
Typing @postman in Codex surfaces the plugin the same way it surfaces files, tasks, and other plugins.
Describe what you’re building, and the plugin recommends what it needs from there. You don’t have to know the underlying postman CLI commands. The skill files translate your request into the right ones and run them for you.
Find out if the API you need already exists #
Before Codex writes an integration from memory, it’s worth checking whether the API already exists, either as something your team built or as a public API someone else maintains. That’s the api-discovery skill. It combines three things: postman search for anything already in your Postman workspaces, context-graph for how services depend on each other, and Orbit for public third-party APIs that need no signup or API key to search.
@Postman I'm adding email receipts to checkout. Does an API for
sending transactional email already exist in our workspace, and
if not, what public provider APIs would fit?
If nothing turns up internally, the skill queries Orbit instead of guessing. Orbit’s search endpoint returns candidate public APIs, including what each one can’t do, not just what it can. Its integrate endpoint turns your chosen candidate into a task brief with auth requirements and known gotchas, using roughly 27 times less context than a full vendor OpenAPI spec. That matters more than it sounds: a vendor spec to answer “does this API support attachments” is a lot of context to burn on one yes-or-no question.
Before you let Codex act on a dependency question, ask it the blast-radius version too:
@Postman what depends on the billing-api collection, and what
would changing its response schema break?
context-graph ask reconciles Postman collections and specs with the GitHub repos and deployments connected through Agent Context, so the answer isn’t limited to what’s checked out locally. Treat what comes back as a lead worth verifying against source, not proof on its own; the graph refreshes nightly, so a service added yesterday won’t show up yet.
Mock the API before it exists #
The second skill worth trying first is api-mocking. It stands up a fake backend from a collection or an OpenAPI spec, running locally as a plain Node process, with per-request overrides for testing failure paths without touching a real server.
Here’s a real prompt and what Codex did with it:
One prompt, three mock scenarios, a git-native test collection, and a passing run, all from the api-mocking skill.
As part of the production readiness, I want to add local mocks
to test everything. @Postman can you add these and run the
initial test suite.
That produced three scenarios: default, empty-catalog, and catalog-unavailable. It also added a git-native collection with reusable assertions, an environment variable to point the running app at the mock instead of production, and npm run mock:test wired into the existing test suite. The run came back clean: 6 mocked requests, 16 assertions, 0 failures.
Once the mock is running, you can switch scenarios or send it to a teammate without writing a single Postman CLI command yourself. Just tell Codex what you need, like @Postman switch the checkout mock to the empty-catalog scenario or @Postman push this mock so QA can hit it, and the skill handles the rest.
Try it yourself #
Install the plugin, then ask it something specific instead of something generic:
@Postman does an API for [thing you're about to build] already exist in our workspace?@Postman turn this OpenAPI spec into a mock server with a scenario for a 500 error@Postman is this API agent-ready?
The last one runs the ai-readiness skill, which scores a collection or spec on exactly the kind of thing that makes this whole plugin worth having: whether an agent calling your API can recover when something goes wrong, not just when everything works.
Resources #
Install the plugin now, and let me know what the first thing you asked it to do was.