Postman Knowledge Base

Core Postman concepts and MCP tool guidance for making better decisions when working with Postman APIs.

Core Concepts

• Collection: A group of API requests organized in folders. The primary unit of work in Postman. Contains requests, examples (saved responses), test scripts, and documentation. Think of it as a living API reference.

• Environment: A set of key-value pairs (variables) scoped to a context like dev, staging, or prod. Used to swap base URLs, auth tokens, and config without changing the requests themselves.

• Workspace: A container for collections, environments, specs, mocks, and monitors. Can be personal, team, or public. Most users have one primary workspace.

• Spec (Spec Hub): An OpenAPI or AsyncAPI definition stored in Postman. Can generate collections automatically and stay synced with them. The source of truth for API shape.

• Request: A single API call definition: HTTP method, URL, headers, body, query params, and test scripts. Lives inside a collection, optionally inside a folder.

• Response (Example): A saved example response for a request. Includes status code, headers, and body. Used by mock servers to know what to return and by documentation to show expected responses.

• Folder: A grouping within a collection, typically by resource (e.g., "Users", "Orders", "Products"). Can contain requests and nested folders.

• Tags: Labels on collections for categorization and search. Useful for finding related APIs.

• Monitor: A scheduled collection runner that checks API health. Runs on a cron schedule and alerts on failures.

• Mock Server: A fake API that returns example responses from a collection. Used for frontend development before the real API is ready, or for testing in isolation.

When to Use What

| Goal | Approach | |------|----------| | Push code changes to Postman | Spec Hub + sync (createSpec -> syncCollectionWithSpec) | | Consume a Postman API in code | Read collection + codegen (getCollection -> generate client) | | Find an API | Search private network (searchPostmanElementsInPrivateNetwork) or user's workspace (getWorkspaces + getCollections) or public network (searchPostmanElementsInPublicNetwork) | | Test an API | Run collection (runCollection with environment) | | Fake an API for frontend | Mock server (createMock from collection with examples) | | Document an API | Analyze collection completeness, fill gaps, improve descriptions | | Secure an API | Audit spec and collection against OWASP API Top 10 |

MCP Tool Selection Guide

Reading Data

• getWorkspaces -- List all accessible workspaces
• getCollections -- List collections in a workspace
• getCollection -- Get full collection detail (always use full model)
• getCollectionFolder -- Get folder contents
• getCollectionRequest -- Get request details (method, URL, body, params)
• getCollectionResponse -- Get saved example responses
• getEnvironment / getEnvironments -- Get environment variables
• getSpecDefinition -- Get the full OpenAPI/AsyncAPI spec
• getAllSpecs -- List all specs in a workspace

Writing Data

• createCollection -- Create new collection (cannot nest folders, use decomposed approach)
• createCollectionFolder -- Create folder in collection
• createCollectionRequest -- Create request in collection or folder
• createCollectionResponse -- Save example response
• createEnvironment -- Create environment with variables
• createSpec -- Upload OpenAPI spec to Spec Hub
• updateSpecFile -- Update an existing spec
• updateCollectionRequest -- Modify request details
• createMock -- Create mock server from collection

Syncing

• syncCollectionWithSpec -- Update collection from spec (async, OpenAPI 3.0 only)
• syncSpecWithCollection -- Update spec from collection changes
• generateCollection -- Generate collection from spec (async)

Running

• runCollection -- Execute collection tests

Searching

• searchPostmanElementsInPrivateNetwork -- Search private/org APIs (default)
• searchPostmanElementsInPublicNetwork -- Search public Postman network
• getTaggedEntities -- Find by tag

For detailed limitations and workarounds, see the companion file mcp-limitations.md.