Add elements to an API in Postman

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.

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

Copy an existing collection to your API

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

1. Select APIs in the sidebar and select an API.
2. On the API's overview, next to Collections, select + and select Copy existing collection.
3. Select an available collection and select Copy 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 select View complete documentation.

Generate a new collection from your API definition

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

1. Select APIs in the sidebar and select an API.
2. On the API's overview, next to Collections, select + and select Generate 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 about keeping a collection in sync with your API.
5. Change any settings to customize the new collection.
6. Select Generate 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 select View complete documentation.

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

Add a new collection to your API

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

1. Select APIs in the sidebar and select an API.
2. On the API's overview, next to Collections, select + and select Add new collection.
3. Enter a new name for the collection.

Keep a collection in sync with your API

When you generate 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. Select APIs in the sidebar and select an API.
2. On the API's overview, select the more actions icon next to a collection and select Enable update suggestions from definition.

If you want to turn off suggestions, select the more actions icon next to a collection and select Disable update suggestions from definition.

Update your collection based on your API definition

When suggestions are enabled, the update collection icon 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. Select the update collection icon 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. Select the arrow next to a request for more details.
   • Modify requests - These requests will be updated to match the paths in the API definition. Select 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, select Update 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.

Change	Suggestion
Add an endpoint	Yes
Remove an endpoint	Yes
Remove a path parameter	No
Add a required query parameter to an endpoint	Yes
Add a required property to the request body	Yes
Change the data type of a request body property	Yes
Update the request summary	Yes
Update the request description	No
Add an example response	Yes
Remove an example response	Yes

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. Select APIs in the sidebar and select an API.
2. Select the collection in the sidebar.
3. Select the fork icon at the upper right.
4. Select Fork Collection.

Learn more about forking elements in Postman.

Delete a collection from your API

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

1. Select APIs in the sidebar and select an API.
2. In the sidebar, select the more actions icon next to a collection and select Delete.

You can also delete a collection from the API's overview. Select the more actions icon next to a collection and select Delete.