🤖 Postman Collection AI Agent

An AI-powered CLI tool that automatically analyzes your backend code, detects API routes, groups them into smart folders, and imports a complete Postman Collection — in seconds.

📖 Why This Was Built

Every backend developer faces the same problem: after building an API, you have to manually create Postman Collections — naming every route, adding request bodies, setting up folders, configuring auth headers. For a project with 30-50 routes, this takes hours.

This tool solves that. Point it at any backend project and it automatically:

• Scans all files by content (not filename)
• Detects base paths from app.use() and combines with route paths
• Groups routes into smart folders (Authentication, Products, Orders...)
• Generates realistic request bodies based on route context
• Detects auth type (JWT, OAuth, API Key)
• Enhances routes with AI (names, descriptions, bodies)
• Imports the complete collection directly into your Postman workspace

⚡ Quick Start

# 1. Install
pip install postman-agent

# 2. Setup (one time only)
postman-agent setup
# → Choose LLM provider (Groq, Gemini, Ollama, OpenAI...)
# → Enter API key for chosen provider
# → Enter Postman API Key (free at postman.com → Settings → API Keys)

# 3. Generate from any project
cd your-backend-project
postman-agent generate --scan .

# Output:
# ✅ Found 53 routes!
# 📁 Authentication (7 routes)
# 📁 Products (5 routes)
# 📁 Orders (4 routes)
# 🚀 Imported to Postman!
# 🔗 https://go.postman.co/collection/xxxxx

🎯 Features

Every request includes:

• ✅ Proper HTTP method
• ✅ Full path with base URL ({{base_url}})
• ✅ Auth header (Bearer {{token}})
• ✅ Realistic request body
• ✅ Path params as variables ({{id}})
• ✅ Query params (?page=1&limit=10)
• ✅ Environment variables

🌐 Supported Frameworks

🤖 Supported LLM Providers

postman-agent generate --scan . --provider gemini
postman-agent generate --scan . --provider ollama --model deepseek-r1
postman-agent generate --scan . --provider openai --model gpt-4o

🛠️ CLI Commands

setup — Configure provider & API keys

postman-agent setup

providers — List all available providers

postman-agent providers

models — List models for a provider

postman-agent models --provider groq
postman-agent models --provider gemini

generate — Generate Postman Collection

# Scan entire directory
postman-agent generate --scan .

# Single file
postman-agent generate --file routes/auth.js

# Custom options
postman-agent generate --scan . \
  --provider gemini \
  --model gemini-2.0-flash \
  --base-url https://api.myapp.com \
  --token my_jwt_token \
  --name "My API Collection" \
  --output collection.json \
  --dry-run

watch — Auto re-generate on file changes

postman-agent watch --scan . --interval 5

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                  CLI Entry Point                     │
│              postman_agent/cli.py                    │
│                                                      │
│  • Smart file scanner (content-based)                │
│  • 15 LLM provider support                          │
│  • API key management (setup/update/delete)          │
│  • Watch mode (auto re-generate on changes)          │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│               LangGraph AI Agent                     │
│            postman_agent/agent/graph.py              │
│                                                      │
│  ┌─────────┐   ┌────────────┐   ┌──────────┐        │
│  │  agent  │──▶│ ai_enhance │──▶│ generate │──▶ END │
│  │  node   │   │    node    │   │   node   │        │
│  └─────────┘   └────────────┘   └──────────┘        │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│                Code Parser                           │
│           postman_agent/tools/code_parser.py         │
│                                                      │
│  1. detect_auth_type()    → JWT / OAuth / API Key    │
│  2. Extract base paths    → app.use('/api/auth', .)  │
│  3. Split by file         → per-file route extract   │
│  4. Combine paths         → /api/auth + /login       │
│  5. detect_folder()       → Authentication folder    │
│  6. generate_name()       → "Login", "Get Products"  │
│  7. extract_path_params() → :id → {{id}}             │
│  8. extract_query_params()→ ?page=1&limit=10         │
│  9. generate_body()       → Realistic request body   │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│              Postman Collection Builder              │
│           build_postman_collection()                 │
│                                                      │
│  • Groups routes into folders                        │
│  • Auth first (Authentication folder always first)   │
│  • Builds Postman v2.1 JSON format                   │
│  • Adds environment variables                        │
│  • Upsert by name (no duplicates)                    │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│               Postman API Import                     │
│           import_to_postman()                        │
│                                                      │
│  POST/PUT https://api.getpostman.com/collections     │
│  → Creates or updates collection                     │
│  → Returns collection URL                            │
└─────────────────────────────────────────────────────┘

🛠️ Tech Stack

🔑 API Keys Setup

Keys are stored securely at ~/.postman-agent/.env

📦 Installation with Extra Providers

# Default (Groq only)
pip install postman-agent

# With Gemini support
pip install "postman-agent[gemini]"

# With Ollama support
pip install "postman-agent[ollama]"

# All free providers
pip install "postman-agent[all-free]"

# Everything
pip install "postman-agent[all]"

🗓️ Changelog

v1.0.15 — Performance & Bug Fixes (Latest)

• Parallel LLM batching — 25 routes per batch, max 3 batches simultaneously (3x faster)
• LLM call timeout (60s) — no more infinite hangs
• Progress bar simulation window increased (120s) — accurate for large projects
• Duplicate route fix — method:path deduplication before and after AI enhancement
• userRoutes.js base path fix — app.use() now matches any variable name, not just *Routes/*Router
• Bare route folder fix — routes like GET /{{id}} now correctly inherit folder from base path
• Phantom route fix — bmap fallback only triggers when variable is declared in that file

v1.0.13 — Stability

• Single batch LLM call for all routes
• Removed unused file section helpers
• Tightened bmap variable matching

v1.0.12 — Multi-Provider LLM

• 15 LLM providers: Groq, Gemini, GLM, Ollama, Cerebras, SambaNova, Cloudflare, Together, Fireworks, HuggingFace, OpenRouter, OpenAI, Anthropic, Mistral, Cohere
• providers command to list all providers
• models command to list models per provider
• --provider and --model flags on generate/watch

v1.0.5 — Smart Collection

• Base path detection (app.use('/api/auth', authRoutes))
• Full path combining (/api/auth + /login = /api/auth/login)
• Smart folder grouping (Authentication, Products, Orders...)
• Human-readable route names (Login, Get All Products...)
• Path params as Postman variables ({{id}})
• Query params auto-detection (?page=1&limit=10)
• Realistic request body generation
• Auth type detection (JWT, OAuth, API Key)
• watch command for auto re-generation
• Upsert collections (no duplicates)

v1.0.3 — Multi-Framework Support

• FastAPI, Flask, Django support added
• Python AST parsing for accurate detection
• Content-based file detection (not filename)
• Fastify register() with prefix support

v1.0.1 — CLI Tool

• Python CLI package (postman-agent command)
• Auto-import to Postman via API
• Setup command for API key management
• PyPI package published

v1.0.0 — Foundation

• Basic Express.js route detection with Regex
• Simple Postman Collection generation
• LangGraph ReAct agent

🔗 Links

🤝 Contributing

See CONTRIBUTING.md for guidelines.

👨‍💻 Author

Hanzala Kashif — Full Stack Developer & AI Agent Builder

• 📧 hanzalakashif2003@gmail.com
• 💼 @Hanzzalaaa

📄 License

MIT License — feel free to use and modify!

⭐ If this saved you time, please star the repo! "# postman-ai-agents"