Postman Collection

A Postman Collection is a machine-readable collection of APIs for use in client, testing, and automation. Postman Collections provides a portable, machine-readable way of defining an API and making available for consumers via a Postman workspace or embedded via documentation and other websites. Collections bundle documentation, can be mocked, and work with the wider Postman platform ecosystem.

Also known as: Postman Collection, PMC, Collection v2.1

Standards

Postman (de facto) Postman Collection Format v2.1.0
Postman (de facto) Postman Collection Format v2.0.0
Postman (vendor) Postman API
OpenAPI Initiative OpenAPI 3.x (importable to/from collections)
Bruno (de facto) Bruno Collection Format (alternative, .bru files)
Kong / Insomnia (de facto) Insomnia Export Format (alternative)

Media Types

application/json — Postman Collections are distributed as JSON conforming to the v2.1 schema.

OpenAPI Expression

n/a (Postman Collection) — Collections are not OpenAPI, but Postman can import/export between OpenAPI 3.x and Collection v2.1.

Governance Rules

collection-schema-valid (Postman / Newman) — Collection must validate against the v2.1.0 JSON Schema.
collection-has-tests (Convention) — Every request should include at least one test script.
collection-no-hardcoded-secrets (Convention) — Use environment / vault variables instead of hardcoded tokens.
collection-uses-variables (Convention) — Base URLs and IDs should be variables, not literals.

Risk & Compliance

OWASP:

OWASP API Security Top 10: API8:2023 Security Misconfiguration — exported collections often contain secrets
OWASP API Security Top 10: API2:2023 Broken Authentication — bearer tokens checked into shared collections

Compliance:

SOC 2 CC6.1 — shared collections are an access-control surface
PCI DSS v4 Req. 3 — avoid storing cardholder data in example bodies

Security: Collections are frequently shared via public workspaces and Git — scan exports for secrets, store credentials in Postman Vault or environments marked private, and rotate any token that lands in a committed collection. Treat public workspace publishing as a release event.

Tools

Postman — Client / platform
Newman — CLI runner (Apache-2.0)
Bruno — Open-source client (alt format) (MIT)
Insomnia — Open-source client (MIT (core))
portman — OpenAPI-to-collection generator (MIT)
openapi-to-postmanv2 — OpenAPI-to-collection converter (Apache-2.0)

Suggested Metrics

collection_test_coverage — Share of requests in a collection that have test scripts.
newman_pass_rate — Share of requests passing in a CI run.
collection_freshness_days — Days since the collection was last updated.
collection_secret_leaks — Count of secrets detected by scanning the exported JSON.

Example Implementations

Twilio — Publishes official Postman Collections on the Postman API Network.
Stripe — Maintains a Stripe workspace with collections per product.
Salesforce — Publishes Salesforce Developers workspace with multiple collections.
PayPal — Publishes Postman Collections via the API Network.

Related Properties

Openapi
Postman workspace
Json schema