Collection Backups Made Easy with the Postman API

Learning Lab
, ,
1

Postman collections are valuable resources—protecting them with backups is a simple but powerful best practice. Whether you’re running automated processes that regularly update your collections or just want to prevent manual mistakes, having a backup can save you a lot of time and headaches. For example:

  • You have automatic processes that modify collections. If something goes wrong, you can quickly roll back to a working version.
  • There are accidental manual changes you want to revert.

The good news? Postman makes it easy to manually back up and recover deleted collections. Plus, with the Postman API, you can automate the process. Use the API’s GET and PUT collection endpoints, a transfer method, or try the pull source changes endpoint to programmatically keep copies of your collections up to date.

In this post, we’ll walk through each of these options to help you keep your collections safe and sound.

Using the /collections GET and PUT endpoints

The Postman API provides the GET and PUT /collections/{id} endpoints, which 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 with the Postman CLI.

Prerequisites

  • An empty collection in your workspace. This is your backup (destination) collection. During the process, the 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. Uses the GET /collections/{id} endpoint to get the source collection.
  2. Processes the GET response and removes all id, _postman_id, and uid fields.
  3. Runs the PUT /collections/{id} endpoint on the backup destination collection with an empty item list in the body. This cleans up the data in the destination collection.
  4. Calls the PUT /collections/{id} endpoint and uses the processed payload (without the ID fields), updating the destination collection with the contents.

Pros

  • Simple. It reads from the source collection and overwrites the destination collection.
  • Requires fewer requests to complete than the Transfers API method, so it’s best for small collections.

Cons

  • Requires some code in the collection scripts to remove the ID fields from the source collection’s response.
  • 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 PUT /collections/{id}/pulls endpoint

The PUT /collections/{id}/pulls endpoint lets you pull changes from a source collection into a forked collection. First, create a fork of the source collection you want to back up (you can also use the Postman API Create a fork endpoint). Then copy the forked collection’s ID.

After you’ve done this, just run the following curl command, replacing {{forkedCollectionId}} with the collection’s ID and $your-postman-api-key with a valid Postman API key:


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

--header 'x-api-key: $your-postman-api-key'

To avoid conflicts when you pull changes, make certain not to modify the forked collection. Also, for large collections, this request can take several seconds to complete.

Pros

  • This is the simplest and fastest way to keep a collection up to date, since it only pulls in changes. It just involves forking the original collection and then periodically updating your fork by pulling changes from the source.
  • 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’s Transfers endpoints enable you to move your collection’s 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 another collection.

This is a variation of the GET and PUT method, but instead of pulling the entire collection, it grabs just basic information. It uses the Postman API’s Transfers endpoints to copy that info step-by-step into the backup collection.

To make this process even easier, we’ve created a collection and environment you can fork and use to make backups of your collections.

Prerequisites

  • An empty collection in your 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. Retrieves the source collection data using the GET /collections/{id} endpoint and passes 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 especially useful for large collections, as it avoids loading the entire collection in a single request.

Cons

  • It’s a more advanced method that uses a complex collection and requires a bit of coding to set up.
  • It performs several requests to the Postman API, so your Postman API rate limits may apply.
  • It is a slower process versus the pull strategy.

Using the POST /collections/{collectionId}/duplicates endpoint

The Postman API’s POST /collections/{collectionId}/duplicates endpoint enables you to create a copy of any of your collections in a workspace.

Prerequisites

  • The collection UID of the collection you want to duplicate.
  • The ID of the destination workspace where you want the collection to be duplicated.

How it works

The collection duplicate operation is an asynchronous operation. The first step would be to send a request to the POST /collections/{collectionId}/duplicates endpoint:

curl --location --globoff 'https://api.getpostman.com/collections/{{collectionUid}}/duplicates' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: ••••••' \
--data '{
    "workspace": "{{workspaceId}}",
    "suffix": "{{suffixText}}"
}'

This operation receives the collection to duplicate, the workspace where we want to duplicate it, and the suffix to add to the duplicated collection name. The request returns a task ID you can use to check the status of the background duplication operation.

{
    "task": {
        "id": "12345678-d2584d81-3283-42d5-9d84-b897257adcf0",
        "status": "processing"
    }
}

The Postman API also offers the GET /collection-duplicate-tasks/{taskId} endpoint, which enables you to check the status of the background duplication operation. The status can be completed, in process, or failed.

Pros

  • This method enables the duplication of any collection, regardless of the size.
  • It’s an asynchronous method, not a long operation you have to wait for.

Cons

  • You need to check the status of the operation by using the task status endpoint.
  • The process always creates a new collection; you can’t overwrite an existing collection.

Next steps

The Postman API gives you full control to back up your collections programmatically, with several different ways to do it.

Depending on what you need, you can fork and pull updates or read and copy data using a few different strategies. We’ve walked through a few examples and shared some collection setups to help you get started.

Got your own use case for managing collections with the API? We’d love to hear about it—drop a comment below and share what you’re working on!

3 Likes