Managing and sharing APIs

When you define your APIs in Postman using the API Builder, each API is associated with a workspace. You can share access to your APIs, discuss them in comments, and view schema activity.

Sharing APIs

You can share your APIs with collaborators by navigating to the API you'd like to share in the left sidebar. Select it, then select Three dots icon > Share.

Share api

For more details, see Sharing Postman entities.

Collaborating on APIs

You can move APIs to shared workspaces to collaborate with your team.

You must be an editor on an API or the workspace admin to move the API to another workspace.

Navigate to the API you'd like to share in the left sidebar, select it, then select Three dots icon > Move.

Use the search bar to find the workspace you'd like to move the API to, or filter by workspace visibility by selecting the icon to the right of the search bar.

You can share APIs to personal, private, team, and public workspaces that you have access to. Shared private, team, and public workspaces allow you to collaborate with others.

You cannot move APIs from team, private, or public workspaces to a personal workspace.

Refer to Roles and permissions for information on workspace access control within your team.

Select the workspace, then Move API.

Move API

Note that collections, documentation, monitors, mock servers, and environments of the API will not move with the API to the new workspace automatically.

Collections and environments must be moved separately. Documentation, monitors, and mock servers must be re-configured in the new workspace.

Watching APIs

The watch option enables you to receive an email or in-app notification when a team member belonging to the same workspace modifies the API, for example updating the schema, attaching an element to the API, adding a comment to the API and so on.

Select Watch to start watching the API.

Watch Option

Click the bell icon on the top right corner to view the notification. The popup will indicate further information about the change that was made to the API.

Notification Watch API

You will also receive an email with the information regarding who has made the change, what the change was, and when it was made.

You will not receive notifications for changes made by yourself.

Commenting on APIs

You can discuss your APIs with collaborators in Postman, keeping the conversation in context and available to other stakeholders. Anyone with access to the API can comment.

To leave a comment on an API, open APIs in the left sidebar and select the API version you want to comment on. Switch to comment mode, enter your comment, and Add comment to publish it.

api comment app

You can leave inline comments on the API schema by highlighting what you want to comment on.

Formatting comments

You can use Markdown in your comments—check out the Markdown Cheatsheet on Github for tips on formatting.

If you want to call the attention of a collaborator in comment, you can tag them by typing @ followed by their name—choose the person from the auto-suggested list. When you tag a member in your comment, Postman will send them a notification.

Editing, deleting, or linking to a comment

To edit, delete, or link to one of your comments, navigate to the comment section and hover over the comment you wish to manage. Click the pen icon to edit the comment, the bin icon to delete, or the anchor icon to get a direct link to the comment.

api comment manage

With Admin permissions you can delete comments made by any contributor, but you cannot update or modify comments.

Using the Changelog

You can view a changelog of your API schemas and all linked collections in the context bar. You can also create releases of an API from the changelog.

To see the changelog, open an API version, then click the changelog icon. (Changelog icon)

You will see a list of changes made to the schema and associated elements. Each release is shown, and the top of the list will show any unreleased changes. Click to expand each entry for more details.

Select + Release changes at the top of the list to create a release from unreleased changes. For more information, see Working with API releases.


Next steps

For more info on working with the API Builder in Postman, check out the following resources:

Last modified: 2021/12/12