Your API in Postman can include more than an API definition. You can add elements such as collections to help you document and test your API.

When you add a collection, an independent copy of the collection is added to the API. The copy in the API will no longer be in sync with the original. If you move or delete an API, any collections contained in the API are moved or deleted with it.

Add a collection to your API

Add a collection to document your API or help others test your API’s endpoints. You can add an existing collection or generate a new collection from your API definition.

Note that you can’t usetypes in a collection that’s linked to an API. If you copy an existing collection to your API, types won’t be available from the copied collection.

You can also add a test suite to your API. Learn more abouttesting an API.

Copy an existing collection to your API

To copy an existing collection to your API, do the following:

1. ClickAPIs in the sidebar and select an API.
2. On the API’s overview, next toCollections, clickAdd a collection and selectCopy existing collection.
3. Select an available collection and clickCopy Collection.

The copy of the collection displays on your API’s overview and under your API in the sidebar. To view documentation for the collection, select the collection and clickView complete documentation.

Generate a new collection from your API definition

To generate a new collection from your API definition, do the following:

1. ClickAPIs in the sidebar and select an API.
2. On the API’s overview, next toCollections, clickAdd a collection and selectGenerate from definition.
3. Name your collection.
4. Select the checkbox if you want Postman to suggest updates for the collection when the API definition changes. This checkbox is selected by default. Learn more aboutkeeping a collection in sync with your API.
5. Change any settings to customize the new collection.
6. ClickGenerate Collection.

The collection displays on your API’s overview and under your API in the sidebar. To view documentation for the collection, select the collection and selectView complete documentation.

You can also generate a collection when you import an API. For more information, seeimporting an API.

Add a new collection to your API

To add a new collection to your API, do the following:

1. ClickAPIs in the sidebar and select an API.
2. On the API’s overview, next toCollections, clickAdd a collection and selectAdd new collection.
3. Enter a new name for the collection.

Keep a collection in sync with your API

When yougenerate a new collection from your API definition, Postman creates a collection with requests that match what’s defined in the API. If you update the API definition, for example by adding a path, those changes won’t be reflected in the generated collection.

In this case, you could repeat the process of generating a collection from the API definition. However, this new collection wouldn’t include any changes you might have made to the first collection you generated. For example, you might have added documentation content or endpoints for test setup that you want to keep. Instead, Postman can offer suggestions for updating the collection based on the changes to the API definition.

Collection update suggestions are supported for OpenAPI 3.0 and 3.1 definitions.

Enable update suggestions for your collection

You can enable update suggestions for any collection that’s been added to an API. When suggestions are enabled, Postman will detect when there are differences between the API definition and the collection and will offer suggestions for updating the collection.

To enable update suggestions for your collection, do the following:

1. ClickAPIs in the sidebar and select an API.
2. On the API’s overview, clickView more actions next to a collection and selectEnable update suggestions from definition.

If you want to turn off suggestions, clickView more actions next to a collection and selectDisable update suggestions from definition.

Update your collection based on your API definition

When suggestions are enabled,Update collection appears next to a collection if Postman detects differences between the collection and the API definition. Differences can occur if the API definition is changed, for example by adding, removing, or modifying endpoints. Differences can also occur if requests are added, removed, or modified in the collection. You can review the differences and, if you choose, update the collection with the suggested changes.

To update your collection based on your API definition, do the following:

1. ClickUpdate collection next to the collection on the API’s overview.

   

2. Review the suggested updates to the collection:

   • Add requests - These requests will be added to the collection based on paths found in the API definition. Click the arrow next to a request for more details.
   • Modify requests - These requests will be updated to match the paths in the API definition. Click the arrow next to a request for more details.
   • Remove requests - These requests don’t match any paths in the API definition. Select the checkbox next to a request if you want to remove it from the collection. Clear the checkbox next to a request if you want to keep it in the collection.

3. When you’re ready to make the suggested updates to the collection, clickUpdate Collection.

Suggestion triggers

The table below lists changes you can make to API definitions, and it notes which changes will result in a suggestion if collection update suggestions are enabled.

Fork a collection from your API

Collections added to an API can’t be used with monitors, mock servers, or CI integrations. To use a collection in an API with these features, you must fork the collection.

To fork a collection from your API, do the following:

1. ClickAPIs in the sidebar and select an API.
2. Select the collection in the sidebar.
3. ClickFork in the upper right.
4. ClickFork Collection.

Learn more aboutforking elements in Postman.

Delete a collection from your API

To delete a collection from your API, do the following:

1. ClickAPIs in the sidebar and select an API.
2. In the sidebar, ClickView more actions next to a collection and selectDelete.

You can also delete a collection from the API’s overview. ClickView more actions next to a collection and selectDelete.

• On this page

• Add a collection to your API
• Keep a collection in sync with your API
• Fork a collection from your API
• Delete a collection from your API