Managing Postman

Postman Management Skill

Manage Postman collections, environments, monitors, and API documentation via the Postman API.

Core Helper Functions

#!/bin/bash

# Postman API
POSTMAN_API="https://api.getpostman.com"
POSTMAN_KEY="${POSTMAN_API_KEY:-}"

# Postman API wrapper
postman_api() {
    local method="${1:-GET}"
    local endpoint="$2"
    shift 2
    curl -s -X "$method" "${POSTMAN_API}${endpoint}" \
        -H "X-Api-Key: ${POSTMAN_KEY}" \
        -H "Content-Type: application/json" "$@" | jq '.'
}

MANDATORY: Discovery-First Pattern

Always inspect the workspace and collections before performing operations.

Phase 1: Discovery

#!/bin/bash

echo "=== Workspaces ==="
postman_api GET "/workspaces" | jq '[.workspaces[] | {id, name, type, visibility}]'

echo ""
echo "=== Collections ==="
postman_api GET "/collections" | jq '[.collections[] | {id, name, owner, updated_at: .updatedAt}] | sort_by(.name)'

echo ""
echo "=== Environments ==="
postman_api GET "/environments" | jq '[.environments[] | {id, name, owner, updated_at: .updatedAt}]'

echo ""
echo "=== Monitors ==="
postman_api GET "/monitors" | jq '[.monitors[] | {id, name, schedule, lastRun: .lastRun.status}]'

Output Rules

• TOKEN EFFICIENCY: Target <=50 lines per output
• Always extract relevant fields from API responses
• Never dump full collection definitions -- summarize structure

Common Operations

Collection Management

#!/bin/bash
COLLECTION_ID="${1:?Collection ID required}"

echo "=== Collection Overview ==="
postman_api GET "/collections/${COLLECTION_ID}" | jq '{
    name: .collection.info.name,
    description: .collection.info.description,
    schema: .collection.info.schema,
    total_items: [.collection.item[] | .. | .request? // empty] | length,
    folders: [.collection.item[] | select(.item) | .name],
    variables: [.collection.variable // [] | .[] | {key, value: (if .type == "secret" then "***" else .value end)}]
}'

echo ""
echo "=== Request Summary ==="
postman_api GET "/collections/${COLLECTION_ID}" | jq '[.collection.item[] | {
    folder: .name,
    requests: [(.item // [])[] | {name, method: .request.method, url: (.request.url.raw // (.request.url | if type == "string" then . else .raw end))}]
}]'

echo ""
echo "=== Auth Configuration ==="
postman_api GET "/collections/${COLLECTION_ID}" | jq '.collection.auth // "No collection-level auth"'

Environment Variable Management

#!/bin/bash
ENV_ID="${1:?Environment ID required}"

echo "=== Environment Variables ==="
postman_api GET "/environments/${ENV_ID}" | jq '{
    name: .environment.name,
    variables: [.environment.values[] | {
        key,
        value: (if .type == "secret" then "***REDACTED***" else .value end),
        enabled,
        type: (.type // "default")
    }]
}'

echo ""
echo "=== All Environments Comparison ==="
for env in $(postman_api GET "/environments" | jq -r '.environments[].id'); do
    name=$(postman_api GET "/environments/${env}" | jq -r '.environment.name')
    vars=$(postman_api GET "/environments/${env}" | jq '[.environment.values[] | .key]')
    echo "${name}: ${vars}"
done

Monitor Run Analysis

#!/bin/bash
MONITOR_ID="${1:?Monitor ID required}"

echo "=== Monitor Details ==="
postman_api GET "/monitors/${MONITOR_ID}" | jq '{
    name: .monitor.name,
    collection: .monitor.collectionUid,
    environment: .monitor.environmentUid,
    schedule: .monitor.schedule,
    last_run: .monitor.lastRun,
    notifications: .monitor.notifications
}'

echo ""
echo "=== Recent Runs ==="
postman_api GET "/monitors/${MONITOR_ID}" | jq '{
    last_run_status: .monitor.lastRun.status,
    last_run_started: .monitor.lastRun.startedAt,
    stats: .monitor.lastRun.stats
}'

echo ""
echo "=== All Monitor Health ==="
postman_api GET "/monitors" | jq '[.monitors[] | {
    name,
    status: .lastRun.status,
    finished_at: .lastRun.finishedAt
}] | sort_by(.status)'

API Documentation

#!/bin/bash

echo "=== Published APIs ==="
postman_api GET "/apis" | jq '[.apis[] | {id, name, summary, created_by: .createdBy, updated_at: .updatedAt}]'

echo ""
echo "=== API Versions ==="
API_ID="${1:-}"
if [ -n "$API_ID" ]; then
    postman_api GET "/apis/${API_ID}/versions" | jq '[.versions[] | {id, name, releaseNotes}]'

    echo ""
    echo "=== API Schemas ==="
    for ver in $(postman_api GET "/apis/${API_ID}/versions" | jq -r '.versions[].id' | head -5); do
        postman_api GET "/apis/${API_ID}/versions/${ver}/schemas" | jq '[.schemas[] | {id, type, language}]'
    done
fi

echo ""
echo "=== Collection Documentation Links ==="
postman_api GET "/collections" | jq '[.collections[] | {name, id, docs_url: "https://documenter.getpostman.com/view/\(.owner)/\(.id)"}]'

Safety Rules

• Read-only by default: Only use GET requests for discovery and inspection
• Never delete collections or environments without explicit user confirmation
• Never expose secret-type environment variables -- always redact them
• Never overwrite environment variables without confirming current values first
• Fork before editing: Suggest forking collections before making structural changes

Output Format

Present results as a structured report:

Managing Postman Report
═══════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Common Pitfalls

• API key rate limits: Postman API has rate limits (60 requests/minute for free tier); batch requests
• Collection UIDs vs IDs: The API uses UIDs (owner-id format), not the short display IDs
• Environment scope: Environments are workspace-scoped; the same name in different workspaces are different environments
• Monitor timezone: Monitor schedules use UTC; confirm timezone when interpreting run times
• Variable precedence: Global < environment < collection < data variables; overlapping keys cause confusion