Manage element tags programmatically with the Postman API

David Espi Hernandez

November 8, 2023

Postman Enterprise users can now add tags to collections, workspaces, and APIs. Tags help improve organization, collaboration, documentation, discoverability, and productivity.

You can manually manage element tags in Postman, but did you know that you can also do it programmatically with the Postman API? We’ve recently exposed the following tag-related endpoints:

• Collection tags: Manage your collection’s tags with the /collections/:collectionId/tags endpoint.
• API tags: Manage API tags with the /apis/:apiId/tags endpoint.
• Workspace tags: Manage workspace tags with the /workspaces/:workspaceId/tags endpoint.
• Search for elements by tag: Search by tag across all of your Postman elements with the /tags/:slug/entities endpoint. The response contains a paginated list of elements with the given tag. We use cursor pagination on this endpoint, and you can also filter your search by workspace, collection, or API.

With these new endpoints, you can:

• Add an under-review tag to an API when you create a new version with the Postman API. You can then share this tag with your stakeholders so they can easily filter elements that contain that tag:
  
• Get all APIs that contain the under-review tag and send them to a Slack channel.
• Automate cleanup tasks. For instance, you can delete all elements (i.e., workspaces, APIs, and collections) that contain a specific tag, like to-delete.
• If a monitor fails, mark its collection with a tag so it can be easily found.

A collection that deletes elements with a specific tag

We’ve created a Delete Postman Elements by Tag collection that deletes any collections, APIs, and workspaces that contain a given tag. The collection uses the Search elements by tag endpoint—and then uses the DELETE endpoints for workspaces, collections, and APIs. Basically, it gets all elements containing the tag, then iterates on deleting all of collections, APIs, and workspaces that contain that tag:

To delete all elements with a specific tag, open the collection’s Variables tab, enable the tag variable and provide the tag you want to use, and run the collection:

The collection run results will display. If the collection finds an element with the given tag (like the delete tag), you’ll see that the collection deleted the elements that had the given tag:

How are you using tags in Postman?

This is just one example of how you can automate your tag management with the Postman API and streamline your development process. Do you have a specific use case? How would you use the Postman API to tag your elements and work with these tags? Let us know in the comments!