Manage your Postman Collection’s items with the Postman API

David Espi Hernandez

October 17, 2023

You already know that you can create Postman Collections for your organization to create groups of saved requests to use for designing, testing, and documenting your APIs. And with the Postman API, you can programmatically manage your collections with the /collections endpoint.

But did you know that you can also manage the items within your collection—such as requests, folders, and responses—using the Collection Items endpoints? These endpoints let you modify the contents of a collection. We’ve recently included the Items folder in the Postman API’s Collections folder, and it’s where you can find all the available endpoints for managing collection items. We’ve also included examples that you can use to help you build your collection items, and we’ll be adding more over time as well:

Some examples of how you can leverage these endpoints include:

• Adding responses to existing requests: Use the Create a response endpoint to add a response to a collection’s request.
• Modifying requests and responses for large collections: Performing a PUT on a large collection can be troublesome, as large request bodies can result in performance issues or exceed the Postman API’s size limitations. In such cases, you’ll want to update only the requests or responses in your collection. You can use the Update a request and Update a response endpoints to manage them in your collections. With these endpoints, your payloads are much smaller than updating your entire collection.
• Updating the authentication of all requests in a folder to inherit from the parent: Use the Update a request endpoint to have the request inherit its authentication from the parent item or collection. To do this, set the auth, currentHelper, and helperAttributes values as null.
• Changing a test’s JavaScript code for several requests: Use the Update a request endpoint to programmatically update a request’s tests.

Next, let’s dive deeper into how you can automatically create requests and responses.

Using curl to create requests and responses

curl is a command-line tool for transferring data specified with a URL syntax. It’s a very popular tool for developers that can be used in scripts and in CI/CD environments. Postman can use curl to export requests. You can also import curl commands into Postman as a request.

We’ve created a command-line utility that parses output files coming from curl commands, then uses that data to create requests and responses on a specific collection with the Postman API. You can find the code that implements the command-line tool in the save-as-postman-request GitHub repository. It’s a JavaScript code (Node.js) that:

• Parses the curl output to extract all the request and response information needed, such as status code, headers, and the response body.
• Calls the Postman API to create the corresponding request and/or response.

We built this code as an example for this post, but Postman does not actively maintain this repository. Note: We do not recommend that you use it in production environments.

Before getting started with the following examples, make sure to save your Postman API key as a POSTMAN_API_KEY system environment variable.

These examples will use the Create a request and Create a response endpoints. Both of these endpoints provide examples of GET and POST requests you can reference for more information.

Creating a POST request and response

1. Save the request body in a REQUEST_BODY environment variable:

   export REQUEST_BODY=$(cat request_body_example.json)

   This is necessary because the curl output doesn’t contain the request body. If it isn’t provided, the request body will be empty in the requests and responses you create.

2. Run the following curl command. We’ll use this to save a response and all of its outputs to a curl_output.txt file:

   curl -v -X POST --location 'https://postman-echo.com/post' \
   --header 'Content-Type: application/json' \
   --data $REQUEST_BODY > curl_output.txt 2>&1

   Note that the command uses the verbose (-v) option. This is required, as we need as much information as possible to build the proper requests and responses.

3. Process the file with the following command. This creates a request in the collection specified in the collectionId argument:

   ./savePostmanRequest.js --inputFile curl_output.txt --collectionId 12345678-c05fb60e-bb28-4e7b-9cf7-55ada6ab320c --requestName 'Example from command line'
   

   The command’s response will look like the following:

   Request created with id e057b34d-04b7-543f-c69a-069b48a6617a
   Response created with id d2715ac5-b9b9-7e6f-e71d-e21040248939
   

Create a GET request and response

1. Run the following command. We use this to save a response and its output to a curl_output_get.txt file:

   curl -v -X GET --location 'https://postman-echo.com/get?param=value' \
   --header 'Content-Type: application/json' > curl_output_get.txt 2>&1
   

2. Process the file using the command. This creates a request and response in the collection specified in the collectionId argument:

   ./savePostmanRequest.js --inputFile curl_output_get.txt  --collectionId 12345678-c05fb60e-bb28-4e7b-9cf7-55ada6ab320c --requestName 'Example from command line get' --responseName='Get response'
   

3. The command’s response will look like the following:

   Request created with id 40310d86-2c98-f1a5-2b89-37506ed8f489
   Response created with id c8d4066a-b736-a001-73fd-ad8d72ed76e9
   

Adding a new response example to an existing request

You can also add new examples to an existing request by passing the --requestId argument to the command:

./savePostmanRequest.js --inputFile curl_output.txt  --collectionId 12345678-c05fb60e-bb28-4e7b-9cf7-55ada6ab320c --responseName='Another post response' --requestId=12345678-536730af-5663-15c7-0625-43c0d5b89030

The command’s response will include only the newly-created response’s ID:

Response created with id 973b0ed3-9d3d-9d72-8e1e-6b57d1524e1b

You can find more information about this command in the save-as-postman-request repository.

Your work with the Postman API

These are just a few examples of how you can automatically create requests and responses with the Postman API. Do you have a specific use case? How would you use the Postman API in your development process to keep your code in sync with your workspaces and collections? Feel free to leave a comment below telling us about your own use cases.