Postman Agent Skill
Version: 1.1.0 (Phase 1 - Core API Compatibility) API Support: Postman v10+ (with v9 graceful degradation)
๐ Quick Start
When you first use this skill, Claude will automatically:
โ Validate your API key and connection ๐ Check your workspace configuration ๐ Count your collections and resources ๐ก Suggest next steps if setup is incomplete
First time setup validation:
Claude will run this automatically on first use
python scripts/validate_setup.py
Common first questions that work immediately:
"How many collections do I have?" - Lists all collections in your workspace "Show me my workspaces" - Displays available workspaces "Validate my setup" - Runs comprehensive diagnostics "Create a new collection called 'Test API'" - Starts building immediately
๐ค Note for Claude: On first use of this skill in a conversation, ALWAYS run:
python scripts/validate_setup.py
This provides immediate diagnostics and context before proceeding with the user's request.
โ Network Compatibility
This skill works across multiple Claude environments with proper proxy configuration.
Where This Skill Works Environment Status Notes Claude Web Interface โ Fully Supported Works with configured proxy Claude API (Code Execution) โ Fully Supported No network restrictions Local Python Scripts โ Fully Supported Direct execution on your machine Claude Desktop โ ๏ธ Limited Requires api.getpostman.com in network allowlist Proxy Configuration
The skill is designed to work with proxy environments:
Keeps proxy environment variables intact for proper DNS resolution Handles nested HTTP responses from proxy servers Supports HTTP/2 responses through proxies Debug mode available with POSTMAN_DEBUG=1 environment variable How to Use This Skill
Option 1: Claude Web Interface (Recommended) Use the skill directly in Claude web interface. The proxy is pre-configured and handles all network requests automatically.
Option 2: Claude API with Code Execution Use the skill through the Anthropic API with code execution enabled. This has no network restrictions.
Option 3: Local Python Scripts Run the scripts directly on your machine:
python scripts/list_collections.py python scripts/manage_collections.py --list
Overview
This skill gives Claude the ability to interact with the Postman API to manage the complete API lifecycle. It enables discovery of workspace resources, execution of test collections, monitoring analysis, and more.
What's New in v1.1 (Phase 1)
โจ Enhanced Error Handling: Custom exception classes with helpful resolution guidance ๐ Git-like Workflows: Fork collections, create pull requests, and merge changes ๐ Auto-Secret Detection: Automatically protects sensitive environment variables ๐ Smart Duplication: Copy collections and environments with full fidelity ๐ก API Version Detection: Automatic detection with compatibility warnings ๐ฏ Improved Developer Experience: Simplified APIs and better error messages
Capabilities Discover: List collections, APIs, specifications, environments, and monitors in your workspace Design: Manage API specifications, validate schemas, compare versions, and define APIs ๐ Spec Hub: Create and manage API specifications (OpenAPI 3.0, AsyncAPI 2.0) ๐ Multi-File Specs: Support for modular specifications with separate schema files ๐ Bidirectional Generation: Generate collections from specs or specs from collections Validate API schemas and compare versions Build: Create, update, and delete collections and environments ๐ Fork & Merge: Git-like version control for collections (v10+) ๐ Pull Requests: Collaborative collection editing workflows (v10+) ๐ Smart Duplication: Copy collections and environments with full metadata Test: Run collection test suites with Newman and analyze results Secure: Check authentication configuration and security settings ๐ Auto-Secret Detection: Automatically mark sensitive variables as secrets ๐ Secret Preservation: Maintain secret types across operations Deploy: Create and manage mock servers for API prototyping Observe: Create, manage, and analyze monitors for continuous API monitoring Distribute: View and assess API documentation quality When to Use This Skill
Claude should use this skill when you:
Mention Postman, collections, API specifications, or API testing Want to create or manage API specifications (OpenAPI, AsyncAPI, Swagger) Need to upload or import API specs to Postman Want to generate collections from API specifications Want to generate specifications from existing collections Want to validate API schemas or compare versions Want to create, update, or delete collections or environments Need to duplicate or organize collections and environments Ask to check authentication or security configuration Ask to create mock servers for prototyping Ask to run tests or check test results Want to see what APIs/collections/specs are available Need to create, manage, or analyze monitors Ask about API uptime, monitoring, or observability Want to check monitor status or run history Ask about API documentation quality or access Prerequisites
This skill requires a .env file with your Postman API key. The .env file should be included in the skill package and is automatically loaded when any script runs.
Important: If the skill is asking for an API key, it means the .env file is either:
Missing from the skill package Empty or incorrectly formatted Not readable by the scripts
To fix: Ensure the skill package includes a .env file with:
POSTMAN_API_KEY=PMAK-your-key-here
Optional configuration in .env:
POSTMAN_WORKSPACE_ID=your-workspace-id POSTMAN_RATE_LIMIT_DELAY=60 POSTMAN_MAX_RETRIES=3 POSTMAN_TIMEOUT=30
POSTMAN_USE_PROXY=false # Keep this false to bypass proxies (default)
Proxy Configuration (Important for Corporate Networks)
By default, the skill bypasses all proxy servers to avoid "403 Forbidden" proxy errors that commonly occur in Claude Desktop.
If you see errors like:
ProxyError: Unable to connect to proxy Tunnel connection failed: 403 Forbidden
The skill automatically handles this - no action needed. The latest version bypasses proxies by default.
If you're in a corporate environment and need to use a proxy:
Add POSTMAN_USE_PROXY=true to your .env file Ensure your proxy allows connections to api.getpostman.com Getting Your Postman API Key Go to https://web.postman.co/settings/me/api-keys Click "Generate API Key" Copy the key (starts with PMAK-) Add it to the .env file in the skill directory How to Use This Skill - IMPORTANT
โ ๏ธ CRITICAL: All Postman API calls MUST be made through Python scripts
This skill uses Python scripts to interact with the Postman API. DO NOT attempt to call api.postman.com directly using HTTP requests, as this will fail due to CORS (Cross-Origin Resource Sharing) restrictions in browser environments.
Always use the Python scripts:
โ CORRECT: Use Python scripts
python /path/to/postman-skill/scripts/list_collections.py
โ WRONG: Direct API calls will fail with CORS errors
fetch('https://api.getpostman.com/collections') # This will NOT work
Why this matters:
The Python requests library is not subject to CORS restrictions Direct browser-based API calls to api.postman.com are blocked by CORS All scripts automatically load your API key from the .env file Available Workflows Discover Resources
File: workflows/test/list_collections.md
List all collections, environments, and monitors in your workspace to understand what resources are available.
Validate API Schema
File: workflows/design/validate_schema.md
Validate API schemas against OpenAPI/Swagger standards. Check schema structure, retrieve API versions, and ensure API definitions are well-formed before deployment.
Compare API Versions
File: workflows/design/version_comparison.md
Compare different versions of an API to identify changes, breaking updates, and migration requirements. Essential for API governance and version management.
Manage API Specifications (Spec Hub)
File: workflows/design/manage_specs.md
Create and manage API specifications using Postman's Spec Hub. This is the modern, recommended approach for managing API definitions.
๐ New Features:
Create specifications directly (OpenAPI 3.0, AsyncAPI 2.0) Single-file and multi-file specification support Generate collections automatically from specifications Generate specifications from existing collections YAML and JSON format support Replaces the deprecated create_api() workflow Manage Collections
File: workflows/build/manage_collections.md
Create, update, delete, and duplicate Postman collections. Build new test collections, organize existing ones, and manage collection lifecycle programmatically.
๐ v1.1 Enhanced Features:
Fork collections for independent development Create and manage pull requests Merge changes from forks Duplicate collections with full metadata preservation Manage Environments
File: workflows/build/manage_environments.md
Create, update, delete, and duplicate Postman environments. Set up environment variables for different stages (dev, staging, production) and manage environment configurations.
๐ v1.1 Enhanced Features:
Automatic secret detection for sensitive variables (api_key, token, password, etc.) Partial updates that preserve existing secrets Duplicate environments with secret preservation Simplified dict-based API for quick environment creation Run Collection Tests
File: workflows/test/run_collection.md
Execute a collection's test suite using Newman and get formatted results showing passes, failures, and detailed diagnostics. Requires Newman CLI to be installed.
Check Authentication
File: workflows/secure/check_auth.md
Review authentication configuration in collections. Identify auth types, check security settings, and get recommendations for improving API security.
Manage Mock Servers
File: workflows/deploy/manage_mocks.md
Create, update, and manage mock servers for API prototyping and frontend development. Enable testing without backend implementation.
Manage Monitors
File: workflows/observe/manage_monitors.md
Create, update, delete, and analyze Postman monitors for continuous API monitoring. View monitor run history, success rates, and performance metrics to ensure API reliability.
View Documentation
File: workflows/distribute/view_documentation.md
Access and assess API documentation quality. Check documentation completeness, review endpoint descriptions, and get recommendations for improving docs.
Architecture
This skill uses progressive disclosure:
Metadata (always loaded): Skill name and description from YAML frontmatter SKILL.md (loaded when triggered): This overview document Workflow files (loaded as needed): Specific step-by-step instructions Python scripts (executed, not loaded): Actual API interaction code File Structure postman-skill/ โโโ SKILL.md # This file - skill overview โโโ workflows/ โ โโโ test/ โ โ โโโ list_collections.md # Discovery workflow โ โ โโโ run_collection.md # Test execution workflow โ โโโ design/ โ โ โโโ manage_specs.md # ๐ Spec Hub management workflow (NEW!) โ โ โโโ validate_schema.md # Schema validation workflow โ โ โโโ version_comparison.md # API version comparison workflow โ โโโ build/ โ โ โโโ manage_collections.md # Collection management workflow โ โ โโโ manage_environments.md # Environment management workflow โ โโโ secure/ โ โ โโโ check_auth.md # Authentication check workflow โ โโโ deploy/ โ โ โโโ manage_mocks.md # Mock server management workflow โ โโโ observe/ โ โ โโโ manage_monitors.md # Monitor management workflow โ โโโ distribute/ โ โโโ view_documentation.md # Documentation access workflow โโโ scripts/ โ โโโ config.py # Configuration management โ โโโ postman_client.py # API client with CRUD + Spec Hub operations (now uses curl) โ โโโ validate_setup.py # ๐ Comprehensive setup validation & diagnostics โ โโโ list_collections.py # Collection discovery script (enhanced with context) โ โโโ list_workspaces.py # ๐ Workspace discovery and navigation โ โโโ manage_collections.py # Collection management CLI โ โโโ manage_environments.py # Environment management CLI โ โโโ manage_pet_store_spec.py # ๐ Spec Hub example script (NEW!) โ โโโ manage_pet_store_api.py # Legacy API example (deprecated) โ โโโ run_collection.py # Newman test execution wrapper โ โโโ manage_monitors.py # Monitor management CLI โโโ utils/ โ โโโ retry_handler.py # Retry logic with backoff โ โโโ formatters.py # Output formatting (collections, monitors, runs) โ โโโ exceptions.py # ๐ Custom exception classes with helpful messages โโโ tests/ โ โโโ test_phase1_manual.py # ๐ Phase 1 test suite โ โโโ README.md # ๐ Testing guide โโโ docs/ โโโ assessment-report.md # ๐ Current state analysis โโโ api-compatibility-matrix.md # ๐ API endpoint coverage โโโ gap-analysis.md # ๐ Implementation roadmap โโโ compatibility-strategy.md # ๐ v10+ compatibility approach
Example Usage Basic Operations
List all collections:
python /skills/postman-skill/scripts/list_collections.py
Create a new collection:
python /skills/postman-skill/scripts/manage_collections.py --create --name "My API Tests"
Create an environment with auto-secret detection (v1.1):
from scripts.postman_client import PostmanClient
client = PostmanClient() env = client.create_environment( name="Production", values={ "base_url": "https://api.example.com", "api_key": "secret-key-123", # Auto-detected as secret! ๐ "bearer_token": "bearer-xyz-456" # Auto-detected as secret! ๐ } )
Spec Hub Workflows (NEW!)
Create an API specification:
import json from scripts.postman_client import PostmanClient
client = PostmanClient()
Create OpenAPI 3.0 spec
openapi_spec = { "openapi": "3.0.0", "info": {"title": "My API", "version": "1.0.0"}, "paths": {"/users": {"get": {"responses": {"200": {"description": "Success"}}}}} }
spec = client.create_spec({ "name": "My API", "description": "A sample API", "files": [{ "path": "openapi.json", "content": json.dumps(openapi_spec), "root": True }] }) print(f"Created spec: {spec['id']}")
Generate collection from spec:
Automatically create a collection from your spec
result = client.generate_collection_from_spec( spec_id, collection_name="My API Collection" )
Generate spec from collection:
Create a spec from an existing collection
result = client.generate_spec_from_collection( collection_id="collection-12345", spec_name="Generated API Spec" )
Run the complete example:
python scripts/manage_pet_store_spec.py
Version Control Workflows (v1.1 - v10+ Required)
Fork a collection:
Create a fork for independent development
fork = client.fork_collection( collection_uid="12345-abcde", label="feature-new-tests" ) print(f"Forked collection: {fork['uid']}")
Create a pull request:
Propose merging your changes
pr = client.create_pull_request( collection_uid="12345-abcde", # Parent collection source_collection_uid=fork['uid'], # Your fork title="Add authentication tests", description="This PR adds comprehensive auth test coverage" )
Merge a pull request:
Merge approved changes
client.merge_pull_request("12345-abcde", pr['id'])
Duplicate a collection:
Create a standalone copy (not a fork)
backup = client.duplicate_collection( collection_uid="12345-abcde", name="My Collection Backup" )
Validate API schema:
See: workflows/design/validate_schema.md
from scripts.postman_client import PostmanClient
client = PostmanClient()
schemas = client.get_api_schema(api_id="
Check authentication configuration:
See: workflows/secure/check_auth.md
collection = client.get_collection(collection_uid="
Create a mock server:
See: workflows/deploy/manage_mocks.md
mock_data = {"name": "API Mock", "collection": "
Run a specific collection:
python /skills/postman-skill/scripts/run_collection.py --collection="My API Tests"
List all monitors:
python /skills/postman-skill/scripts/manage_monitors.py --list
Analyze monitor run history:
python /skills/postman-skill/scripts/manage_monitors.py --analyze
Error Handling (Enhanced in v1.1)
All scripts include:
Custom Exception Classes: Specific exceptions for each error type AuthenticationError (401) - Invalid API key with setup instructions PermissionError (403) - Insufficient permissions with resolution steps ResourceNotFoundError (404) - Missing resources with possible causes ValidationError (400) - Request validation failures with details RateLimitError (429) - Rate limit exceeded with retry-after info ServerError (5xx) - Server errors with status page link NetworkError - Connection issues with troubleshooting steps TimeoutError - Request timeouts with configuration guidance Automatic retry with exponential backoff (3 attempts) Helpful error messages with resolution guidance API version detection with compatibility warnings Rate limit handling with automatic backoff Error Message Example
Before (v1.0):
Exception: API request failed with status 404: Resource not found
After (v1.1):
ResourceNotFoundError: Collection with ID '12345' was not found.
Possible reasons: - The resource was deleted - The ID is incorrect - You don't have permission to access it - The resource is in a different workspace
Security (Enhanced in v1.1) API keys read from environment variables only All operations scoped to configured workspace Rate limiting with automatic backoff No sensitive data logged or cached ๐ Automatic secret detection for environment variables ๐ Secret type preservation across updates and duplication ๐ 11 sensitive keywords monitored (api_key, token, password, bearer, auth, etc.) ๐ No accidental exposure of credentials in default-typed variables Limitations Runs in code execution container (no network access restrictions apply to API calls) Maximum 8MB skill size Uses pre-installed Python packages only Collection forking and pull requests require Postman v10+ API Some enterprise features may require paid Postman plans API Version Compatibility
This skill is optimized for Postman v10+ APIs but maintains graceful degradation:
Feature v9 API v10+ API Collections CRUD โ Best Effort โ Full Support Collection Forking โ Not Available โ Full Support Pull Requests โ Not Available โ Full Support Environments CRUD โ Best Effort โ Full Support Secret Variables โ ๏ธ Limited โ Full Support Custom Exceptions โ Full Support โ Full Support Version Detection โ Full Support โ Full Support
The client automatically detects your API version and will show warnings if v10+ features are unavailable.
Next Steps
After loading this skill (Claude Instructions):
ALWAYS run setup validation first: python scripts/validate_setup.py This provides immediate diagnostics and workspace context Identifies configuration issues proactively Shows collection counts and helpful next steps If validation fails: Check if POSTMAN_API_KEY is set in .env file Guide user to get their key from https://web.postman.co/settings/me/api-keys For "How many collections?" queries: Run python scripts/list_collections.py If 0 collections found, suggest: List workspaces: python scripts/list_workspaces.py Create new collection Switch workspace in .env file Execute specific workflows based on user requests
Helpful diagnostic commands:
Setup validation: python scripts/validate_setup.py List collections: python scripts/list_collections.py List workspaces: python scripts/list_workspaces.py List all resources: python scripts/list_collections.py --all Related Resources Postman API Documentation Workflow Files Example Responses