postman-claude-code-plugin/commands/sync.md

description, allowed-tools

description	allowed-tools
Sync Postman collections with your API code. Create collections from specs, push updates, keep everything in sync.	Bash, Read, Write, Glob, Grep, mcp__postman__*

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.
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.
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

Collection to Spec (reverse sync):

1. Call syncSpecWithCollection to update the spec from collection changes
2. Write the updated spec back to the local file

Manual updates (no spec): For individual endpoint changes:

1. createCollectionRequest to add new endpoints
2. updateCollectionRequest to modify existing ones
3. createCollectionFolder to organize by resource
4. createCollectionResponse to add example responses

Step 5: Confirm

Collection synced: "Pet Store API" (15 requests)
  Added:    POST /pets/{id}/vaccinations
  Updated:  GET /pets — added 'breed' filter parameter
  Removed:  (none)

  Environment: "Pet Store - Development" updated
  Spec Hub: petstore-v3.1.0 pushed

Error Handling

• MCP not configured: "Run /postman:setup to configure the Postman MCP Server."
• MCP timeout: Retry once. If generateCollection or syncCollectionWithSpec times out, the spec may be too large. Suggest breaking it into smaller specs by domain.
• 401 Unauthorized: "Your Postman API key was rejected. Generate a new one at https://postman.postman.co/settings/me/api-keys and run /postman:setup."
• Invalid spec: Report specific parse errors with line numbers. Offer to fix common YAML/JSON syntax issues.
• Async operation stuck: If polling shows no progress after 30 seconds, inform the user and suggest checking the Postman app directly.
• Plan limitations: "Workspace creation may be limited on free plans. Using your default workspace instead."