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 initrun in it
Install the plugin #
Install the plugin from Anthropic’s official Claude Code plugin marketplace. Register the marketplace once, then install:
claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install postman@claude-plugins-official
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:
Which Postman skills do you have available in this session?
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:
| Skill | What it does |
|---|---|
bootstrap |
Finds the Postman CLI, authenticates, and links the repo to a workspace |
api-discovery |
Searches your workspaces, finds public provider APIs through Orbit, and queries the Context Graph for dependencies |
api-mocking |
Generates and runs mocks from a spec or collection |
api-testing |
Runs single requests and collections with pm.test assertions |
api-documentation |
Generates agent-friendly docs |
ai-readiness |
Scores a spec or collection for how well an agent can use it |
ci-integration |
Adds lint, test, and readiness gates to your pipeline |
api-monitoring ,performance-testing ,flows |
Monitors, load tests, and Postman Flows |
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:
postman init
Then add a short section to CLAUDE.md:
## API work
- `openapi.yaml` is the contract. Change it before you change code.
- Make HTTP calls with `postman request`, not curl.
- Before you say a change is done, run `postman spec lint openapi.yaml`
and `postman collection run` against the mock.
- Never run `postman workspace push`. CI does that after merge.
- Never edit `.github/workflows/api-gate.yml` or lower a `--min-score`
threshold to make a check pass. Ask me.
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:
postman/collections/
Orders API/
.resources/
definition.yaml
create order.resources/
examples/
201 Created.example.yaml
409 Out of Stock.example.yaml
create order.request.yaml
get order.request.yaml
cancel order.request.yaml
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 JSON.
- Saved examples are documentation. The
.example.yamlfiles 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:
Read the collection-schema-v3 skill, then lint openapi.yaml and the Orders
API collection. Fix anything at error severity and run both linters again
until they're clean.
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.
| Source | Answers | Command |
|---|---|---|
| Postman search | “Does a collection, spec, or mock like this exist in our workspaces or on the Postman Public API Network?” | postman search <type> <query> --ownership all |
| Orbit | “Which public provider APIs could do this, and what can’t they do?” | search , thenintegrate |
| Context Graph | “What depends on this service, and who owns it?” | postman context-graph ask "..." --wait |
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 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:
I need an orders API with create, get, and cancel operations, and orders
need payment. Before we build anything: does either already exist in our
workspaces or on the Postman Public API Network? Search with --ownership
all. If there's no existing payments API, use Orbit to find public payment provider APIs that fit, and tell me
what each one can't do before you recommend one.
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.
Plan an OpenAPI 3.1 spec for an orders API: POST /orders, GET
/orders/{orderId}, and POST /orders/{orderId}/cancel. Design it so an
AI agent can use it without a human reading the docs. Every operation
needs an operationId and a description that says when to call it. Every
response needs an example, and every documented failure should use the
RFC 9457 problem details format.
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.
openapi: 3.1.0
info:
title: Orders API
version: 1.0.0
description: Create and look up customer orders.
servers:
- url: http://localhost:4010
paths:
/orders:
post:
operationId: createOrder
summary: Create an order
description: >
Call this to place a new order for one or more items. The call is
safe to retry when you send the same Idempotency-Key header.
parameters:
- name: Idempotency-Key
in: header
required: true
description: A unique string per order attempt, such as a UUID.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/NewOrder"
example:
customer_id: cus_8f3a21
items:
- sku: KB-104
quantity: 2
responses:
"201":
description: Order created.
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
example:
id: ord_71c9e4
status: pending
total_cents: 15800
"409":
description: An item is out of stock. Do not retry; reduce the quantity or remove the item.
content:
application/problem+json:
schema:
$ref: "#/components/schemas/Problem"
example:
type: https://api.example.com/problems/out-of-stock
title: Item out of stock
status: 409
detail: SKU KB-104 has 1 unit available, 2 requested.
/orders/{orderId}:
get:
operationId: getOrder
summary: Get an order
description: Call this to check the current status of an order you created.
parameters:
- name: orderId
in: path
required: true
description: The order ID returned by createOrder, such as ord_71c9e4.
schema:
type: string
responses:
"200":
description: The order.
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
example:
id: ord_71c9e4
status: shipped
total_cents: 15800
"404":
description: No order with that ID. Check the ID; don't retry.
content:
application/problem+json:
schema:
$ref: "#/components/schemas/Problem"
example:
type: https://api.example.com/problems/not-found
title: Order not found
status: 404
detail: No order with ID ord_000000.
components:
schemas:
NewOrder:
type: object
required: [customer_id, items]
properties:
customer_id:
type: string
description: The customer placing the order.
items:
type: array
minItems: 1
items:
type: object
required: [sku, quantity]
properties:
sku:
type: string
quantity:
type: integer
minimum: 1
Order:
type: object
required: [id, status, total_cents]
properties:
id:
type: string
status:
type: string
enum: [pending, shipped, cancelled]
total_cents:
type: integer
description: Order total in cents, to avoid floating-point rounding.
Problem:
type: object
required: [type, title, status]
properties:
type:
type: string
format: uri
title:
type: string
status:
type: integer
detail:
type: string
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.
Generate a local mock of this spec on port 4010 and run it. Then call
createOrder against it three ways: the default response, with the
x-mock-scenario header set to a scenario that simulates out of stock,
and with x-mock-response-code set to 500. Tell me what came back each
time.
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.
Create a Postman Collection in the v3 file format for this spec in postman/collections
with tests for the 201, 409, and 404 cases. Assert on status code, the
response shape, and that error responses use the problem+json content
type. Run it against the mock and show me the results.
The assertions Claude writes are standard Postman test scripts. The error-path one is the one I’d read most carefully:
pm.test("Out of stock returns problem+json", function () {
pm.response.to.have.status(409);
pm.expect(pm.response.headers.get("Content-Type"))
.to.include("application/problem+json");
const body = pm.response.json();
pm.expect(body).to.have.property("type");
pm.expect(body).to.have.property("title");
pm.expect(body.status).to.eql(409);
});
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.
Run the AI-readiness check on openapi.yaml. Report the score, bucket,
and confidence exactly as the command printed them, then list the three
changes that would raise the score the most. Apply them, and run it
again.
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:
postman context-graph ask "What could break if we change the Orders API?" --wait
You rarely type that yourself. Ask Claude for the impact before it touches the contract:
I want to rename total_cents to total_amount_cents in the Order
response. Use the Context Graph to find what depends on the Orders API
and what would break. Don't change anything yet. Tell me which
consumers you're sure about and which are guesses.
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.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "f=$(jq -r '.tool_input.file_path'); case \"$f\" in *openapi.yaml) postman spec lint \"$f\" -f error >&2 || exit 2;; esac"
}
]
}
]
}
}
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:
---
name: contract-reviewer
description: Reviews openapi.yaml changes for agent-readiness problems. Use after any spec edit.
tools: Read, Grep, Bash
---
You review OpenAPI changes for an AI-native API. Read the spec, then run
`postman spec ai-readiness openapi.yaml`. Report: operations missing an
operationId or a "when to call" description, responses without examples,
undocumented error cases, and ambiguous parameters. Do not edit files.
Return findings ranked by how likely they are to make an agent fail.
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:
{
"permissions": {
"allow": [
"Bash(postman spec lint:*)",
"Bash(postman spec ai-readiness:*)",
"Bash(postman collection run:*)",
"Bash(postman mock:*)",
"Bash(postman request:*)"
],
"deny": ["Bash(postman workspace push:*)"]
}
}
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.
name: API gate
on: pull_request
jobs:
gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm install -g postman-cli
- run: postman spec lint openapi.yaml -f error
- run: postman collection run "postman/collections/Orders API" --use-mock
- run: postman spec ai-readiness openapi.yaml --min-score 80
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:
/goal Run `postman collection run "postman/collections/Orders API" --bail`
against http://localhost:3000. Done when the run summary shows 0 failed
assertions, including the response-time test (under 300 ms). Print the
run summary every turn. Only edit files in src/. Do not edit anything
under postman/ or lower any threshold. Stop and report if 15 turns pass,
or if two attempts in a row change nothing.
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:
/goal `postman spec ai-readiness openapi.yaml --min-score 80` exits 0 and
`postman spec lint openapi.yaml -f error` is clean. Only edit openapi.yaml.
Don't add operations or remove responses. Show both command results each
turn. Stop after 12 turns.
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 turnsis 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.
--bailends 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
/goalwith no arguments to see the condition, elapsed time, turns evaluated, and token spend./goal clearstops it. - Cap headless runs. In a script,
claude -p "/goal ..."runs the whole loop in one invocation. Pair it with--max-turnsand--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:
claude -p --max-turns 25 --max-budget-usd 5.00 \
"/goal postman spec ai-readiness openapi.yaml --min-score 80 exits 0. Only edit openapi.yaml. Stop after 12 turns."
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:
/loop 30m Run `postman collection run "postman/collections/Orders API" --bail`
against staging and tell me only if something fails.
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-readinessprinted. A paraphrased 82 has a way of becoming a “roughly 80.” - Run
-hbefore 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. Theplugin 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.