Full API lifecycle management through Postman. Sync OpenAPI specs to collections, generate typed client code, run API tests, create mock servers, publish documentation, audit security against OWASP Top 10, and discover APIs across workspaces. Requires the Postman MCP Server. Use this skill when the

Postman Agent Skill Full API lifecycle management through the Postman MCP Server. Sync specs, generate code, run tests, create mocks, publish docs, and audit security. Version : 2.0.1 Requires : Postman MCP Server Prerequisites This skill requires the Postman MCP Server to be configured. The MCP server exposes 111+ tools for interacting with Postman workspaces, collections, specs, environments, mocks, monitors, and more. Setup check : Call getAuthenticatedUser via MCP. If it succeeds, you're connected. If it fails, walk through Setup below. Important: MCP Tool Behavior Before using the workflows below, be aware of these behaviors: getWorkspaces returns ALL workspaces. For large organizations this can be 300KB+. If you already have a workspace ID, use getWorkspace(workspaceId) directly instead. getCollection default response is a lightweight map with itemRefs (folder/request tree). This is efficient for discovery. Only use model=full when you need complete request/response bodies, and be aware it can exceed 300KB for large collections. Prefer targeted getCollectionRequest and getCollectionResponse calls for specific endpoints. getTaggedEntities returns 404 for missing tags , not an empty array. Handle this gracefully. Tag functionality may require an Enterprise plan. runCollection returns aggregate results only (total requests, passed, failed, duration). It does NOT return per request detail or error messages. For debugging specific failures, examine individual requests with getCollectionRequest and getCollectionResponse after the run. searchPostmanElements only searches the PUBLIC Postman network , not private workspaces. Always search private workspace first with getCollections . Setup If MCP tools are not available or getAuthenticatedUser fails: 1. Get a Postman API key: Go to https://postman.postman.co/settings/me/api keys Click "Generate API Key", name it "Claude Code" Copy the key (starts with PMAK ) 2. Set the environment variable: Add to ~/.zshrc or ~/.bashrc to persist. 3. Verify: Call getAuthenticatedUser . On success, call getWorkspaces to list workspaces, then getCollections with the workspace ID to count resources. Present: Routing When the user's request involves Postman or APIs, match their intent to the correct workflow below. Always prefer these structured workflows over raw MCP tool calls. User Intent Workflow Import a spec, push spec to Postman, create collection from spec, sync, push changes Sync Collections Generate client code, SDK, wrapper, typed client, consume an API Generate Client Code Find API, search endpoints, what's available, discover APIs Discover APIs Run tests, check if tests pass, validate API, test collection Run Collection Tests Create mock server, fake API, mock for frontend, mock URL Create Mock Servers Generate docs, improve documentation, publish docs, API docs API Documentation Security audit, vulnerabilities, OWASP, security check API Security Audit Is my API agent ready?, scan my API, analyze spec for AI Use the postman api readiness skill Routing rules: 1. Specific workflows take priority. If intent clearly maps to one, use it. 2. Ambiguous requests: ask the user what they need. 3. Multi step requests chain workflows. "Import my spec and run tests" = Sync then Test. 4. Only use mcp postman tools directly for single targeted updates or when the user explicitly asks. Workflow: Sync Collections Keep Postman collections in sync with API code. Create new collections from OpenAPI specs, update existing ones, or push endpoint changes. Step 1: Understand What Changed Detect or ask: Is there a local OpenAPI spec? Search for /openapi.{json,yaml,yml} , /swagger.{json,yaml,yml} Did the user add/remove/modify endpoints? Is there an existing Postman collection to update, or do they need a new one? Step 2: Resolve Workspace If the user provides a workspace ID, call getWorkspace(workspaceId) directly. Otherwise, call getCollections with a workspace ID if known, or ask the user which workspace to use. Avoid calling getWorkspaces (no filter) on large org accounts as it returns all workspaces (300KB+). Step 3: Find or Create the Collection Updating an existing collection: 1. Call getCollections with the workspace parameter 2. Match by name or ask which collection 3. Call getCollection to get current state Creating from a spec: 1. Read the local OpenAPI spec 2. Call createSpec with workspaceId , name , type (one of OPENAPI:2.0 , OPENAPI:3.0 , OPENAPI:3.1 , ASYNCAPI:2.0 ), and files (array of {path, content} ) 3. Call generateCollection from the spec. This is async (HTTP 202). Poll getGeneratedCollectionSpecs or getSpecCollections until complete. 4. Call createEnvironment with variables from the spec: base url from servers[0].url Auth variables from securitySchemes (mark as secret ) Common path parameters Step 4: Sync Spec to Collection (most common): 1. Call createSpec or updateSpecFile with local spec content 2. Call syncCollectionWithSpec to update the collection. Async (HTTP 202). Poll getCollectionUpdatesTasks for completion. 3. Note: syncCollectionWithSpec only supports OpenAPI 3.0. For Swagger 2.0 or OpenAPI 3.1, use updateSpecFile and regenerate via generateCollection . 4. Report what changed Collection to Spec (reverse sync): 1. Call syncSpecWithCollection to update the spec from collection changes 2. Write the updated spec back to the local file Manual updates (no spec): 1. createCollectionRequest to add new endpoints 2. updateCollectionRequest to modify existing ones 3. createCollectionFolder to organize by resource 4. createCollectionResponse to add example responses Step 5: Confirm Workflow: Generate Client Code Generate typed client code from Postman collections. Reads private API definitions and writes production ready code matching the project's conventions. Step 1: Find the API 1. If workspace ID is known, call getWorkspace(workspaceId) to get the full inventory (collections, specs, environments) in one call. Otherwise ask the user which workspace. 2. Call getCollections with workspace parameter. Use name filter if specified. 3. If no results in private workspace, fall back to searchPostmanElements (public network only) 4. Call getCollection for the lightweight map (default, no model param) 5. Call getSpecDefinition if a linked spec exists (richer type info) Step 2: Understand the API Shape For each relevant endpoint: 1. Call getCollectionFolder for resource grouping 2. Call getCollectionRequest for method, URL, headers, auth, body schema, parameters 3. Call getCollectionResponse for status codes, response shapes, error formats 4. Call getEnvironment for base URLs and variables 5. Call getCodeGenerationInstructions for Postman specific codegen guidance Step 3: Detect Project Language If not specified, detect from the project: package.json or tsconfig.json TypeScript/JavaScript requirements.txt or pyproject.toml Python go.mod Go Cargo.toml Rust pom.xml or build.gradle Java Gemfile Ruby Step 3b: Check for Variable Mismatches Compare collection variables with environment variables. Common issue: collection uses {{baseUrl}} but environment defines base url (or vice versa). Flag any naming mismatches to the user before generating code, as these cause silent failures at runtime. Step 4: Generate Code Generate a typed client with: Method per endpoint with proper parameters Request/response types from collection schemas Authentication handling from collection auth config Error handling based on documented error responses Environment based configuration (base URL from env vars) Pagination support if the API uses it Code conventions: Match the project's existing style (imports, formatting, naming) Include JSDoc/docstrings from collection descriptions Use the project's HTTP library if one exists (axios, fetch, requests, etc.) Write to a sensible path (e.g., src/clients/<api name .ts ) Step 5: Present Workflow: Discover APIs Answer natural language questions about available APIs across Postman workspaces. Find endpoints, check response shapes, understand what's available. Step 1: Search 1. If workspace ID is known, call getWorkspace(workspaceId) directly. Otherwise ask the user. 2. Call getCollections with workspace parameter. Use name filter to narrow. 3. If sparse, broaden: searchPostmanElements as fallback (public network only, not private workspaces) Note: getTaggedEntities and getCollectionTags may return 404/403 on non Enterprise plans. Do not rely on these for discovery. Step 2: Drill Into Results For each relevant hit: 1. getCollection for overview (default returns lightweight map with itemRefs , not full payloads) 2. Scan endpoint names from the map to identify relevant folders/requests 3. getCollectionRequest for specific relevant endpoints (targeted, not bulk) 4. getCollectionResponse for specific response data 5. getSpecDefinition if linked spec exists Step 3: Present Found: Not found: Show closest matches and explain why they don't match. Multiple results: List collections with endpoint counts, ask which to explore. Workflow: Run Collection Tests Execute Postman collection tests, analyze results, diagnose failures, and suggest fixes. Step 1: Find the Collection 1. If workspace ID is known, call getWorkspace(workspaceId) directly. Otherwise ask the user. 2. Call getCollections with workspace parameter. Use name filter if specified. Step 2: Run Tests Call runCollection with the collection UID in OWNER ID UUID format (from getCollection response's uid field). If environment variables are needed: 1. Call getEnvironments to list available environments 2. Ask which to use or detect from naming convention 3. Pass the environment ID to runCollection Step 3: Parse Results Note: runCollection returns aggregate results only (total requests, passed/failed counts, duration). It does NOT include per request detail. Present what's available: If tests failed and per request detail is needed, examine the collection's test scripts and request definitions with getCollectionRequest to help diagnose. The user may also need to check the Postman app or a monitor run for detailed failure logs. Step 4: Diagnose Failures For each failure: 1. getCollectionRequest for full request definition 2. getCollectionResponse for expected responses 3. Check if API source code is in the current project 4. Explain expected vs actual 5. If code is local, find the handler and suggest the fix Step 5: Fix and Re run After fixing: offer to re run and show before/after comparison. Step 6: Update Collection (if needed) If the tests themselves need updating: updateCollectionRequest to fix request bodies, headers, or test scripts updateCollectionResponse to update expected responses Workflow: Create Mock Servers Spin up a Postman mock server from a collection or spec. Get a working mock URL for frontend development, integration testing, or demos. Step 1: Find the Source If workspace ID is known, call getWorkspace(workspaceId) directly. Otherwise ask the user. From existing collection: getCollections with workspace ID select target collection From local spec: Import first: 1. createSpec with workspace, name, type, files 2. generateCollection . Async (HTTP 202). Poll getGeneratedCollectionSpecs or getSpecCollections for completion. Step 2: Check for Examples Mock servers serve example responses. Call getCollection and check if requests have saved responses. If missing,