- Introduction
- Installing and updating
- Navigating Postman
- Sending your first request
- Managing your account
- Syncing your work
- Discovering templates
- Creating your first collection
- Creating a workspace
- Setting up your Postman app
- Importing and exporting data
- Troubleshooting app issues
- Building requests
- Authorizing requests
- Receiving responses
- Grouping requests in collections
- Using variables
- Managing environments
- Visualizing responses
- Specifying examples
- Using cookies
- Working with certificates
- Generating client code
- Troubleshooting requests
- Using the Collection Runner
- Scheduling runs with monitors
- Building request workflows
- Importing data files
- Working with your team
- Defining roles
- Requesting access
- Sharing your work
- Your Private API Network
- Commenting on collections
- Versioning APIs
- Using version control
- Using the API Builder
- Managing and sharing APIs
- Validating APIs
- Monitoring your APIs
- Setting up a monitor
- Viewing monitor results
- Monitoring APIs and websites
- Set up integrations to receive alerts
- Running Postman monitors using static IPs
- Troubleshooting monitors
- Monitoring FAQs
- Analyzing with reports
- Documenting your API
- Authoring your docs
- Publishing your docs
- Viewing documentation
- Using custom domains
- Publishing templates
- Publishing to the API Network
- Submission guidelines
- Managing your team
- Purchasing Postman
- Billing
- Configuring team settings
- Utilizing audit logs
- Onboarding checklist
- Migrating data between teams
- Intro to SSO
- Configuring SSO for a team
- Logging in to an SSO team
- Microsoft AD FS
- Custom SAML in Azure AD
- Custom SAML in Duo
- Custom SAML in GSuite
- Custom SAML in Okta
- Custom SAML in Onelogin
- Custom SAML in Ping Identity
- Migrating to the current version of Postman
Versioning APIs
You can manage multiple versions of any APIs you create in Postman. You can link collections, mocks, monitors, and documentation to specific versions of APIs using version tagging.
To use versioning with your APIs, you need to carry out the following steps:
- Link your API to a collection
- Add version tags to your collection
- Update version tags on API changes
You can access versions in the API Builder, by opening APIs and selecting the API you want to work with.
Creating API versions
When you create a new API in Postman, it will initially have Draft
version.
You can create new versions from scratch or from an existing version. Click Show All Versions.

From here you can rename and delete versions—deleting a version will also delete its version tag.
To create a new version, click Create another version.

Enter a version name. If you want want to base this version on an existing version select it from the dropdown list, otherwise choose Don't carry over any elements. If you are basing your new version on an existing version, check any elements you want to connect to the new version. Click Create Version.
Your new version will open in the API Builder.
Updating versions
Postman automatically updates the version tags for linked collections whenever you update the API version. If you add a new version to the API, Postman will also add that version tag to the collection.
You can tag your collection revisions to match changes in your API. For example, if you update the API, which results in a revision of the collection, you can then link the updated collection (or documentation) to the new version of the API.
If you have collections with specific version tags, Postman will associate them with the appropriate API versions by default. Due to this automatic behavior, Postman does not allow you to manipulate the version tags of a collection linked with an API manually.
If an API version is incremented, for example from 2.0 to 3.0, and you choose to Carry over elements from a previous version, but the collection is not tagged to API version 3.0 yet, Postman will display a warning, since there is no equivalent version tag on the collection corresponding to API version 3.0.
To resolve this, add a corresponding version tag to the collection.
When you update an API version number and choose to carry over elements from a previous version, Postman provides you a list of elements that you need to update in order to match the new API version. This makes the API Builder your central dashboard to manage changes across all of your API elements.
Connecting linked elements to versions
You can link elements such as collections to a version of an API, by adding either documentation or a test suite in the API Builder.
When you add a mock or a monitor to an API, the underlying collection also gets linked to the API.
To link a collection to an API version, navigate to the Collections tab in the sidebar, expand the arrow (▸) to show the details view for the collection, open the Changelog, and click Add Version Tag.

Choose the version of the API you want to connect to and how you want the collection to be linked.

You can also add version tags to your collections from the Postman web dashboard.
You can create and run mocks and monitors on tagged revisions of your collections. You can also create and publish documentation from the tagged revisions of collections.
Monitors, mocks, and documentation are always associated with specific versions of a collection.
- The version tags of monitors and mocks linked to versioned collections do not update automatically. If you update the version of an API you're monitoring, you need to create a new monitor linked to the new version as your original linked monitor will run on the original collection.
- Documentation version tags automatically update along with your API.
You can publish specific versions of collection documentation.
Next steps
For more on working with the API Builder, check out the following topics: