AI prompts live or die on specificity. “Help me debug this auth issue” gets a different response than “I’m getting 401 errors on this collection; help me debug the auth, sync my environment variables, and validate OAuth 2.0 token expiration.” Same intent, very different output.
Postman’s prompting research calls this out: vague instructions are the single biggest reason AI output disappoints developers. The fix isn’t a smarter model. It’s a better prompt.
This is the problem Postman Agent Mode recipes solve. Recipes are pre-written prompt templates for common API tasks, covering everything from auth debugging to compliance audits. You drop one into the chat, swap in your collection or specification, and Agent Mode runs the task using your actual workspace context: your requests, environment variables, response bodies, and API specifications.
In this post, I’ll walk through four recipes I’ve found genuinely useful, explain the prompt patterns behind them, and show you how to write your own.
What Agent Mode does #
Before we get to recipes, a quick mental model. Agent Mode isn’t a chatbot that happens to know about HTTP. It runs inside your Postman workspace and has access to:
- Your collections and the requests in them
- Environment variables (secret values stay redacted)
- Live response bodies from requests you’ve sent
- API specifications in Spec Hub - Native Git history when connected
When you ask Agent Mode to “fix the auth on this collection,” it can inspect the headers, see which requests are failing, and propose changes. That’s the part recipes lean on: they assume the agent can read what you’ve built and act on it.
Recipe 1: Debug auth errors #
Auth is where most API integrations fall apart, and 401 errors are the loudest signal that something is off. The official Agent Mode Debug Auth Errors recipe starts with this prompt:
I'm getting 401 errors on this collection; help me debug the auth, sync my
environment variables, and validate OAuth 2.0.
What I like about this prompt is how it stacks three diagnostic steps in one go. Most 401 issues come from one of a handful of root causes: an expired access token, a missing Authorization header, a Bearer prefix typo, or an environment variable pointing at the wrong host. Asking the agent to walk all three explicitly means you don’t end up with a generic “check your credentials” response.
When I run this against a collection where the access_token
variable has gone stale, Agent Mode typically:
- Checks the token expiration claim in any JWT it can find
- Compares the
Authorization
header format across requests - Suggests refreshing the token using the OAuth 2.0 authorization helper
Worth noting: the recipe assumes you’ve set OAuth client credentials in an environment, not hardcoded them in a request. If you’ve stored secrets directly in a collection, the Postman Secret Scanner will catch it before Agent Mode does.
Recipe 2: Collection cleanup #
Collections get messy fast. Three engineers, two months, and you’ve got duplicate endpoints, half-renamed folders, and three different ways to call /users
. The Collection Cleanup recipe uses this prompt:
Find duplicate requests, identify redundant endpoints, and reorganize this
collection by grouping related requests into folders with descriptive names.
What the agent does here is interesting. It looks beyond identical URLs and matches on semantic similarity, so two requests hitting /api/v1/users/{id}
and /api/v1/users/:id
get flagged even though the path templating differs. It also reads request descriptions and method types to group related calls.
I ran this on a 60-request collection I’d inherited and ended up with:
Proposed changes:
- Merge 4 duplicate POST /users requests into 1 canonical version
- Group 12 requests into new folder "User management"
- Group 8 requests into new folder "Authentication"
- Mark 3 requests as deprecated (no longer in OpenAPI spec)
Apply changes? [y/N]
Always review the diff before applying. I once accepted changes that merged two requests that looked identical but had different test scripts. The cleanup removed scripts I needed.
Recipe 3: Broken documentation refresh #
API docs go stale faster than anything else in a codebase. The Broken Documentation Refresh recipe uses recent test runs as the source of truth:
Analyze my latest test results and schemas to generate comprehensive API
documentation with interactive examples and current response shapes.
This is a meaningfully different approach from generating docs out of a static specification. Instead of trusting the OpenAPI file, the agent reads recent responses from your collection runs and writes the docs around what the API returns in practice. If your spec says one thing and the response says another, the docs end up matching the response.
The output goes into a markdown file you can publish through Postman Docs or commit to your repo. The interactive examples are real requests with sanitized response bodies, not placeholder JSON.
Recipe 4: Compliance audit #
This one is the most opinionated and the most useful for anyone shipping to a regulated industry. The Compliance Audit recipe:
Implement security testing and compliance checks for GDPR and HIPAA; validate
role-based access control, scan for exposed secrets, and check sensitive
data handling in request and response bodies.
The recipe scans for a few patterns:
- Hardcoded secrets in request URLs, headers, or bodies (anything matching a known token format)
- Personally identifiable information in test data, like email addresses or phone numbers that aren’t redacted
- Missing RBAC tests for endpoints that should enforce role boundaries
- Sensitive fields returned in response bodies without redaction
This is where the Postman API Governance rules come in. If your team has custom governance rules defined, the audit checks against those too. I’ve used this to find an internal API where the staging environment had a real customer email in the test body. Embarrassing, but useful to catch before it hit production logs.
Write your own recipe #
The official recipes are starting points. Once you see the pattern, you can write your own.
A good recipe has three parts:
The task, stated specifically. Not “test my API” but “test all GET endpoints in this collection for 200/404/500 responses and check that response times stay under 250ms.”The context, scoped to what the agent should look at. Mention the collection name, the environment, or specific folders. Use@
in the chat to reference them directly.The output format, when it matters. “Return a markdown table with endpoint, expected status, actual status, and response time.”
Here’s one I use for a personal project:
@MyAPI Run a load test against the /search endpoint at 50 requests per second
for 30 seconds. Use the queries in test-queries.csv. Report p50, p95, and p99
response times in a markdown table. Flag any 5xx responses with the full
request and response body.
The result is specific, scoped, and clear about what to return. The agent has everything it needs to give a useful answer the first time.
Gotchas I’ve hit #
A few things I’ve learned the hard way running these:
Agent Mode uses AI credits. Every recipe consumes Postman AI credits, and the more complex recipes (compliance audits, server scaffolding) can use a lot. Check your usage before running batch operations on large collections.
The agent will modify your collection if you let it. Always review proposed changes before approving. Collections are versioned in Native Git, so you can roll back, but it’s faster to read the diff first.
Secrets stay safe, but test data doesn’t. Environment variables marked as secrets are redacted from prompts. Test data in your requests is not. If you have customer PII in test bodies, the agent sees it.
Try it yourself #
The fastest way to get a feel for this is to run a recipe against an existing collection. If you don’t have one handy, fork the Postman Echo collection into your workspace.
Then open Agent Mode in Postman (the chat icon in the workbench), paste in one of the recipe prompts from the official recipes page, and see what it does.
Worth running the cleanup recipe first on a low-stakes collection. It gives you a feel for the diff review flow without risking anything important. Once you trust the output on a sandbox collection, the auth debugging and compliance audit recipes are worth running on something you actually ship.
Resources #
Postman Agent Mode overviewAgent Mode recipes catalogSeven best practices for writing high quality promptsPostman AI credits and billingPostman API GovernanceNative Git in PostmanOAuth 2.0 RFC 6749OpenAPI specification