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.