Automate backups of your Postman Collections with the Postman API

Postman enables you to manually back up your data and recover deleted collections. While keeping backups of your Postman Collections is always a good idea under normal circumstances, it can be a real lifesaver when:

• You have automatic processes that modify collections. In such cases, you may want to back up collections before there are any changes. Then, if there’s an error, you can safely roll those changes back.
• There are accidental manual changes you want to revert.

But did you know that you can use the Postman API to programmatically maintain a copy of your collection? You can do it by using the Postman API’s GET and PUT collection endpoints, a transfer method, or the new pull source changes endpoint.

Using the /collections GET and PUT endpoints

The Postman API offers a GET /collections/{id} and PUT /collections/{id} endpoint that you can use to create a collection backup. These endpoints read a source collection and then update an empty destination collection with the source collection’s contents.

To simplify the process, we’ve created a collection and environment you can fork and run. You can also use this collection in your CI/CD environments using the Postman CLI.

Prerequisites

• An empty collection in a workspace. This will be your backup (destination) collection. During the process, this collection will be renamed to use the original (source) collection’s name.
• The empty backup collection’s ID.

How it works

When you run this collection, it:

1. Performs a GET of the source collection using the GET /collections/{id} endpoint.
2. Processes the GET response and removes all the id, _postman_id, and uid fields. This is necessary for the next step.
3. Runs a PUT /collections/{id} on the backup destination collection with an empty item list in the body. This cleans up all the data in the destination collection.
4. Runs a PUT /collections/{id} using the processed payload (without the ID fields) into the destination collection.

Pros

• It’s a simple process: it reads from the source collection and overwrites the destination collection.
• It requires fewer requests to complete than the Transfers API method, so it is best for small collections.

Cons

• It requires some code in the collection scripts to remove the ID fields from the source collection’s response.
• It performs several requests to the Postman API, so Postman API rate limits may apply.
• Not recommended for large collections because the process can take some time to complete.

Using the /collections/{id}/pulls endpoint

The PUT /collections/{id}/pulls endpoint lets you pull changes from a source collection into a forked (destination) collection. The process consists of a single request, which you can run with a cURL command:

curl --location --globoff --request PUT 'https://api.getpostman.com/collections/{{forkedCollectionId}}/pulls' \
--header 'x-api-key: PMAK-XXX'

Prerequisites

• Create a fork of the collection you want to back up.
• The forked collection’s ID.

How it works

Use the PUT /collections/{id}/pulls endpoint to pull changes from the source into the destination collection:

1. Fork the source collection in the Postman app or use the Postman API Create a fork endpoint.
2. Perform a pull changes request on the forked collection. To avoid conflicts when you pull changes, make certain that you don’t modify the forked collection. For large collections, this request can take several seconds to complete.

Pros

• This is the fastest and easiest way to update a collection because it only propagates changes. It consists of creating a fork of the collection and updating it periodically with a pull of the changes on the source collection.
• The process is a single API call that you can implement with a cURL request and integrate into your CI/CD processes without exceeding your Postman API rate limits.

Cons

• If the backup collection changes, the process may fail due to conflicts.

Using Transfers APIs

The Postman API has Transfers endpoints, which let you move collection items—such as requests and responses—between different collections and folders. These endpoints copy the collection’s items (folders and requests) from the source collection into a backup collection.

This is a variant of the GET and PUT method, but instead of retrieving all the collection contents, it just gets basic information about the collection. It uses the Postman API’s Transfers endpoints to iteratively copy that information into the backup collection.

We’ve created a collection and environment you can fork and use to make backups of your collections.

Prerequisites

• An empty collection in a workspace. This will be your backup (destination) collection. During the process, this collection will be renamed to use the original (source) collection’s name.
• The empty backup collection’s ID.

How it works

When your run this collection, it:

1. Retrieves the source collection data using the GET /collections/{id} endpoint and passing the model=minimal query string parameter. This returns all folders and requests located in the collection’s root level.
2. Performs a PUT on the destination collection using the previous data, but passes an empty item list. This copies the collection’s variables, scripts, and authorization information.
3. Loops over the rootLevelFolders property and uses the POST /collection-folders-transfers endpoint to copy each folder into the backup collection.
4. Loops over the rootLevelRequests list and uses the POST /collection-requests-transfers endpoint to copy each request into the backup collection.

Pros

• This method is best for very large collections because it does not process the entire collection in a single request.

Cons

• It’s an advanced process that requires some code and uses a complex collection.
• It performs several requests to the Postman API, so Postman API rate limits may apply.
• It is a slower process versus the pull strategy.

Next steps

The Postman API provides full CRUD capabilities that let you programmatically back up your collections into another collection in different ways.

Depending on your use case, you can fork and pull changes or read and copy the information using different strategies. We’ve shown you some possible scenarios and implemented some collections with these solutions.

Do you have any use cases related to collections that require managing them programmatically? We would love to hear about it—please let us know in a comment below!