README.md

Postman Reference

• Overview
  • Collection SDK vs API
  • YAML Files
• Getting Started
  • Prerequisites
  • Quick Start
• Authentication
  • API Keys
  • Collection Access Keys
  • Rate Limits
• API Sections
  • Workspaces
  • Collections
  • Environments and Variables
  • APIs
  • Mock Servers
  • Monitors
  • Comments
  • Forks
  • Pull Requests
  • User and Usage Data
  • Users and User Groups
  • Roles
  • Billing

Overview

Collection SDK vs API

The Postman platform offers two distinct tools for programmatic interaction:

Collection SDK

• Node.js module for programmatic collection manipulation
• Works locally without requiring API calls
• Focused on collection creation and modification
• SDK Documentation
• GitHub Repository
• Integration Guide

Postman API

• REST API service for Postman's cloud platform
• Requires authentication and internet connectivity
• Full access to platform features (workspaces, environments, monitors etc)
• API Documentation
• API Reference

While both follow the Postman Collection Schema, they serve different purposes:

• Use the SDK for local collection manipulation in development pipelines
• Use the API for cloud platform integration and team collaboration features

Example workflow: Generate collections with the SDK locally, then use the API to deploy to team workspaces and configure monitoring.

For detailed comparisons and use cases, see the Developer Tools Overview.

YAML Files

The YAML files in this directory are derived from the Postman API OpenAPI 3 specification. Files are organized by major section and named accordingly to facilitate work with Claude and AI tools.

Note: The #/ references can be found in the corresponding reference files. For example:

• collectionId is in docs/reference/postman-api-parameters
• Request/response objects for mergeEnvironmentFork are in postman-api-requestBodies.yaml and postman-api-responsesonly.yaml
• Schemas are in postman-api-schemasonly.yaml

Getting Started

Prerequisites

1. Access the Postman API collection
2. Generate an API key in Postman account settings
3. Store your API key securely:
   • Use Postman Vault for personal use
   • Use environment variables (secret type) for team sharing

Quick Start

1. Fork the Postman API collection to your workspace
2. Navigate to the User folder and locate the /me endpoint
3. Set your stored API key in the request headers
4. Send the request to verify authentication

For detailed instructions, see Making your first Postman API call.

Authentication

API Keys

• Generate API keys in your Postman account settings
• Include the API key in the X-API-Key header for all requests
• API keys provide access to all Postman resources you have permissions for
• Store API keys as postman-api-key variables to use with the Postman API collection

Collection Access Keys

• Generate collection-specific read-only access keys for API sharing
• Manage keys in the API keys page under "Collection access keys"
• Each key grants access to a single collection
• Keys can be revoked at any time

For detailed authentication documentation, see Postman API Authentication.

Rate Limits

Per-user rate limits: 300 requests per minute. Monitor usage through response headers and monthly allowances.

Rate limit information is available through response headers:

• Current window limits via RateLimit and X-RateLimit-* headers
• Monthly usage via RateLimit-Limit-Month and RateLimit-Remaining-Month
• Retry timing via RetryAfter when limits are exceeded

Resources:

• API Reference
• Documentation
• Usage monitoring
• Plan comparison
• Resource usage docs

API Sections

Workspaces

Manage Postman workspaces, including creating temporary test workspaces and backing up workspace resources.

• API Reference
• Documentation

Collections

Manage Postman Collections with operations for adding, deleting, and updating collections and their contents. Includes fork/PR management and OpenAPI import/export.

• API Reference
• Documentation

Environments and Variables

Manage Postman environments and variables (global and collection-level) for different deployment contexts.

• API Reference
• Documentation

APIs

Manage APIs and integrate with CI/CD systems. Features include API definition updates, version management, and collection synchronization.

• API Reference
• Documentation

Mock Servers

Create and manage mock servers with public/private settings, call logging, and error response management.

• API Reference
• Documentation

Monitors

Run collections programmatically based on CI/CD events and manage webhooks for collection execution.

• API Reference
• Documentation

Comments

Manage comments across APIs, collections, folders, requests, and responses.

• API Reference
• Documentation

Forks

Create and manage forks of collections and environments.

• API Reference
• Documentation

Pull Requests

Handle pull requests for collections, including creation, updates, and status management.

• API Reference
• Documentation

User and Usage Data

Access authenticated user information and account usage details.

• API Reference

Users and User Groups

Manage team users and groups with capabilities to retrieve team member and group details.

• API Reference
• Documentation

Roles

Define and manage user permissions for workspaces, collections, and other Postman elements.

• API Reference
• Documentation

Billing

Access billing account information and integrate with internal systems.

• API Reference