November 9, 2026
Most APIs were written for a human who reads the docs, squints at an error message, and tries again. An AI agent doesn’t do any of that well. It calls the endpoint your spec describes, and if the spec says nothing about what happens when an order is out of stock, the agent guesses. Guessed behavior in an agent loop becomes retries, hallucinated parameters, and a confused on-call engineer.
The Postman plugin for Claude Code is how I close that gap from inside the terminal. It gives Claude Code a set of skills that run the real Postman CLI for each step of API work: discover, design, mock, test, document, and gate. In this post, I’ll install it, then build a small orders API end to end with prompts you can copy. Along the way, I’ll point out where Claude Code’s own features (plan mode, hooks, subagents, and /goal loops with token limits) make the workflow tighter.
If you want the conference-talk version of the same idea, the Postman in the Terminal short talk boils it down to one sentence: a coding agent doesn’t need a UI. It needs a command per step, committed skills that say which command to run, and a gate it can’t edit. That’s the frame for everything that follows.
What you’ll need
- Claude Code, signed in
- Node.js 18 or later, which the plugin uses to set up the Postman CLI for you
- A Postman account. The free plan works, and local commands such as linting, mocking, and running a collection don’t require you to sign in. Only anything that touches the Postman cloud does.
- An empty directory with git init run in it
Install the plugin
Install the plugin from Anthropic’s official Claude Code plugin marketplace. Register the marketplace once, then install:
That’s the whole install. You don’t need to install the Postman CLI yourself. The plugin’s bootstrap skill checks for it the first time Claude needs it and installs it if it’s missing, so there’s no separate setup step.
The whole install is two commands. Illustrative terminal, shortened for readability.
Start a fresh Claude Code session so the plugin loads. The plugin also registers a hosted MCP server at mcp.postman.com. Run /mcp in the session, pick postman, and complete the sign-in flow in your browser. You only need this for the tools that talk to your Postman workspace, such as searching your team’s existing collections.
To confirm everything loaded, run /plugin and look for postman. Or ask Claude:
What the plugin gives Claude
On every startup, clear, and compact, a SessionStart hook injects a short instruction block telling Claude to route non-trivial API work through the postman:api-engineer skill. That skill is the entry point, and it hands off to the specialists:
The api-engineer skill bakes in the opinions that matter for this post. The contract comes first. Validate every change against the contract. Consider a mock before the implementation exists. Don’t push to the cloud without consent. I’d have written roughly the same rules on a whiteboard, which is why I trust it to run unattended on reversible work.
Set the ground rules once with CLAUDE.md
Skills tell Claude how to use Postman. CLAUDE.md tells it how your repo works. Run postman init once in the project, which links the repo to a workspace and commits the skills alongside your code so a teammate’s agent (or a CI job) gets the same guidance without installing anything:
Then add a short section to CLAUDE.md:
That last rule matters more than it looks. An agent under pressure to turn a red check green will happily loosen the check. Put the gate somewhere it can’t reach, and say so in writing.
Why the OpenAPI spec and v3 collections matter
Everything in this post hangs on two kinds of file, and the plugin is built around the idea that all Postman resources have a filesystem representation. An agent works best on files it can read, diff, and edit in small pieces. It works worst on a blob it has to load whole or a UI it can’t see.
The OpenAPI specification is the contract. It says what the API promises: operations, parameters, schemas, and the error cases. It’s also the first thing an agent reads, so its quality sets the ceiling on everything downstream. The mock, the tests, the docs, and the readiness score all derive from it. A vague spec produces vague mocks and a low score.
The v3 collection is the executable proof. In the git-native v3 format, a Postman Collection stops being one large collection.json and becomes a directory tree under postman/collections/. Every request, folder, and saved example gets its own YAML file:
That layout pays off in three ways when an agent is doing the work:
- Small diffs. Adding a test to one request changes one file. Pull request reviews show exactly that, and merge conflicts stay rare.
- Cheap context. Claude reads the one request it needs, not an entire collection, so tokens go to the work instead of to loading JSON.
- Saved examples are documentation. The .example.yaml files record what a 201 and a 409 look like. Examples are also the signal the readiness check rewards, so the same files serve humans, agents, and the score.
Two habits keep this working. First, the plugin ships a collection-schema-v3 skill with the exact schema and naming rules, and you should tell Claude to read it before it hand-edits anything under postman/. Second, lint what it writes, since a malformed YAML file fails silently in a way a UI never would. You don’t need to remember the commands. Ask Claude:
Underneath, Claude runs two Postman CLI commands: postman spec lint openapi.yaml -f error and postman collection lint "postman/collections/Orders API" -f error. The -f error flag makes only error-level findings fail the run. You’ll see the same commands again in the hook and the CI gate later, where nothing is prompting Claude to run them.
Keep the spec and the collection in the same repo as the code. When the three change in one pull request, review is one diff, and CI checks all three together.
Build an orders API with prompts and goals
I’ll use a small orders service as the running example. Each of the following steps has a goal, a prompt, and a note on what to look for. Paste the prompts as written, then adapt them to your own API.
Goal 1: check whether the API already exists
Before Claude writes anything, find out whether someone already solved this. That’s the api-discovery skill, and it answers from three different sources. They don’t share data, so a miss in one says nothing about the others.
Postman search matches the collections, specs, and mocks people have saved. The postman search command takes an --ownership flag. The default, organization, searches only your own workspaces. external searches everything outside your organization, which is where the Postman Public API Network lives. all searches both. Tell Claude to use all before it concludes that nothing exists, because a public or partner API is invisible at the default scope.
Orbit, which the api-discovery skill calls for you, goes a step further for third-party providers. Its search call returns candidates for your task, including their limits, and integrate turns the one you pick into a brief with the base URL, auth requirements, steps, and gotchas. That’s a lot less context than loading a vendor’s full OpenAPI specification to answer one question. Orbit doesn’t supply the provider’s credentials, so you still sign up for those yourself. The Context Graph is a separate engineering service map, which we’ll use in Goal 6.
Here’s a prompt that exercises the first two. The orders service is ours to build, but taking payment probably isn’t:
One prompt, three sources. Illustrative session; the exact calls Claude makes will vary with your workspace.
If something close exists, you’ve saved a service. If nothing does, you’ve confirmed the gap, and the Orbit brief gives Claude the integration details it would otherwise guess.
Heads up: Orbit support is in the latest api-discovery skill. If Claude doesn’t mention Orbit when you ask, update the plugin and start a new session.
Goal 2: write the contract first, in plan mode
Press Shift+Tab until Claude Code shows plan mode, then ask for the contract. Plan mode keeps Claude read-only while it proposes, so you review the design before a single file changes.
Approve the plan, and Claude writes openapi.yaml. Here’s the shape you’re aiming for. It’s a complete, runnable spec for the first two operations; ask Claude to add cancel the same way.
Look at what the spec tells an agent that a human would infer. The 409 says “do not retry.” The 404 says “check the ID.” Money is an integer in cents with the reason stated. The Idempotency-Key header makes retries safe, and the description says so. Those are the details that decide whether an agent recovers or spirals. The OpenAPI Specification gives you every field you need for this, and RFC 9457 gives you a machine-readable error shape so you don’t invent one.
Goal 3: unblock consumers with a mock that can fail
A client team (or another agent) shouldn’t wait for your implementation. The api-mocking skill generates a local mock server from the spec, and its request-time overrides make it possible to rehearse failure paths.
Two headers change what the mock returns per request: x-mock-scenario picks a named scenario, and x-mock-response-code forces a status.
Under the hood, Claude runs postman mock generate, postman mock run, and postman request. A mock is two files in postman/mocks/: a config.yaml and a default.js that’s a plain Node HTTP server. Because it’s ordinary code, Claude can read it, and you can too.
Heads up: there’s no hot reload. If Claude edits default.js, it has to stop and restart the mock for the change to show up. A good skill-aware session does this on its own, but if a response looks stale, that’s the first thing to check.
Goal 4: prove the contract with tests
Now write the checks that hold the implementation to the contract. The api-testing skill uses postman collection run for suites of pm.test assertions, and --use-mock points the run at the mock instead of a real backend.
The assertions Claude writes are standard Postman test scripts. The error-path one is the one I’d read most carefully:
Tests like this are the part of the contract an agent relies on most, because they describe the unhappy path. They’re also what turns “the mock says it works” into “the implementation matches the mock.” Point the same collection at your real service by swapping the base URL in the environment.
Goal 5: score the spec for agent readiness
This is the step that makes the workflow AI-native instead of merely automated. The ai-readiness skill scores a spec (or collection) on whether an agent can discover it, understand it, call it correctly, and recover from errors. Missing examples, undocumented errors, and ambiguous parameters all cost points.
The score lands in one of four buckets: Limited, Fair, Good, or Excellent, along with a confidence value that says how many signals it could measure. Ask Claude to report what the command printed rather than paraphrase it. The skill is written to do that, and it keeps you from nodding at a number the model rounded in its head.
Try breaking the spec on purpose. Delete the 409 response and rerun the check. The score should drop, and the recommendation should point straight at the missing error. That feedback loop is the fastest way I know to learn what agents need.
Goal 6: know what you’d break before you change it
Once an API has consumers, every change is a risk question. The Context Graph is an organization-wide map of your APIs and the services that depend on them, built from signals such as Postman workspaces and your repositories. It answers architecture questions that search can’t, because there’s no keyword for a dependency. api-discovery queries it with postman context-graph ask, which takes a plain-English question:
You rarely type that yourself. Ask Claude for the impact before it touches the contract:
Run this in plan mode and the order of operations is right: impact first, then a plan, then edits.
Treat the answer as a strong lead, not proof. The graph answers at the endpoint level, so it can tell you a consumer calls GET /orders/{orderId}, not which field that consumer reads. And “no consumer found” doesn’t mean safe, only that none was found. The safer change here is to keep the old field, add the new one beside it, and mark the old one deprecated.
Use Claude Code features, not just prompts
Prompts get you far. These features turn the workflow into something repeatable.
Plan mode for anything that changes the contract
You saw it in Goal 2. Use it any time a change touches openapi.yaml, because a contract change ripples into mocks, tests, and consumers. Reviewing a plan costs seconds. Reviewing a half-applied refactor costs an afternoon.
A hook that lints every spec edit
Hooks run on events you choose, outside the model, so they fire every time. This PostToolUse hook in .claude/settings.json lints the spec whenever Claude edits it, and feeds failures straight back so Claude fixes them in the same turn. Exit code 2 is what sends stderr back to Claude.
It needs jq installed. The hooks reference covers the other events if you’d rather lint on commit or at the end of a turn.
A subagent for an independent contract review
An agent reviewing its own work tends to approve it. A subagent starts with a clean context and only the tools you give it, which makes it a better reviewer. Save this as .claude/agents/contract-reviewer.md:
Then ask: Use the contract-reviewer subagent on my changes to openapi.yaml.
Pre-approve the safe commands
Claude Code asks permission before running shell commands, which is right by default and tedious for the commands you run forty times a day. Allow the read-only and local ones in .claude/settings.json, and leave anything that touches the cloud on the prompt:
Headless mode and CI as the gate the agent can’t edit
Claude Code runs non-interactively with claude -p, which is useful for scripted reviews. For the gate itself, though, I’d skip the model and run the Postman CLI directly in CI. A deterministic check can’t be talked out of failing.
postman collection run exits nonzero when a pm.test assertion fails, and --min-score fails the job when the readiness score drops under your threshold. The --use-mock flag needs a recent version of the Postman CLI, so check postman collection run -h on yours before relying on it. Pick a threshold your spec clears today, then raise it as you improve. If you want Claude to react to a failure, a second job can call claude -p "The api-gate check failed. Read the log and propose a fix" with a narrow --allowedTools list, and open the fix as a pull request for a human to review.
Use /goal to loop until an outcome is met
Everything so far is one prompt, one result. Some outcomes take several tries: get the collection run clean, or get the readiness score over a bar. For those, Claude Code’s /goal command sets a completion condition and keeps Claude working across turns until it’s met. After every turn, a separate small, fast model checks the condition against what Claude has shown in the conversation. If it isn’t met, Claude starts another turn. If it is, the goal clears.
That separate evaluator is the point. Claude doesn’t get to decide it’s finished. A fresh model reads the transcript and judges the condition, the same way a CI job judges an exit code.
Example: get the API fast and error-free
Say the orders service exists and the collection has a response-time assertion, such as pm.expect(pm.response.responseTime).to.be.below(300). Here’s a goal for getting it green:
The condition names one end state, how to prove it, what must not change, and when to give up. Illustrative session.
A goal doesn’t change your permission mode. In manual mode, Claude still stops to ask before any tool call your settings don’t already allow, which is why the allowlist from the previous section matters here. For an unattended run, start the session in auto mode on a branch you can throw away.
Here’s what makes that condition work:
- One measurable end state. Zero failed assertions in a run summary, which is something the CLI prints.
- A stated check. Claude has to run the collection and print the summary, because the evaluator can only judge what appears in the conversation. It doesn’t run commands or read files on its own.
- Constraints on the way there. Claude may change src/, not the tests. Without that sentence, the shortest route to green is deleting the assertion.
- An exit. The turn limit and the “no progress” clause bound the loop.
Example: raise the readiness score
The same shape works at the contract level, and it’s the most AI-native goal in this post:
Keep the token bill predictable
A goal runs without you prompting each step, so a vague one can run a long time. Set the limits before you start:
- Put a turn limit in the condition. or stop after 15 turns is a documented pattern. Claude reports progress against it each turn, and the evaluator judges it from the conversation.
- Add a no-progress clause. “Stop if two attempts in a row change nothing” ends a loop that’s spinning.
- Pick one metric. A goal like “make the API good” never resolves. “Zero failed assertions” does.
- Keep the output small. --bail ends a collection run at the first failure, so each turn reads a short result instead of a full report.
- Work on a branch. If the loop ends badly, you discard a branch.
- Check the meter. Run /goal with no arguments to see the condition, elapsed time, turns evaluated, and token spend. /goal clear stops it.
- Cap headless runs. In a script, claude -p "/goal ..." runs the whole loop in one invocation. Pair it with --max-turns and --max-budget-usd, which work in print mode only. Whichever limit hits first ends the run with a nonzero exit code, so a script can branch on it:
A turn here is one round trip that includes a tool call, and the budget is checked after each response, so spend can pass the cap by one response. Leave some headroom. Heads up: --max-budget-usd shows in claude --help on my machine, but --max-turns doesn’t, so check yours before you depend on it.
The evaluator itself runs on the small fast model and is typically negligible next to the main turns, so the spend to watch is Claude’s work, not the judging. A goal also stops by itself if the evaluator decides the condition can never be met, or if Claude goes several turns without using a tool.
When to use /loop instead
/goal converges: it runs until a condition holds. /loop repeats on a time interval, which suits watching rather than fixing. Use it to poll something that changes on its own:
Use /goal to fix a failing run, and /loop or a Postman Monitor to notice that it started failing. For anything that must run while your laptop is closed, a Monitor or CI job is the better tool.
Things to watch for
- Don’t let the agent push to your workspace. The plugin’s own rules say not to push without consent, and I’d back that with the deny rule above. Push from CI after merge instead.
- Report scores, don’t recompute them. Ask Claude to quote what ai-readiness printed. A paraphrased 82 has a way of becoming a “roughly 80.”
- Run -h before trusting a flag. The skills tell Claude to read the CLI’s help before using any flag with a default. Do the same when you copy commands from a blog post, including this one. Flags change between CLI versions.
- Check what gets reported. Some Postman CLI commands send run results and analytics to Postman by default. The plugin README lists which ones and how to opt out with --no-report-events. Read it before you run the plugin against a sensitive codebase.
- Mocks are not the service. A green run against a mock proves your tests match your contract. It says nothing about your implementation until you point the same collection at it.
What you’ve built
You now have a repository where the contract is a file, the mock and tests derive from it, the readiness score is a number you can track, a bounded goal can drive a failing run to green, and a CI job holds the line. Claude Code does the typing, the Postman CLI does the checking, and the rules sit in CLAUDE.md and the pipeline instead of in anyone’s memory.
What I like about this setup is how little of it is prompt engineering. The prompts above are plain requests. The reliability comes from the commands underneath being real, the skills being committed to the repo, and the gate living somewhere the agent can’t reach.
Install the plugin, then start with Goal 5 on an API you already have. Score its spec, read the recommendations, and fix the top three. You’ll learn more about what agents need from your API in ten minutes than from any checklist, including this one.
Resources
- Postman plugin for coding agents on GitHub
- Postman in the Terminal short talk and demo
- Postman CLI documentation
- Postman CLI installation
- Set up mock servers in Postman
- Postman API Context Graph
- Claude Code plugin module on Postman Liftoff
- Postman plugin api-discovery skill, including Orbit
- Claude Code hooks reference
- Claude Code subagents
- OpenAPI Specification
- Model Context Protocol
