putCollection

Instructions

Implementation Reference

• tools/postman_tools.py:225-264 (handler)

  The PutCollectionTool class with its run_tool method that replaces collection contents via a PUT request to /collections/{collectionId}. This is the core handler for the 'putCollection' tool.

  class PutCollectionTool(ToolHandler):
      """Replace collection contents"""
      
      def __init__(self):
          super().__init__("putCollection")
      
      def get_tool_description(self) -> Tool:
          return Tool(
              name=self.name,
              description="Replaces collection contents using Postman Collection v2.1.0 format. Include ID values or they'll be removed and recreated. Max size 100MB.",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "collectionId": {
                          "type": "string",
                          "description": "Collection ID in format <OWNER_ID>-<COLLECTION_ID>"
                      },
                      "Prefer": {
                          "type": "string",
                          "description": "Use 'respond-async' for async update (returns 202)"
                      },
                      "collection": {
                          "type": "object",
                          "description": "Collection object in Postman Collection v2.1.0 format"
                      }
                  },
                  "required": ["collectionId"]
              },
          )
      
      async def run_tool(self, args: dict) -> list[TextContent]:
          collection_id = args["collectionId"]
          collection = args.get("collection", {})
          headers = {}
          if args.get("Prefer"):
              headers["Prefer"] = args["Prefer"]
          
          body = {"collection": collection}
          result = await postman_api_call("PUT", f"/collections/{collection_id}", body=body, headers=headers)
          return [TextContent(type="text", text=json.dumps(result, indent=2))]

• tools/postman_tools.py:231-253 (schema)

  The inputSchema definition for putCollection, defining parameters: collectionId (required), Prefer (optional, for async update), and collection (Postman Collection v2.1.0 object).

  def get_tool_description(self) -> Tool:
      return Tool(
          name=self.name,
          description="Replaces collection contents using Postman Collection v2.1.0 format. Include ID values or they'll be removed and recreated. Max size 100MB.",
          inputSchema={
              "type": "object",
              "properties": {
                  "collectionId": {
                      "type": "string",
                      "description": "Collection ID in format <OWNER_ID>-<COLLECTION_ID>"
                  },
                  "Prefer": {
                      "type": "string",
                      "description": "Use 'respond-async' for async update (returns 202)"
                  },
                  "collection": {
                      "type": "object",
                      "description": "Collection object in Postman Collection v2.1.0 format"
                  }
              },
              "required": ["collectionId"]
          },
      )

• tools/postman_tools.py:1831-1843 (registration)

  The register_all_tools function that instantiates and registers all tool handlers, including PutCollectionTool() on line 1842.

  def register_all_tools() -> list[ToolHandler]:
      """Register all Postman tool handlers"""
      return [
          # User Info
          GetAuthenticatedUserTool(),
          GetEnabledToolsTool(),
          
          # Collections
          CreateCollectionTool(),
          GetCollectionTool(),
          GetCollectionsTool(),
          PutCollectionTool(),
          DuplicateCollectionTool(),

• tools/postman_tools.py:21-67 (helper)

  The postman_api_call helper that handles HTTP communication with the Postman API. Used by PutCollectionTool to make the PUT request.

  async def postman_api_call(
      method: str,
      endpoint: str,
      body: dict | None = None,
      params: dict | None = None,
      headers: dict | None = None
  ) -> dict:
      """Make an API call to Postman API"""
      if not POSTMAN_API_KEY:
          raise RuntimeError("POSTMAN_API_KEY environment variable is not set")
      
      url = f"{POSTMAN_BASE_URL}{endpoint}"
      
      # Prepare headers
      request_headers = {
          "X-Api-Key": POSTMAN_API_KEY,
          "Content-Type": "application/json",
      }
      if headers:
          request_headers.update(headers)
      
      async with httpx.AsyncClient(timeout=30.0) as client:
          try:
              response = await client.request(
                  method=method,
                  url=url,
                  json=body,
                  params=params,
                  headers=request_headers
              )
              response.raise_for_status()
              
              if response.status_code == 204:
                  return {"success": True, "message": "Operation completed successfully"}
              
              return response.json() if response.content else {"success": True}
          
          except httpx.HTTPStatusError as e:
              error_detail = e.response.text
              try:
                  error_json = e.response.json()
                  error_detail = json.dumps(error_json, indent=2)
              except:
                  pass
              raise RuntimeError(f"Postman API error ({e.response.status_code}): {error_detail}")
          except Exception as e:
              raise RuntimeError(f"Request failed: {str(e)}")