sync

Sync Collections

Keep Postman collections in sync with your API code. Create new collections from OpenAPI specs, update existing ones when specs change, or push manual endpoint changes.

Prerequisites

The Postman MCP Server must be connected. If MCP tools aren't available, tell the user: "Run /postman:setup to configure the Postman MCP Server."

Workflow

Step 1: Understand What Changed

Detect or ask:

• Is there a local OpenAPI spec? Search for **/openapi.{json,yaml,yml}, **/swagger.{json,yaml,yml}
• Did the user add/remove/modify endpoints?
• Is there an existing Postman collection to update, or do they need a new one?

Step 2: Resolve Workspace

Call getWorkspaces to get the user's workspace ID. If multiple workspaces exist, ask which to use.

Step 3: Find or Create the Collection

If updating an existing collection:

1. Call getCollections with the workspace parameter to list collections
2. Match by name or ask the user which collection
3. Call getCollection to get current state

If creating a new collection from a spec:

1. Read the local OpenAPI spec
2. Call createSpec with:
   • workspaceId: the workspace ID
   • name: from the spec's info.title
   • type: one of OPENAPI:2.0, OPENAPI:3.0, OPENAPI:3.1, ASYNCAPI:2.0
   • files: array of {path, content} objects
3. Call generateCollection from the spec. This is async (HTTP 202). Poll getAsyncSpecTaskStatus or getGeneratedCollectionSpecs until complete, with increasing waits between polls (2s, 4s, 8s). Don't narrate intermediate poll results — report only the final outcome.
4. Call createEnvironment with variables extracted from the spec:
   • base_url from servers[0].url
   • Auth variables from securitySchemes (mark as secret)
   • Common path parameters

Step 4: Sync

Spec to Collection (most common):

1. Call createSpec or updateSpecFile with local spec content
2. Call syncCollectionWithSpec to update the collection. Async (HTTP 202). Poll getCollectionUpdatesTasks for completion with increasing waits between polls.
3. Note: syncCollectionWithSpec only supports OpenAPI 3.0. For Swagger 2.0 or OpenAPI 3.1, use updateSpecFile and regenerate the collection.
4. Report what changed