# Postman

> API lifecycle management through Postman. Discover collections, run tests, monitor APIs, validate schemas, and publish documentation across the complete API development workflow.

- **Type:** Skill
- **Install:** `agentstack add skill-sterlingchin-postman-claude-skill-postman-claude-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SterlingChin](https://agentstack.voostack.com/s/sterlingchin)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SterlingChin](https://github.com/SterlingChin)
- **Source:** https://github.com/SterlingChin/postman-claude-skill

## Install

```sh
agentstack add skill-sterlingchin-postman-claude-skill-postman-claude-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:**
1. ✅ Validate your API key and connection
2. 📁 Check your workspace configuration
3. 📊 Count your collections and resources
4. 💡 Suggest next steps if setup is incomplete

**First time setup validation:**
```bash
# 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:
```bash
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:
```bash
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:
1. Add `POSTMAN_USE_PROXY=true` to your `.env` file
2. Ensure your proxy allows connections to `api.getpostman.com`

## Getting Your Postman API Key

1. Go to https://web.postman.co/settings/me/api-keys
2. Click "Generate API Key"
3. Copy the key (starts with `PMAK-`)
4. 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:**
```python
# ✅ 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:

1. **Metadata** (always loaded): Skill name and description from YAML frontmatter
2. **SKILL.md** (loaded when triggered): This overview document
3. **Workflow files** (loaded as needed): Specific step-by-step instructions
4. **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:**
```bash
python /skills/postman-skill/scripts/list_collections.py
```

**Create a new collection:**
```bash
python /skills/postman-skill/scripts/manage_collections.py --create --name "My API Tests"
```

**Create an environment with auto-secret detection (v1.1):**
```python
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:**
```python
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:**
```python
# Automatically create a collection from your spec
result = client.generate_collection_from_spec(
    spec_id,
    collection_name="My API Collection"
)
```

**Generate spec from collection:**
```python
# 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:**
```bash
python scripts/manage_pet_store_spec.py
```

### Version Control Workflows (v1.1 - v10+ Required)

**Fork a collection:**
```python
# Create a fork for independent development
fork = client.fork_collection(
    collection_uid="12345-abcde",
    label="feature-new-tests"
)
print(f"Forked collection: {fork['

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SterlingChin](https://github.com/SterlingChin)
- **Source:** [SterlingChin/postman-claude-skill](https://github.com/SterlingChin/postman-claude-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-sterlingchin-postman-claude-skill-postman-claude-skill
- Seller: https://agentstack.voostack.com/s/sterlingchin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.