Create and manage request collections in Postman

Learn how to create and manage Postman Collections, use collections in development workflows, apply collection templates, and save multi-protocol requests into collections.

Creating collections

There are several ways to create a new collection:

• Select Collections in the sidebar, then select +.

  

• Select New, then select Collection.

• With Collections open in the left sidebar, select +.

• In an empty workspace, select Create Collection.

• You can also create a collection from a template.

To customize and configure a new collection, do the following:

1. Select the collection name to give your new collection a name.
2. You can optionally enter a description for your collection in the Overview tab. This description will appear in its documentation and in the workspace when anyone opens it.
3. Select Authorization to configure authorization details for the collection.
4. Select Pre-request Script to define a pre-request script for your collection, which will run before requests are sent to the server.
5. Select Tests to define a test script for your collection, which will run after a response is received.
6. Select Variables to define values for collection variables to share across all requests in the collection.

You can turn on autosave to automatically save your changes to collections, requests, and environments. Learn more about autosave.

Adding requests to a collection

There are several ways to add existing and new requests to a collection.

Moving an existing request to a different collection

To move an existing request to a different collection, do the following:

1. Select the request you want to move.
2. Drag the request into the desired collection.

Alternatively, open the request and select Save As, then choose the collection you want to copy it to.

To move more than one request to a different collection, do the following:

1. Press and hold ⌘ or Ctrl, then select the requests you want to move.
2. Drag the requests into the desired collection.

Adding a new request to a collection

1. From a new request, select Save.
2. Choose the collection you want to move it to, and then select Save.
3. To create a new collection to save the request to, select New Collection.

Creating a new request inside a collection

1. Select the more actions icon next to the collection name.

2. Select Add Request from the actions menu.

   

Adding a request to an empty collection

Select the collection, then select Add a request.

Adding a request from your history to a collection

1. Select History in the sidebar.

2. Select the more actions icon next to the request you want to save.

3. Select Save request.

   

4. Choose the collection to add the request to, then select Save.

Alternatively, select + next to the request.

Managing collections

Basic actions

From the list of collections in your workspace, you can:

• Select a collection to open its overview in a tab.
• Open and close collection content by selecting the arrow next to the collection name.
• Hover over a collection name and select the star icon ★ to move that collection to the top of the list.
• Use the collection search bar to filter through your collections.
• Reorder the requests, folders, and examples inside a collection by dragging and dropping them.

Adding folders to a collection

1. Select the more actions icon next to the collection name.
2. Select Add folder.

You can also add sub-folders to create extra levels of nesting for the collection's requests and examples.

Deleting a collection

1. Select the more actions icon next to the collection name.
2. Select Delete.

You can also select the collection and press Delete on your keyboard.

If a deleted collection is larger than 30 MB, you won't be able to recover it. To avoid this, you can split the collection into smaller pieces before deleting it, or back up the collection first.

Recovering a deleted collection

1. Select the more actions icon next to the collection search bar.

2. Select Open Trash.

   Alternatively, select Trash from the Postman footer.

3. In the Trash page, select the restore icon next to the collection you want to recover.

Deleted collections that are larger than 30 MB can't be recovered.

Recovery options depend on your Postman plan:

• Free account: Recover collections for up to one day.
• Postman Basic: Recover collections for up to 30 days.
• Postman Professional and Enterprise: Recover collections for up to 90 days.

If a collection that you expected to be in the Trash isn't there, it may have been removed from a workspace rather than deleted. If the collection appears in another workspace, you can move it by selecting Share.

Sharing a collection

To share a collection with other users, you can:

• Publish a Run in Postman button.
• Invite others to collaborate by selecting the more actions icon next to the collection name, then selecting Share. Learn more about sharing elements in Postman.
  • To share a URL to a collection, folder, request, or example with an active environment selected, choose an environment using the environment selector, copy the element's link to your clipboard, then send the link to team members you want to share with.
• Allow external users who aren't in your Postman team to view collections by selecting the more actions icon next to the collection name, selecting Share, then turning on the toggle next to Allow Guests to join your team and view this collection with the link. Learn more about allowing external users to view collections.
• Move the collection to a shared workspace by selecting the more actions icon next to the collection name, then selecting Move. Learn more about moving Postman elements.
• (Enterprise) Add the collection to your team's Private API Network.

Tagging a collection

Tagging collections is available on Postman Enterprise plans. You can apply shared tags to workspaces, collections, and APIs. Tags must be between two and 64 alphanumeric characters, starting with an alphabetic character, and contain only dashes and no spaces. You can add up to five tags.

Adding shared tags to collections enables you to organize and search for collections.

Once you add tags to the collection, you can select a tag to open search results associated with the tag in a new tab.

To learn more about searching using tag names in Postman, see Search Postman. You can also search using tag names in the Private API Network when searching elements in the network, elements to add to the network, and elements to request to add to the network.

To add tags to a collection, do the following:

1. Select Collections in the sidebar.

2. Select a collection.

3. Select the Tags section to edit it.

   

4. Select an existing tag or enter a new tag. If you're adding a new tag, enter the new tag name and then select Create "tag-name".

   

5. Select the area outside of the Tags section to save your changes.

To remove tags from a collection, do the following:

1. Select Collections in the sidebar.

2. Select a collection.

3. Select the Tags section to edit it.

4. Select the close icon next to a tag.

   

5. Select the area outside of the Tags section to save your changes.

Watching a collection

When you watch a collection, Postman notifies you when a workspace team member makes changes to the collection, including adding a new request, modifying the existing requests, adding or updating variables, editing pre-request scripts or tests, and adding or deleting a folder. You can watch a collection that you own, as well as collections in any public workspace.

To watch a collection, do the following:

1. Select the watch icon to start watching the collection.

To view notifications about what has changed in a collection you watch, do the following:

1. Select the notifications icon in the Postman header to view the notification. Select View changelog to view the collection's changelog.

   

2. You will also receive an email with the information regarding who made the change, what the change was, and when it was made. Select View changelog in the email to access the full changelog in Postman.

If you create a collection and change it from the same Postman account, you won't receive notifications for any changes you make to that collection.

Forking a collection

You can fork collections in your own workspace to develop collection versions.

1. Select the more actions icon next to the collection name.
2. Select Fork.

Alternatively, select the fork icon from the collection overview.

Adding comments to a collection

1. Select the comments icon in the right sidebar and enter your comment.
2. (Optional) Select the Watch collection checkbox to be notified when there are changes to the collection.
3. Select Comment to add your comment.

To learn more about using comments to collaborate on collections and requests, go to Comment on collections, folders, and requests.

Reverting collection changes

To revert your collection to an earlier state, do the following:

1. Select the changelog icon on the right.

2. Select a session to expand it.

3. Select the more actions icon next to the change you'd like to restore your collection to, then select Restore to this change.

   

Restoring a collection from the changelog reverts it to the point immediately after your selected change occurred.

Viewing pull requests, forks, and collection details

From the right sidebar:

• To view pull requests for a collection, select the pull request icon
• To view forks created from a collection, select the fork icon
• To view more information about the collection, including mock servers, monitors, and integrations, select the information icon

Using collections in development workflows

Collections can power various parts of your API development, testing, and publishing workflows.

• Select Run to access the Collection Runner, which allows you to run all requests in a collection and build testing workflows into your runs.
• Select View complete documentation in the collection's Overview tab to generate documentation from a collection.
• Attaching a monitor to a collection lets you schedule collection runs. Select the more actions icon next to the collection name, and then select Monitor collection.
• You can use mock servers to return sample data during testing and development. Select the more actions icon next to the collection name, and then select Mock collection.
• Generate collections from API specifications using the Postman API Builder.

Using collection templates

Not sure where to start when creating a collection? Instead of starting from scratch, you can create a collection from a template. Several collection templates are available for getting started with integrations, API documentation, conditional workflows, or data visualization.

There are several ways to create a collection from a template:

• When you first create your account, you will be asked if you want to create a collection from a template.
• In an empty workspace, in the left sidebar, select Use a Template.
• Select New, then select Use a template.
• In an empty collection, on the Overview tab, select a template.

About multi-protocol request collections

You can also save multi-protocol requests, such as WebSocket and gRPC requests, into collections.

Because multi-protocol requests have different features than HTTP requests, when they're saved to a collection, it causes the collection to be in a "beta" state with certain limitations.

When in this state, a collection can only contain WebSocket or gRPC requests, and not HTTP requests. Some features related to collections also aren't supported.